for agents: this page is markdown at https://switchyard.so/docs/api.md; every page is listed in llms.txt.
REST API
Every project answers under https://app.switchyard.so/v1/projects/<project>; the paths below are relative to it. Send your key as a header, Authorization: Bearer <key>: an admin key for the project, a task key for one task, an agent group key for many agents at once, or a signed-in person's session from the app. Answers are JSON and carry seq, the position in the project's history; errors carry { "error": { "code", "message", "hint" } } as the errors page lists. A 503 with a Retry-After header means wait that long: send a read again, and send a write again only when the answer also carries X-Switchyard-Not-Applied: 1, which says it was refused before anything was done; after a 503 without it, read the project's state to see whether the write landed before sending it again. A 429 is always refused before anything is done.
Paths say workspace where the product says task; the ids are the same (W8, 8 or task 8 are all accepted wherever a task is named). This page is rendered from the design document's route table, so it changes when a route does. For machines, every public route, the organization and account routes included, is in the OpenAPI document, and the parity page names each one's yard command and MCP tool.
| Method | Path | What it does |
|---|---|---|
| GET | (the project itself) | { seq, project }: its id, name, branch, main, remote and, when it follows one, its GitHub repository; POST /v1/projects answers the same project with the admin key |
| POST | /v1/projects (not under a project) | Create a project: { id, name?, github?, branch?, importUrl?, organization?, team?, reviews?, fixes?, taskPermission?, checkNetwork?, rules?, proposedRules?, storage? }. id is 2 to 63 lowercase letters and digits in groups joined by single dashes. github (owner/name) follows that GitHub repository on branch, its default branch when absent, and cannot come with importUrl, a public Git URL to import; with neither, main starts with one empty commit on branch (main when absent). storage is Switchyard's alone to send, and anyone else who sends it gets 403. A signed-in owner or admin of the organization (who must administer the repository on GitHub to send github) creates a project, and so does an organization API key with admin access, in its own organization and never with github. Answers 201 { seq, project, adminToken }, with the admin key shown once; with Prefer: respond-async, 202 { id, status: "creating", poll, startedAt, adminToken }, and GET /v1/projects/:project/creation says when it is ready. 401 when no one is signed in, or when the organization API key is not valid. 404 when the Switchyard GitHub App is not installed on the repository, when GitHub has no repository by that name that the app can read, or when the team named does not exist. 409 when GitHub has no branch branch ("push a first commit to it on GitHub"), when another project already follows the repository (naming it), or when the id is taken ("project id already exists"; where people sign in, "the project id id is not available"). 400 for a body the route cannot use, and 403 for a caller who may not create it, each naming the reason |
| GET | /me | Which principal the key or session is: { kind, workspace?, user?, fleet?, otherClients? } (kind is fleet for an agent group key, or workspace with fleet for the MCP session of one that claimed a task; otherClients: [{ name, seenAt }] only to a task's own key through the MCP server, when another MCP client's name used the key in the last 10 minutes: MCP, below) |
| POST | /admin-key/rotate | Issue a new admin key for the project (project admin: a person with admin access to the project, in a browser signed in within the last 15 minutes. No key rotates it, the project admin key included, and a yard or MCP sign-in is answered approval_required with the project's settings page); every earlier admin key stops at once, with no grace period, since a rotation is usually for a leaked key. Answers { seq, adminToken, revoked }, with the key shown once, and records project.admin_key (the count only, never the key), which cannot be undone; it is also written to the organization's audit log. The board's settings page has the button, and the audit log names who rotated |
| POST | /fleets | Issue an agent group key (project admin): { name, tags?, permission?, maxWorkspaces?, ratePerMinute?, expiresInDays? }, permission the project's taskPermission when absent, and a looser one refused as a looser task permission is; answers { seq, fleet, token } with the key, which is shown once, and records fleet.create; fleet carries expiresAt, and once known lastUsedAt, disabledAt, rotatedAt and previousValidUntil |
| POST | /workspaces/:workspace/key | Replace a task's key when it may have leaked (project admin or a developer of the project's team; the task's own key and any other task's get 403, so a leaked key cannot lock out its agent). The old key stops at once, live connections made with it end on their next message, and the Git keys it minted are revoked at the host; an active task gets a new key, answered once as { seq, workspace, token, ended, gitTokens }, and a merged or abandoned one gets none (token absent): its key ends now instead of seven days after the merge. Records workspace.key_replace without the key, which cannot be undone. The same as yard branch key <task>, the MCP tool yard_task_key and the task page's "replace its key" |
| POST | /fleets/:fleet/rotate | Issue a new secret for the agent group (project admin), { graceMinutes?, expiresInDays? }: the old secret works for graceMinutes (60, at most 10,080); answers { seq, fleet, token } and records fleet.rotate, which cannot be undone |
| POST | /fleets/:fleet/disable, /fleets/:fleet/enable | Stop or restart an agent group key and its tasks' keys without revoking it (project admin); answers { seq, fleet } and records fleet.disable or fleet.enable |
| GET | /fleets | The project's agent group keys (project admin), each with the tasks it created and how many are active |
| POST | /fleets/:fleet/revoke | Revoke an agent group key (project admin), { abandon? }: records fleet.revoke once, and with abandon abandons the agent group's active tasks; answers { seq, fleet, abandoned } |
| POST | /workspaces/claim | The MCP session of an agent group key claims its task: { task, plan?, tags?, agent?, model?, resume?, parentTask?, continues?, requestId? } (continues: the design document, Continuing a merged task), with the MCP session as its session; answers { seq, claimed, workspace, credentials, resume } without a task key. requestId (or the Idempotency-Key header, the same value; both and different is 400) keys the claim as it keys a create: a claim sent again with it, from any session of the agent group key, takes the task it made (claimed: "existing"), and with a different request (task, agent, model, tags, parent task or continuation) is 409; at the project's ceiling the claim answers as a create does (Admission of new tasks) |
| DELETE | /workspaces/claim?requestId= | Give up a claim by its key, as DELETE /workspaces does for a create |
| DELETE | /workspaces?requestId= | Give up a create by its key, only by the key that sent it (a task key, or the MCP session bound to a task, what its own task sent; an MCP session of an agent group key its own claims; the raw agent group key what it sent itself; a person or developer key what they sent), and a task never by an agent group key, raw or through a session with no task: answers { seq, requestId, given, workspace? }, given being abandoned (the task the key made, abandoned as the abandon op does, at its base; 409 "abandon it by its id" once anything but its create, the plan it gave and the judge's decisions on it is recorded on it, a Git key was asked for it on its own (POST /credentials, a claim resumed) or its copy of the repository holds a commit past its base, recorded or not), finished (it had merged or been abandoned already), queued (the key left the admission line) or on its way (its task was being made and will not be); the key is remembered for a day for whoever gave it up, so their send of it again is 409; a key never seen is 404 and is remembered the same way, since a create can come after its give-up; anyone else's key is 403; a requestId and an Idempotency-Key header that differ are 400 |
| POST | /workspaces | Create a task (project admin, a developer of the project's team, an agent group key: Fleets, or a task key for a subagent's task of its own task: the design document, Subagents with a task key), with optional tags, session, parentTask, continues and permission (the project's taskPermission when absent, submit unless changed); returns remote URL, key, permission; 409 while main has no commits yet or the host's default branch is not the project's. The copy of the repository and its key are made outside the coordinator's lock, and the task starts at the commit the copy of the repository copied. The same requestId sent again within a day returns the task it created, with fresh credentials, instead of a second task (409 if the request differs, tags included, if someone other than its maker sends it, or if that task has finished; 503 not-applied if it finished while its keys were made). The Idempotency-Key header is the same key: sent alone it is the requestId, and sent with a different requestId it is 400. At the project's ceiling a create sent with the Idempotency-Key header answers 202 { queued, atCapacity, saturated, position, etaSeconds, request } with Retry-After, x-switchyard-queued: 1 and x-switchyard-at-capacity: 1 (admission at capacity, never a failure), nothing made, and the same request sent again after Retry-After keeps its place; keyed by its body's requestId alone it keeps its place the same way and answers 503 not-applied with Retry-After and x-switchyard-at-capacity: 1; without a key it is 503 not-applied with x-switchyard-at-capacity: 1 (Architecture, Admission of new tasks). A create a fault no refusal names ended answers 503 with x-switchyard-outcome-unknown: 1, not known whether it was made: sent again under its key it makes the task once; sent with no key, read the tasks first (Retries). The answer carries no warnings: a plan given is compared after it (the task named in the judging queue in the create's own write, so a restart before the comparison ends compares it on the next start), and its warnings arrive through GET /warnings, the status and the live feed. Where people sign in, a key no person is behind (the raw project admin key, or an agent group key no person made) names no assignee: 403, before anything is made |
| POST | /workspaces/:workspace/tags | { set?, remove? }: merge tags into the task's and drop the keys named; answers { seq, workspace, tags }. Records workspace.tag unless nothing changes; 400 past 16 tags or 1,024 characters, or for a key both set and removed |
| PUT | /workspaces/:workspace/plan | Set or update the plan; returns the task's intent warnings from comparing the new plan with the tasks it may meet, in bounded steps outside the coordinator's lock; the judge's verdicts on the pairs that need one follow on the judging queue, through GET /warnings, the status and the live feed, and the call never waits for them. On a project whose comparison runs on its overlap shard, the call waits at most 2 s for the shard and answers analysing: true if it has not finished: no warning then does not yet mean no overlap |
| GET | /status?min_seq=&workspace=&tag= | The ProjectState with groups, its tasks grouped person → session → subagents → tasks (TaskGroup[]: { person, sessions: { session, tasks: { workspace, subagents? }[] }[] }, where a task whose parent is listed sits under that parent whatever session or person started it, people by login with the unassigned last, sessions by their first task with the tasks made without a session last); with workspace, that task, its parent and its subagents' tasks (every open one and the 20 that finished last, with subagentsMore counting the rest) join the ones it is stacked on or under, without groups. The state carries activity while the project is doing something that takes more than a moment: a list, most important first, of { kind, sentence, progress?: { done, total, unit }, secondsLeft?, since? }, where kind is waking, moving, copying, history, applying or testing, and the sentence is the one the board, yard status and yard_status all show; the engine's waking is told by the engine, with the bytes it loads (every pack and the indexes kept beside it) and, once a whole load has been timed, its seconds left counted down from when it was told, and forgotten after two minutes without news. It lists every active task and the 20 most recently finished, with olderFinished when there are more; the inbox lists active tasks only. With workspace, the same shape for one task: the task, the tasks it is stacked on and every active task built on it, with the tasks in between (finished ones included), the warnings involving it and its inbox items. With tag=key:value (repeated, ANDed; not with workspace), the same shape for the tasks carrying those tags: the tasks, the warnings involving any of them and their inbox items, with the whole merge queue. With logs=tail, each check's log in the merge queue's test builds and in what a task's checks ran while waiting is its last 4,000 characters from a line's start, after a line saying earlier lines were left out: the board asks for it, since it shows a check's last lines and its first error, and the whole logs of a busy merge queue made every read megabytes long; yard check log and the full-log download read the whole log. Every form answers with a weak ETag and answers 304 to a matching If-None-Match (see "Live state": the view behind the status). The MCP yard_status without a task lists a line per task and the warnings grouped by kind and tasks (MCP tools) |
| GET | /workspaces?status=&before=&limit=&tag= | status=active (the default): every active task. status=finished: finished tasks older than the cursor, newest first, up to 100, with the next cursor. Both answer { seq, workspaces } and take the status's tag filter; the active page also carries groups, as the status does |
| GET | /workspaces/:workspace/warnings | Warnings involving a task, with suggestions, and the head they are about, so a client can tell an answer about the head before its push; while the task is analysing it waits up to 30 s for the integration rebuild that analyses its head and wip, and answers analysing: true when that rebuild failed, ran past the wait or could not read the branch, so the warnings never read as none. Answers with a weak ETag (never the same while analysing) and 304 to a matching If-None-Match |
| GET | /pulls/:number | Where a pull request of the followed GitHub repository stands in the merge queue: state (queued, testing, waiting, held, merged, sent_back, refused or withdrawn), code (a stable reason code from the reasons page), reason (the sentence its status comment and switchyard queue check show), task, head, lane, position and merged; ?repository=owner/name, when given, must be the followed repository; not_found for a pull request never in the merge queue; every key of the project reads it |
| GET | /workspaces/:workspace/notice | Switchyard's note on a task, the one its pushes print as remote: switchyard: lines and every MCP reply to its key carries as notice: what Switchyard last changed on it and how to catch up, its merge queue state or why it was sent back, its conflicted files and up to two warnings; absent when there is nothing to say |
| POST | /workspaces/:workspace/claims | Claim paths or symbols; returns the task's intent warnings like PUT /plan, with its analysing |
| POST | /workspaces/:workspace/observe | Read the task's branch now, after a push, instead of waiting for the push event (which stays as the backstop); an abandoned task answers 409, since its pushes are not tracked, except one the reap abandoned as never used, observed with its own key within its copy of the repository's day, which is brought back first as by its credentials call (Retention). Continuation of merged tasks is behind the project setting continue_merged (PUT /continue-merged), on by default; off, a merged task answers 409 here (as does one on whose branch nothing new was pushed; the hint names yard_workspace_create with continues, or yard_workspace_claim for an agent group key's MCP session: the design document, Continuing a merged task) and its pushes are not tracked, with no branch read and no lock taken, its commits staying in the task's repository and its notice naming the merge. With it on, a push to a merged task (reported here, with its own key, or by the event) that builds on the merge (its history holds the head the task merged at, or the commit main reached with that merge, as when a person pulled main from elsewhere first) continues it as a new change: it opens again as working, its base the newest commit of the push that main holds, as for an active task's push, else the merge it holds (its log read with the branch, outside the lock, and the base worked out again from it under the lock when main moved meanwhile; a log or main's history that cannot be read is a read that failed, never a base on the merge), so its stack is its own new commits, as a task pushed while its merge landed stays open, the answer's note, the push's operation and the task's notice say "task N merged at X; your push continues it as a new change", and the task's continued says which merge it continues ("continued after merging as 4f1c2ab (action #42)"), as the board and yard status show, until it merges again. One merged task is continued once (plan, 4 Nov): with the setting on, the hint of a merged task's refusals (observe with nothing new, a write with its key) names a push to the task itself, never a new task with continues, or, while an open task continues it, that task's own branch, and a task whose repository was cleared names a new task from main; a push to it while an open task made with continues naming it starts at its merged head (stacked on it and made after its merge; a task stacked on it before the merge refuses nothing) is not tracked, answered 409 here and in the task's notice naming that task, so the commits stay in one task, and reconcile does not read that head again; and a create with continues reads the merged task again under the lock, so one a push continued meanwhile is refused and its new copy of the repository deleted. Any other push to it (a forced push of an older or rewritten head) is not tracked, answered 409 here and in the task's notice with why; whether a push builds on the merge is the engine's walk without a bound (ancestry, only a yes or no being an answer); where it gives none (a commit the store lacks, a shallow store's boundary, a host without the walk) one read of the log, 1,000 commits, is walked, and a push past it holding neither is refused, said as such, never sent again for ever, while a walk that fails is sent again. The merged task's branch is read outside the project lock: with nothing new the answer is 409 without the lock, so agents polling a finished task never queue behind the project's work; the lock is taken only to continue the task or record why not, and checks again under it, reading the branch there only where it was not read before the lock or the task merged again since, within 2 s, past which the push is answered not-applied and sent again. A read that fails answers 503 not-applied with Retry-After whatever the store said (busy, throttled, unavailable or invalid); by the event, the failure is the push's, so the engine's outbox sends it again. A push to a merged task whose event never came is caught by reconcile: each pass reads the merged tasks that still hold a live Git key (no other can push), as many as the active tasks it reads (200), in number order from a cursor kept in the store so passes in turn reach every one, outside the lock, eight at a time, and takes the lock only to continue a task or to record a refusal not yet recorded for that head; a read that fails waits for the next sweep. A push to a merged task whose event was lost is continued within an hour plus one sweep, unless the engine is unreadable, then at backoff pace: the passes go round in sweeps, each ended by task number alone, a sweep runs at reconcile pace (a pass a minute) until it has read every merged task with a live key (a key that expired within the last two hours counts, so a push made in a key's last hour is still read), and the next sweep is an hour after it, a task that merged meanwhile included, so the backstop costs about one read a task an hour; a sweep with a read that failed or a continuation that threw is followed by the next at backoff pace instead (a minute, then 2, 5, 10 and 15), until a clean sweep returns it to the hour, the count kept in the store across a restart; with nothing else to do, a project with such tasks keeps one reconcile an hour and never the idle steps between, and stops once none holds such a key. A push event to a merged task is read by its own recording, that task alone; refused or not, it also brings the next sweep forward and wakes reconcile at once, but at most once in five minutes, so pushing to a merged task every minute costs a read a push, never a sweep a push. It answers once the head the store holds is recorded (the workspace.push operation and the stack), without waiting for the engine: the integration rebuild that analyses the head (footprint, warnings) runs after the answer, and the task reads analysing until it lands; an observe that recorded nothing starts no rebuild |
| POST | /workspaces/:workspace/ops | Run an engine operation (sync, absorb, split, …); with expectHead, only if the task's branch is still at that commit (409 otherwise), after catching up with a push the coordinator has not seen yet |
| POST | /workspaces/:workspace/credentials | Mint a fresh Git key for the task remote (a task abandoned as never used is brought back first, within its copy of the repository's day: Retention; 402 at the organization's spending limit, 503 with Retry-After while the coordinator is busy); 409 once the task has been abandoned, or has merged with the project's continue_merged setting off (on, the default, a merged task's own key or anyone else who may takes a fresh key, as for an active one, for a push that continues it; off, the 409's hint names yard_workspace_create with continues) |
| POST | /main/credentials | Mint a read-only Git key for main (one hour), for anyone in the project, a merged task's read-only key included |
| POST | /workspaces/:workspace/submit | Freeze the task at its head and enqueue it on the merge queue (refused with nothing to merge, unresolved conflicts or an abandoned parent); expectHead names the head the caller pushed, and a task elsewhere is refused with 409 after the coordinator catches up with pushes it had not seen; the key of a task with commit permission gets 403. A task whose head is not analysed is submitted only after the integration rebuild has analysed it (its head alone: a newer wip does not hold a submit), waiting up to 30 s, so the merge queue never takes a head the coordinator has not analysed; in shapes old and a, a head whose rebuild failed, ran past the wait or could not read the branch is refused with 503 and Retry-After, naming the engine, and nothing is submitted, while in shape b only a head the engine could not read is refused so, and one the wait did not see analysed is recorded (below). Every submit takes this path: git push -o submit (which leaves a notice to submit again), a pull request labelled or pushed in PR mode (whose label is taken off, with a comment to add it again) and the resubmit after a conflict fix. again (yard submit --again, again on yard_submit) is accepted and has no effect today. The status's mergeQueue.commit of a sent-back task names the head it was sent back at, and the board asks before submitting one with nothing pushed since. A submit recorded that the merge queue has not read within 1.5 s (it reads a submit between passes, and a pass can wait 10 to 35 s on the engine) may answer 200 all the same: its mergeQueue is the merge queue's state as last kept before it read the submit, marked behind: true with reason, one sentence that the submit is recorded and in the merge queue, to be followed on the task's status, as a submit sent again while the task is still submitted does not queue it twice (SubmitMergeQueueState); a submit sent again while the task is still submitted answers the same way until the merge queue has read it, then with its state, never queuing it twice (one the merge queue sent back meanwhile is queued again). A submit recorded whose answer could not be read at all answers 503 not-applied with x-switchyard-recorded: 1: send it again for its state (Retries). A submit a fault no refusal names ended is never a bare 500: recorded at its head it answers so; otherwise 503 with x-switchyard-outcome-unknown: 1, not known whether it was recorded, and a resend records it once, never twice (Retries). In shape b a submit whose head the next rebuild on main has not analysed within the 30 s wait (every rebuild there is full: minutes over a thousand tasks) is neither refused nor held for that rebuild: the task's object records it (its kept job, split/task/kept.ts) and answers 202 with x-switchyard-recorded: 1, Retry-After (the seconds until that rebuild is due, when known), the task as it stands (still working, analysing) and mergeQueue empty, marked behind: true with reason, one sentence that the submit is recorded and waits for the head's analysis; the object submits it by itself once the head is analysed, never twice, as the caller who submitted (the row carries the submit's actor, so the operation names them and a person's submit of a commit-permission task is made as theirs; an agent's own is dropped there as on the project object); a row held at an older head is dropped then, its agent told the head moved; the row is never given up while its task is open, by any count of refusals or time waited, and neither is a push's own -o submit kept on the task's object or the project object (each try at most 2 minutes after the last, spread a quarter either way so rows refused together part; one still not queued 30 minutes after it was asked is alerted, recorded_submit_old, once and again each time its age doubles; a head that could not be analysed is told as kept and tried again, never as "submit again", and from its fifth try asks for a push), only ended by the task's abandon or end, a newer push, edit or undo of the agent's, the submit made, or a refusal for good, each told to its agent, while a move of the head by Switchyard (the merge queue's sync, a restack, its fix, and its own rewrite read from the branch after a restart) or by a person (a sync, a move, a conflict's resolve) carries the submit to the new head in the move's own write (project/kept-row.ts), in every shape (the 1,000 run of 18 November: three passing refusals dropped a recorded submit); a submit sent again meanwhile answers the same, and once the task is submitted answers it as it stands. A head the engine could not read is still refused 503. The recording needs no engine and no other object: an analysis read that is not answered in time records the submit all the same. wait (query, whole seconds 0 to 30) asks a shorter wait for the head's analysis than the route's 30 s, for a client whose own hold must fit the answer (the MCP's resend of a recorded submit); anything else leaves the route's wait |
| POST | /workspaces/:workspace/retry | Let a task the merge queue holds after its check failed again and again with no cause found (queue v2, FLAKY_HELD: its held reason) go once more: every build of it held or backing off is let go, its count kept, and the merge queue woken; at most once in ten minutes a task. A person on the team only (developer or admin): a task's or a group's key, an agent's account, an agent signed in over MCP and every organization key get 403, and so does the project admin key with no account where people sign in; a task with nothing held so, or retried in the last ten minutes, gets 409. Answers { "workspace", "retried": true } |
| GET | /changes/:change?version= | A change at its latest version, or the one version names: ChangeDetail with its task, subject and commit, every version recorded for the Change-Id (number, commit, task, when it was recorded, subject, and unavailable once its commit is known to be gone), the diff against its parent (files, base, truncated) and the reason behind it (agent, task, and the task plan's summary as plan). A version whose commit is gone answers with no files and unavailable saying why; an unknown change or version answers 404 naming the change; a version that is not a positive integer 400. Readable like /status |
| GET | /changes/:change/interdiff?from=&to= | What changed between two versions: { seq, change, from, to, rebased, truncated, files }. 400 unless from and to are two different version numbers; 404 for an unknown change or version, or one whose commit is gone, naming it. Readable like /status |
| GET | /conflicts | { seq, conflicts }: a ConflictView per conflicted path in each active task's stack, and the ones fixed or resolved within the last 50 operations; a fixed conflict names the step that fixed it (resolvedBy) and, when a person or an agent resolved it or accepted a proposal, who did (resolvedActor); an open conflict waiting on a person carries suggestion, ask when a person can ask for an AI suggestion (again) and off when AI fixes are off for the team. Readable like /status |
| POST | /conflicts/:change/resolve | Climb the conflict steps; expectHead leases it like a task operation, and the answer names the task's new head. In a task with two commits carrying the Change-Id it resolves the conflicted one, and answers 409 when both are conflicted. { "rung": "agent" } accepts the resolver step's proposals for the change's current version: the task's own key or a person (an admin or member) may, an agent group key that has not claimed the branch gets 403, and a version with no proposal answers 409. A version an agent accepted waits for a person's approval in the merge queue like a recipe fix (unless fixes is auto); a person's accept is the approval. An accept of the resolver step's proposal (agent) or of the file rules (recipe), sent without files, and a person's own resolution (human with files) are recorded before the engine writes them and answer within 15 seconds: when the engine has not finished by then it answers 202 with the usual fields and applying: true, finishes in the background, and GET /conflicts shows the conflict with applying: true until it is fixed; the same call for the same change meanwhile answers the same 202 and starts nothing, and a different fix of that change answers 409 until the first is written or not applied, so none is dropped. A refusal the caller sees at once (conflict markers, a moved head) leaves nothing behind. One the engine could not apply shows applyFailed: { reason, at, again }: with again (the engine was unavailable) Switchyard tries it again a minute later, up to three tries, and the conflict still shows applying; without it the suggestion stays to be accepted again. A person (an admin) sending { "rung": "agent" } for a version with no proposal asks for an AI suggestion instead and gets 202 { "asked": true, "paths": [...] }. "ask": true makes the call ask and nothing else, and a member of the project's team may send it too (accepting stays with an admin or the task's own key): a suggestion already there answers 409 instead of being accepted unseen, lockfiles alone answer 409, a task or agent group key gets 403, and ask with another step or with files is 400. The board's conflicts page and the overview's needs-you rows always ask this way. { "rung": "human", "files": [...] } is refused with 400 invalid when a file still holds a full conflict block in order (<<<<<<<, =======, >>>>>>>, each alone on its line or, for the outer two, followed by a space and a name), naming the file and line, hint "remove them and send it again" |
| POST | /review/:change/:version | Approve, comment or request a fix; the version names one commit, even in a task with two commits carrying the Change-Id. The project admin and members of the project's team review, and only a signed-in person approves: no key does, the project admin key included; a task key gets 403, its own changes included. The approver's teams are recorded with the approval; when the task's facts are known and touch owned paths, an approval answers with owners (each team, its paths, the approvals it needs and has, and whether this approval counted) and, while a team is still short, a note saying why |
| GET | /why?path=&line=&workspace= | Change, task, agent and plan that last wrote a line: a task key blames its own task head, an admin the live integration or the task it names. A line older than the history copied so far lands on the first copied commit; the answer then carries history, "history is still copying (2.1 of 4.3 GB)" or "history was not copied", instead of a change. A blame at a commit, once the history behind it is whole, is kept for 90 days in a cache keyed by the project, the commit, the path and the line, so the same question again does not wait for the engine; a deleted project's cached blames are purged with it; a task's plan has the files it names blamed ahead at main |
| POST | /live | A single-use ticket (60 s) for a live WebSocket connection |
| GET | /oplog?since= or /oplog?last= | Read the log: the actions after since, or from the newest last on (the board's first read, sent before the status has said how long the log is; last wins when both are given); at most 500 a page, with seq the newest. Each action carries sentence, the board's plain words for it (@login, task numbers, the merge preview), written from the record when it is read (the board and the server share one writer) and never stored, so a wording fix reaches old actions too. With logs=tail, each check's log in an action's arguments is its last 4,000 characters, as in /status |
| GET | /attestations/:commit | The attestation of a merged commit (7 or more hex digits): the signed text, signature, signer, whether it verifies and whether its note is on main |
| GET | /signer | The project's signing key and its allowed_signers line |
| GET | /insights?days= | Insights over the last 1, 7 or 30 days (default 7; another value 400), computed from the operation log (project admin or a member of its team): tasks started, submitted, sent back and merged, merges, approvals, submit to merge, start to merge and the wait for a review (median and the slowest tenth), the typical change size, counts per day, and per agent and model the same counts, send-back rate, conflict rate and submit to merge. A project admin's answer also carries coordinator, the coordinator's load as it stands: how many calls wait for its lock and for how long, the call holding it, per caller label the wait and hold of the calls it kept (count, median, 99th percentile, most), and what its status builds cost (ms, rows and statements read) |
| GET | /queue-health | The merge queue's health now, QueueHealth: one sentence the server writes, at most one thing that needs a person, and the numbers behind them over the newest 200 decisions (a task merged or sent back) of the last 24 hours: submit to merged (the median and, from 10 merged tasks, the slowest, from 100 the 99th percentile, by insights' own nearest-rank function), the share sent back, the tasks waiting and the oldest, the machine wait of finished tests, whether merging is paused, held by the spending limit, frozen or stalled, and the same per lane, with the thresholds each level was judged by. Computed from the operation log (the read model's rows of decisions where it answers), never from Analytics Engine. Readable like /status (a member, the project admin key, a task's key, an agent group key), read-only, and the same body for every reader: no amount of money, no person's name from billing, no link that acts. A field the records cannot give is null with its code in notKnown (which held tasks wait for a person; for records made before each was recorded, a spending-limit hold's begin and end, a merged task's lane and a send-back's cause code, the lanes and causes known in part counted in laneNotKnown and causeNotKnown; and the submit time of a task whose submit the log archived, which is counted and never left out: submit to merged is then not judged and gives no median, and the state is not_known unless the share sent back is amber or red). A task waiting more than 48 hours may be counted only from its next record. The one thing that needs a person names the kind of place that shows it (place), never an address. One answer is kept for every reader of a project for at most 5 seconds, with its true computedAt; a weak ETag over the body without computedAt, 304 to a matching If-None-Match, cache-control: private. 503 unavailable with Retry-After while a read model that existed before fills its decision rows (from its alarm, never by a reader), the refusal kept for 5 seconds as an answer is |
| GET | /value?days= | What Switchyard did for the project over the last 1, 7 or 30 days (default 7; another value 400), folded from the same records as insights (project admin or a member of its team; a task's key gets 403): ProjectValueResponse: tasks merged and submit to merge, broken changes kept out of main, conflicted files fixed by each step, check runs not made, flaky checks caught, each group with sources, the sentence naming the records it is counted from; nothing in it is estimated |
| GET | /spending-limit | The organization's spending limit as anyone on the project reads it, a person in full and an agent without an amount: SpendingLimitReadResponse (spending null, with its sentence, where no limits are set). Never the bill's amounts; an agent (a key, an MCP sign-in, an AgentID agent, an agent's run of yard) reads the percentage only, no limit in dollars and no logins, from the stored state, kept 30 s; nothing here raises it. Readable like /status |
| GET | /notifications | A person's open notifications of this project's reviews and tasks (ProjectNotificationsResponse), read without marking any seen or read: for a person's account, an agent signed in over MCP as its person included; a key reads an empty list and a sentence. |
| GET | /agent-approvals | Whether the organization lets an agent signed in as a person approve another person's unprotected change at once, recorded as agent for that person: { agentsMayApprove }, the project object's read of organization.agentsMayApprove (kept 30 s). False when the read fails or is not back in 2 s. yard_review's list carries it. Readable like /status |
| GET | /settings | Everything the project is set to, for the settings page (project admin or a member of its team; tasks get 403): the project (name, main branch, storage), the GitHub connection when it follows a repository (the app's granted permissions and events against what Switchyard needs, each gap with what it unlocks, links to fix it on GitHub, and when the last push and pull request event arrived), the rules file on main as read at which commit (found, missing or unreadable), its checks (a kept check turned off is listed with off: true, where it stands in the kept text, and a check that starts services lists them in services, each with its name, version, port and any host and env), the check network, and the values fixed for now. When the Git engine does not answer the rules read in 10 s, the page still answers: with the last rules read and rules.unread "…, so these are the rules as of main @ abc1234; reload to read the newest", or with empty lists and "…, so the rules on main are not read yet; reload to try again" |
| PUT | /pause | Pause merging, { "reason": "incident 42", "until"?: "2026-10-16T09:00:00Z" } (project admin; tasks get 403; an empty reason, an unreadable time, a time past or more than 30 days ahead get 400). Answers { seq, paused }. Records project.pause, which undo reverts, and wakes the merge queue |
| DELETE | /pause | Resume merging (project admin). Answers { seq, paused: null }; nothing is recorded when merging is not paused |
| POST | /feedback | An agent's one-way note to the Switchyard team when an answer confused it or cost it a retry, { "text": "…", "about"?: "yard submit", "expected"?: "…", "yardVersion"?: "0.2.9" } (any key that acts in the project, a member's too, a merged task's read-only key included; text 1 to 2,000 characters, about up to 100 and yardVersion up to 40 on one line, expected up to 500, no control characters but newlines and tabs in the text and expected, or 400). Answers { id, seq, kept: true }. The note is redacted of secrets and kept by Switchyard for its team to read; agent.feedback records the id, task, yardVersion and the text's length, nothing the agent wrote, since other agents read the history. 20 notes a caller and 200 a project each UTC day, then 429. Changes nothing in any task and is never returned by a read |
| POST | /copy-again | Copy the followed GitHub repository into Switchyard again after the first copy failed (project admin). While main has no commits, /status carries firstCopy: { state: "copying" | "failed", github, since, tries, reason?, nextTry? }; a failed copy is tried again every 15 minutes for an hour (five tries), then nextTry is gone and Switchyard waits for this call. A copy still running is checked every 15 minutes too: the engine runs one import of a repository at a time, so a check (as after a deploy restarted the project) joins the import already running and waits for it, and a join counts as the same try with the same start; an import that finished in the last 30 minutes answers again to a late check. An import answers every pack on the engine's disk that the project has not kept yet, not only the ones its own fetch wrote, so a pack left by an import whose caller died is kept on the next check; packs R2 already holds are not sent twice, and a first copy that names no pack is refused, logged as an error and tried again, never recorded. The object runs the import, and each history step, as an engine job that answers in its own call when it ends within 20 s and is otherwise asked about from 50 ms, twice as long each time up to every 3 seconds, so no call is cut for staying silent; a copy whose engine object restarted mid-copy can show failed while its import still runs, and the next check joins it. Main alone is no measure of the repository's size, so the first copy of main checks no room; the history copy does (/copy-history). Answers { seq, firstCopy } (the new copy's state, or null once main is copied); records project.copy_again only when it starts a copy. The same as yard copy-again and the MCP tool yard_copy_again. The first copy fetches main's head alone (depth 1), so main is in within about a minute at any size; while it runs, firstCopy carries bytes received and objects ({ received, total }, Git's own count), both read from Git's progress output every few seconds, size (the repository's size on GitHub, kept for the history) and step (preparing, receiving, indexing, saving); main's line shows main's own bytes, never a share of the whole repository. The store records main and its shallow boundary (the commits whose parents were not fetched) in one version, and tasks may start as soon as main is in; the history then copies behind it (/copy-history). A failure GitHub's status page explains (an incident on Git Operations, API Requests, Webhooks, Actions or Pull Requests) uses up no try, nor does an engine that went away or was still catching up with the store, up to ten such tries in a row counted on the project record. When the App can no longer read the repository (made private, or taken from the App's repositories), the reason is "Switchyard can no longer read acme/app on GitHub: the App needs access again" and access links the App's settings |
| POST | /engine/wake | Wake the project's Git engine ahead of work (project admin), so the first push, clone or check does not wait while it loads the repository from storage. A second ask while a wake runs starts nothing more. Answers { seq, started, activity }: whether this ask started it, and what the project is doing. The same as yard engine wake and the MCP tool yard_wake_engine. |
| POST | /copy-history | Copy the history behind main again after it was cancelled, or after it failed and Switchyard stopped trying (project admin). Once main is in, /status carries history while its history copies: { state: "copying" | "failed" | "cancelled", github, since, tries, bytes, size?, secondsLeft?, step?, reason?, nextTry?, access?, by?, at? }, with bytes counting main's bytes and the history's together against GitHub's size, and secondsLeft once the rate is known (after half a minute of bytes). The engine object first brings the engine's store up to date and passes its version; the engine refuses a step while its store is behind that version or lacks the head the copy started from. The engine fetches the history at low priority (nice, with GitHub given up to 15 minutes to start sending) under one copy lock per store, so an import and a history copy of one store never overlap, on the head the copy started from even when main moves on GitHub meanwhile: in one step (git fetch --unshallow) when GitHub's size says what is left fits 2 GiB, otherwise in steps (--deepen, from 1,000 commits, sized from the bytes the last step brought), and in steps whenever GitHub gives no size. Each step is fetched into a staging repository of its own beside the store (borrowing the store's objects and its boundary), split from its own packs under a 4 GiB pack limit (pack-objects --stdin-packs), checked complete down to its new boundary (git rev-list --objects --missing=error), kept in R2 and recorded, and only then moved into the store with its boundary, so no push can rest on history that is not kept. A step whose pack is still too large is asked again with half as many commits, using up no try. The history is recorded whole only when the engine proves it: no boundary left and every object under main present. When it is, the copy is recorded once as project.history_copied (a system action), and for a day /status carries historyCopied: { seq, at, github, sentence } with the sentence "History copied: blame, the full log and pushes built on older commits work now", shown on every page of the board until someone dismisses it in that browser, by yard status and in yard_status. A history copy that needs more room than the engine has (about twice what is left plus half a gigabyte) moves the project to an engine sized for the whole repository: an idle engine on a smaller disk stops and starts again on the larger one, and the copy goes on there. Only a history even the largest engine (20 GB of disk) cannot hold waits with that reason instead of failing halfway. A failed copy is tried again every 15 minutes, five times, then waits for this call; only failures count as tries, a project restarted by a deploy counts none, nor does an engine restart (an engine object reset, a container that went away or a lost connection to it), an engine still catching up with the store, a step that met a cancelled copy still ending (these three tried again within a minute), a step that ran past the wait while the engine still lists it, or a try while GitHub reports trouble, up to ten such tries in a row counted on the project record, and the count starts again at 0 once a step moves the boundary; two engine losses on one step halve the next step. A reason never says the copy is tried again once Switchyard stopped trying. Copy history right after a cancel starts the copy again at once with no try and no failure from the cancelled step: the new copy waits for the engine's stop, the stop drops the engine object's running step so the next starts afresh, and a step that still meets the cancelled copy ending waits a few seconds and asks again. Reasons are plain sentences: the engine's own JSON and Git's command lines stay in the logs. Answers { seq, history }, null only when the store's boundary was read empty; with no history recorded it starts one when the store is shallow, answers the copy a follow started meanwhile, and answers 503 when the boundary cannot be read; records project.history_copy only when it starts a copy. The same as yard copy-history and the MCP tool yard_copy_history |
| DELETE | /copy-history | Cancel the history copy (project admin): the engine's fetch stops, main and every task stay as they are, blame past the first copied commit answers "history was not copied", and a push based below it is refused with Switchyard's sentence. Answers { seq, history } with state: "cancelled", by and at, or history: null when no history copy was recorded; records project.history_cancel. The same as yard copy-history --cancel and yard_copy_history with cancel |
| PUT | /fixes | Whether fixes Switchyard makes wait for a person, { "fixes": "approve" | "auto" } (project admin; tasks get 403, another value 400; default approve). With approve the merge queue holds a change version the recipe step wrote until that version is approved; auto lets it merge once its checks pass. POST /v1/projects takes fixes; settings report it. Records project.fixes, which undo reverts, and wakes the merge queue |
| PUT | /task-permission | Who submits a finished task, { "taskPermission": "submit" | "commit" } (project admin; tasks get 403, another value 400; default submit). It is the permission a new task, and a new agent group key, gets when its request names none: submit lets the agent submit its task when the work is done, commit leaves submitting to a person. Tasks made earlier and agent group keys keep their own permission. POST /v1/projects takes taskPermission; settings report it. Records project.task_permission, which undo reverts |
| PUT | /self-approval | Whether the person whose task it is may approve its protected changes, { "selfApproval": "on" | "off" } (project admin; tasks get 403, another value 400; off by default, so someone else approves them); records project.self_approval, which undo takes back, and the merge queue looks again at once |
| PUT | /build-cache | Whether checks keep their package downloads between runs, one cache per set of lockfiles, { "buildCache": "on" | "off" } (project admin; tasks get 403, another value 400; on by default); records project.build_cache, which undo takes back; off, checks get no cache links and download afresh |
| PUT | /incremental-rebuild | Whether the integration is rebuilt only where tasks moved, { "incrementalRebuild"?: "off" | "on" | "verify", "verifyCappedEvery"?: 0–1000 } (project admin; tasks get 403, another value 400; incrementalRebuild may be left out when verifyCappedEvery is sent, and the mode stays; off by default; verifyCappedEvery, one in how many incremental rebuilds are verified with the setting on, 10 until set, 0 turns sampling off, kept when left out, answered and shown in the settings; another number 400 "verifyCappedEvery must be a whole number from 0 to 1000: one in that many incremental rebuilds is checked against a full rebuild, and 0 turns sampling off"): off, every rebuild merges every task; on, a rebuild merges only the moved tasks and those sharing their paths or names, and one in verifyCappedEvery is also rebuilt in full and compared (verify mode); verify, every one is (load projects). Records project.incremental_rebuild, which undo takes back; it turns on for every project once our larger load runs show no mismatch |
| PUT | /grouped-merge | Whether the engine merges path by path, { "groupedMerge"?: "sampled" | "off", "groupedVerifyEvery"?: 0–1000, "groupedLatch"?: "clear" }, at least one (project admin; tasks get 403, another value 400; sampled with 5 by default): sampled, the engine merges path by path from 32 tasks and one full rebuild in groupedVerifyEvery, drawn at random, is checked against the full merge (0 none); off, every rebuild asks for the full merge; groupedLatch: "clear" clears the latch to the full merge a differing check or a failing path-by-path merge set. Answers { seq, groupedMerge, groupedVerifyEvery, groupedLatch? }; recorded as project.grouped_merge, which yard undo reverts (not the cleared latch) |
| PUT | /continue-merged | Whether a push to a merged task that builds on the head it merged at continues the task as a new change, { "continueMerged": "off" | "on" } (project admin; tasks get 403, another value 400; on by default): on, a merged task's Git key keeps working to its own expiry and a fresh one may be minted, and a push that builds on its merged head continues it (see observe); off, the key is revoked at the merge, a merged task stays merged, observe answers 409, and its pushes are not tracked, with no read or lock taken for them. Turning it off revokes merged tasks' keys at once, as does an undo that leaves it off. Records project.continue_merged, which undo takes back |
| PUT | /merge-trains | Whether the merge queue runs separate trains (queue v2, Phase E), { "mergeTrains": "off" | "on" } (project admin; tasks get 403, another value 400): on, tasks that touch nothing in common are tested and landed on trains of their own, and a train's tested change may land on a main another train moved, checked on main afterwards; off, one train, and every tree that lands is the tree its checks ran on. On for a project made on queue v2 since 19 November, off for every other, with no effect until the merge queue reads it; it helps only where checks are scoped by paths or sparse checkouts. Turning it on lands a tree no check ran as a whole, so where people sign in it is a person's in a browser signed in within 15 minutes (approval_required for every key, the admin key included), and so is an undo that turns it back on; any admin turns it off. There is no control on the settings page yet; Switchyard turns merge trains on for a project on request. Answers { seq, mergeTrains }; records project.merge_trains, which undo takes back |
| PUT | /docs-excused | Whether a task that changes only documentation (**/*.md, **/*.rst, **/*.adoc, images under docs/, licence, notice and authors files; never .github/workflows/, .github/actions/ or .yard/) merges though no check reads it, { "docsExcused": "on" | "off" } (project admin; tasks get 403, another value 400; on by default); records project.docs_excused, which undo takes back (the design document.4, Every changed file is tested) |
| POST | /untested-guard/enforce | Start holding now a task that changes a file no check reads, on a project made before that guard, which watches for its first seven days (project admin; tasks get 403). Records project.untested_guard with state: "enforcing" once; a second call changes nothing. Answers { seq, untestedGuard } |
| PUT | /checks-before-submit | Whether a working task's checks run ahead of submit once 30 seconds pass with no push to it, so a pass is ready when it is submitted, { "checksBeforeSubmit": "on" | "off" } (project admin; tasks get 403, another value 400; on by default); records project.checks_before_submit, which undo takes back, and the merge queue looks again at once |
| PUT | /checks-while-reviewing | Whether a task waiting for a person's review runs its checks while it waits, so an approval lands at once, { "checksWhileReviewing": "on" | "off" } (project admin; tasks get 403, another value 400; on by default); records project.checks_while_reviewing, which undo takes back, and the merge queue looks again at once |
| PUT | /wake-on-open | Whether the Git engine wakes when someone opens the project, { "wakeOnOpen": "on" | "off" } (project admin; tasks get 403, another value 400). Unset, it is on once the project passes 1 GB (the larger of its last storage measurement, the size GitHub gave for it at the first copy and the store the engine holds) and off below, and /settings says wakeOnOpenChosen only when a person set it. Opening the board wakes the engine when it is on, once however many open it and not again within ten minutes of that warm's end, never while main is not copied yet. Records project.wake_on_open with who changed it, undoable. The same as yard settings set wake-on-open and the MCP tool yard_setting. |
| PUT | /engine-sizing | Whether the Git engine starts on a larger machine after many agents worked at once, { "engineSizing": "grows" | "small" }; another value 400. Without organizations it is the project's (project admin; tasks get 403), and a change records project.engine_sizing in the project's log with who changed it and to what (engineSizing, previous), never undone, since an undo a key asks for must not let engines grow. In the hosted product it is the organization's for all its projects: an owner or admin signed in, or an organization key with admin access and no team, may set small; only an owner or admin signed in in a browser within the last 15 minutes sets grows, and a key or yard sign-in gets 403 "letting engines grow under load is done only by a person signed in in a browser; no key does it, and no yard sign-in"; anyone else gets 403 "whether X's engines grow under load is the organization's choice, an owner's or admin's" (the project's own admin key reads "the organization" for X). A hosted project no organization owns keeps the choice itself, and a key there gets the same 403 for grows. A change tells the project's engine at once. Answers { engineSizing, setBy: "organization" | "project", organization?, sentence }, which /settings carries as engineSizing; organization and the name in sentence go to people and organization keys only, and the project's own admin key reads "the organization's Git engines …" with no organization (re-probe Z5). See Engine size. The same as yard settings set engine-sizing and the MCP tool yard_setting engine_sizing. |
| PUT | /warm-hour | Whether the Git engine stays warm for an hour after work, { "warmHour": "on" | "off" } (project admin; tasks get 403, another value 400). Unset, it is on once the project passes 1 GB, by the same measure as wake-on-open, and off below, where a cold wake takes seconds; /settings says warmHourChosen only when a person set it. While it is on, a push, a task created, a check run or an opening of the board tells the engine, at most once in five minutes, and the engine then stays up until an hour after the last of them on the shape it already has, never resized; once the hour passes, its usual quiet time counted from its last call applies again. It comes with the Scale and Enterprise plans: on a Launch team /settings says warmHour: "off" with warmHourNeeds: "scale", this call answers 403 "the warm hour comes with the Scale plan", and the engine is never told. Records project.warm_hour with who changed it, undoable. The same as yard settings set warm-hour and the MCP tool yard_setting. |
| PUT | /conflict-data | Whether the project's conflict records (the conflicting lines, the fix and whether a person accepted it) may help improve Switchyard's resolver, { "conflictData": "private" | "share" } (project admin; default private). Nothing uses shared records yet; the setting records the project's choice before anything could. Records project.conflict_data, which undo reverts |
| GET | /webhooks | The project's webhook endpoints (project admin; others 403): id, url, events, failing (attempts failed since the last success), dropped (events given up on), lastSuccessAt, lastError, lastDroppedAt, and note when the address uses a port an endpoint added today is refused for (worked out at the read, stored nowhere; the endpoint keeps receiving); never the secret |
| POST | /webhooks | Add an endpoint, { "url": "https://…", "events"?: [...] } (project admin): https on port 443 (written or left out; any other port is refused) on a public host, no IP literal, no local name, no user info, a host whose name resolves and only to public addresses, not on Switchyard's own addresses; at most 5 endpoints. Answers the endpoint with its signing secret, shown only here, and test, the result of one test event sent to the endpoint once the add is stored: { delivered, status, failure, ms } as POST /webhooks/:id/test answers it. A test that fails neither undoes the add nor changes its status, and is not counted among the endpoint's 30 an hour. Records project.webhooks with the URL without its query string, never the secret; it cannot be undone |
| DELETE | /webhooks/:id | Remove an endpoint and every event still waiting for it (project admin) |
| POST | /webhooks/:id/test | Send one test event to an endpoint (project admin; others 403), whatever events it asked for and however its deliveries go: an event of data.type webhook.test with the id evt_test_ and 16 hex digits, data.project and the project's seq, no task, signed as every delivery. Answers { event, delivered, status, failure, ms }: status is the HTTP status or null when no answer came, failure is null, http (a status that is not 2xx), redirect (a 3xx, never followed), timeout (no answer in 10 seconds), connect (the request failed; a refused certificate reads so too), refused_address (the host's name resolves to an address that is not public; no request is made and ms is null) or unsignable (the endpoint's secret cannot sign; no request is made and ms is null). One attempt, never queued and never retried; no history entry; failing, lastError and lastSuccessAt stay as they are. The request is made outside the project's lock, and is answered as timeout no later than 11 seconds after it was made (the look at where the host resolves is inside the 10 seconds: the request gets what the look left of them), so the call answers within 12 seconds of taking its count. At most 30 an endpoint in one hour of the clock, counted in the endpoint's row (a restart keeps the count); the 31st answers 429 rate_limited with Retry-After |
| PUT | /rules | Keep the rules and checks in Switchyard, { "rules": "<the text of a rules file>" }, or "" to stop (project admin; tasks get 403, text that does not parse 400, over 64 KiB 400). While main has no .yard/rules.toml, the merge queue, checks and settings read these instead; a file on main always wins. POST /v1/projects takes the same text as rules, and as proposedRules text checked the same way but not kept: settings report it as rules.proposed (the rules sent at creation when there is no proposedRules), so the board's editor starts from the checks and rules agreed at set-up while none are kept. With "tryChecks": true, every check that is new or whose command, checkout, skeleton, size, timeout or services changed starts off (in the same project.rules operation, so undo reverts both) and is tried once on main; one that passes there, or that Switchyard's runner could not run, is turned on, and one that fails stays off with its log, as at creation; a try that would take the project past its 100 free trial runs on main for the UTC day (a large check counts as four) answers 429 rate_limited with "try again tomorrow or submit a task" and Retry-After, and saves nothing, unless the day has run none. Records project.rules, which undo reverts, and wakes the merge queue; answers { seq, source } with source switchyard or none, and settings report rules.source (repository, switchyard or none) and the kept text as rules.stored |
| POST | /rules/unchecked | Say plainly that paths need no check, { "paths": ["src/gen/**"], "reason"?: "…" } (1 to 16 paths or globs; project admin; tasks get 403, a glob that steps out of the repository 400): adds an [[unchecked]] table to the rules kept in Switchyard, or changes nothing when every table already names them, and answers { seq, source, paths, coverage }. Rules in .yard/rules.toml on main answer 409 naming the table to add in a task. PUT /rules answers coverage too (the design document.4, Caught at setup) |
| GET | /checks/tried | The one trial of the kept checks on main (any key of the project): { seq, state, main, checks, off, turnedOff, at }. A project made with rules tries each kept check once on main as soon as main is known, before any task, on the check runner and the checks' network, and records project.checks_try (an action of Switchyard's, not a counted check minute). state is none (no kept checks were tried), waiting (main not read yet), running or done; at is when the last trial finished, so a running trial still shows the time of the one before it; each check carries its status, duration, size and, when it failed, the log's tail. A check that failed or timed out on main itself is turned off (turnedOff), so the first task never waits on a check that cannot pass; one that failed only because the checks' network blocked a host names it as blocked and is turned off too, and one Switchyard's own runner failed to run is tried once more after the others (a new project's engine can take minutes to start) and, failing again, is unrun and stays on. off lists the kept checks that are off now |
| GET | /checks/logs/<id> | A check's full log as plain text (any key of the project; another project's key, or a log older than 30 days, 404). <id> is the fullLog.id a check carries in a test build or in GET /checks/tried; which task's check it is, and whether this project ran it, is read from that field and kept.id only, compared exactly, so an id that appears elsewhere in a record (a test's name, a log line) names no check. The log is kept when the check settles, before its machine stops, with the board's secret redaction and every value the check was given replaced by [redacted]; a log over 50 MB keeps its first and last 25 MB with a line saying how many MB were left out. A check whose log could not be kept carries fullLog.lost with why. Not counted as check minutes |
| PUT | /checks/off | Turn kept checks off or back on, { "off": ["<check name>", …] }, the whole list of what should be off (project admin; others 403; a name not kept 400; a project whose rules live in .yard/rules.toml on main 409, since a file's checks change in the file). An off check stays in the kept text and leaves the merge queue's and the settings' checks; records project.checks_off with turnedOff and turnedOn, which undo reverts, and wakes the merge queue |
| POST | /checks/try | Try kept checks that are off once more on main, { "checks"?: ["<check name>", …] }, every check that is off when left out (project admin; others 403; a name that is not off 400; nothing off, a trial already running, or rules in .yard/rules.toml on main 409; a trial that would take the project past its 100 free trial runs on main for the UTC day, a large check counting as four, 429 rate_limited with "try again tomorrow or submit a task" and Retry-After, unless the day has run none). Answers the trial as GET /checks/tried reads it, now waiting or running; the trial records project.checks_try with again: true, turns each check that passes back on and keeps each that fails off |
| PUT | /reviews | Turn reviews on or off, { "reviews": "on" | "off" } (project admin; tasks get 403, another value 400). Off adds a last rule that lets every change no rule covers merge once its checks pass, so rules that ask for review still apply; records project.reviews, which undo reverts, and wakes the merge queue so waiting work is decided again |
| PUT | /checks/network | Set the network the project's checks may reach, { "network": "open" | "registries" | "off" } (project admin; tasks get 403, another value 400); records project.check_network unless it is already set, and answers { seq, network }. A project starts on registries, or on the checkNetwork POST /v1/projects names; a project made before that kept no value and reads as open. Every check, including those started ahead for a test build behind, runs under the stricter of this and the rules file's network |
| POST | /oplog/:seq/undo | Undo an operation; a developer of the project's team gets 403 for an operation that changed the project's settings (its rules, fixes, pause, reviews, checks and the like), which an admin undoes; operations on a merged task are final (409), the kinds the design document names cannot be undone (400), and an operation already undone, even by an undo running at the same time, answers 409, as does a integration rebuild whose integration never reached main |