Docs · API
The HTTP surface.
Switchyard exposes one authenticated JSON API for Git-aware collaboration: identity, repositories, Work, Attempts, Pull Requests, editor drafts, workflows, the Integration Queue, policy, organisations and realtime events.
Conventions first
| Concern | Contract |
|---|---|
| Browser authentication | Registration/login establish an HttpOnly session cookie. Mutating browser requests are authorized as the signed-in Switchyard principal. |
| Repository identity | Public-facing repository APIs use owner/repo. The backing Cloudflare Artifacts repository name remains an implementation/storage identity. |
| JSON errors | Application failures return structured JSON with an error value; concurrency failures use explicit conflict states rather than silent overwrite. |
| Optimistic concurrency | Drafts use revisions; repository writes use expected Git state. Stale writes are surfaced to the caller. |
| Realtime | Normalized domain events are available over authenticated Server-Sent Events. |
Endpoint map
| Area | Representative endpoints | What they are for |
|---|---|---|
| Auth & account | POST /api/auth/register, /login, /logout · GET /api/auth/me | Application identity and browser sessions. |
| Users & settings | GET /api/users/{username} · PATCH /api/settings/profile · avatar/password/session endpoints | Profiles, large avatars, account metadata, password/session management. |
| Owners & organisations | GET /api/owners/{slug} · /api/orgs… · members, teams, invitations, policies, audit | Git-host ownership, organisation profiles and server-enforced membership/access. |
| Repositories | GET /api/repositories · /api/repositories/{owner}/{repo} · /tree · /content · /refs | Canonical owner/repo browsing. Legacy flat-name /api/repos… routes remain for compatibility. |
| History & compare | /commits · /commits/{sha} · /compare | Ordinary Git history, commit detail and ref comparisons. |
| Repository settings | GET/PATCH …/settings · collaborators · protected refs | Metadata, access and integration policy. |
| Work | GET/POST /api/work · GET/PATCH /api/work/{id} · comments · provenance | Human-first issues/tasks. Attempts are an optional execution layer beneath Work. |
| Attempts | POST /api/work/{id}/attempts · /api/attempts/{id}/run|review|preview|resolve | Isolated candidate branches, Agent execution, review and conflict repair. |
| Pull Requests | GET /api/prs · GET /api/prs/{id} · check/enqueue/integrate | Reviewable integration proposals and their queue state. |
| Editor | POST /api/drafts · GET /api/drafts/… · /agent-propose · /commit · POST /api/diff | Recoverable drafts, interactive Agent proposals, diffing and explicit commit. |
| Workflows | /api/workflows… · /api/workflow_runs… | Create/run workflows; inspect, cancel, approve or retry durable runs. |
| Queue & attention | GET /api/queue · POST /api/queue/{id}/requeue · GET /api/attention · escalations | Canonical scheduling, blocked work and human decision packets. |
| Events | POST /api/events/ingest · GET /api/events · GET /api/events/stream | Normalized Git/domain event ingestion and SSE delivery. |
| Agents & credentials | GET /api/roles · GET/POST /api/credentials · rotate/delete | Role configuration and provider credential lifecycle. Provider secrets never imply repository authority. |
Example: browse a repository
# after authenticating in the browser/session
curl -b cookies.txt \
http://127.0.0.1:8080/api/repositories/switchyard-labs/switchyard/overview
curl -b cookies.txt \
'http://127.0.0.1:8080/api/repositories/switchyard-labs/switchyard/tree?ref=main'
The overview response is deliberately product-shaped: ownership, visibility, default branch and clone information are resolved there so the UI does not need to reconstruct repository identity from low-level Artifacts records.
Concurrency semantics you should design around
| Operation | Caller supplies | On stale state |
|---|---|---|
| Draft save | expected_revision | 409 draft_stale; newer draft content remains intact. |
| Draft commit | Draft base_sha | 409 stale_base; the draft remains recoverable and the user reconciles. |
| Git/ref mutation | Expected prior SHA | Normal non-force Git push rejects stale movement; Switchyard reconciles instead of overwriting. |
| Integration Queue | Validated PR + current canonical state | Item is re-previewed/re-queued or blocked with an explicit reason. |
Example: create Work and an Attempt
work=$(curl -s -b cookies.txt \
-H 'Content-Type: application/json' \
-d '{"title":"Tighten repository browser errors","kind":"fix"}' \
http://127.0.0.1:8080/api/work)
# Attempts are optional: ordinary human Work can remain just an issue/task.
# When execution is needed, create an isolated candidate branch underneath it.
API principleThe API exposes familiar Git-host concepts where they are truthful, and Switchyard-specific concepts only where they add genuinely new coordination semantics.