API reference

Developer referenceHTTP · JSON

Connect your tools to the work happening in Shiba.

Read run records, queue work for approval, and work with your installation’s email API. All paths below are relative to your Worker origin.

Authentication

Dashboard endpoints use your installation’s configured identity system: Cloudflare Access or the built-in sign-in session. Authenticate before calling the routes on this page. A local loopback development server can run without an identity provider when neither system is configured.

Dashboard routes

Use the authenticated dashboard session for /api/runs and the email routes below. An MCP bearer token does not authenticate these routes.

Agent and v1 clients

The /mcp gateway and documented /api/v1 routes have their own token and scope rules. See MCP clients or the SDK guide for that transport.

This is a focused reference, not a complete endpoint catalog. The coverage note lists the additional surfaces and source references.

Run registry

Inspect retained run records or request cancellation. URL-encode the entire run ID, including any colons.

GET/api/runs

List runs

Returns a JSON object containing the visible run records.

Returns{ "runs": […] }

GET/api/runs/:id

Get a run

Returns one retained run. An unknown ID returns 404.

Returns{ "run": … }

DELETE/api/runs/:id

Request cancellation

Updates cancellation state before best-effort cleanup. An unknown ID returns 404.

Returns{ "run": … }

DELETE/api/runs

Clear the registry

Clears retained run records. This does not stop active work or erase child storage.

Returns{ "ok": true }

Records include runId, sandboxId, repoUrl, task, baseBranch, publishPullRequest, status, createdAt, updatedAt, and optional summary or error information. Timestamps are Unix milliseconds. Status values include pending, running, completed, error, aborted, and cancelled. Inspect the transcript and returned result for available diffs and files.

Other unsupported methods return 405. The response shapes above are structural sketches, not recorded execution results.

Submit and approve

POST/api/runs

Queue a run for approval

Submits work to the orchestrator. Queueing does not start sandbox execution before human approval.

Include the repository, a bounded task, and the checks you want run. Keep pull request publication off until you are ready to review that action. The delegation tool accepts a request such as:

{
  "repoUrl": "https://github.com/owner/repository",
  "task": "Describe a bounded coding task",
  "baseBranch": "main",
  "publishPullRequest": false,
  "testCommand": ["pnpm", "test"],
  "harness": "opencode"
}

Approval is part of the contract.

The exact input, including the optional testCommand argv array, is frozen with the approval. Execution waits for a human decision. Harness and model values are optional and validated before the run is approved.

The dashboard also uses the coding-orchestrator agent SDK routes under /agents/. The tool declares needsApproval: true; SDK approval decisions use addToolApprovalResponse({ id, approved }), and delegated events use useAgentToolEvents. HTTP requests use the approval endpoints or the configured Slack interaction. Read Approval gates for the flow.

Harness unit coverage is not proof of successful inference. Review the readiness checklist for recorded verification and current limits.

Email API

GET/api/email/openapi.json

Read the email contract

Machine-readable schema for this installation’s mailbox, email, thread, draft, and attachment routes.

ReturnsOpenAPI 3.1

This is Shiba’s own API, not Goshen Email’s /v1 API. It uses the dashboard authentication described above. Provision Cloudflare Email Routing, Email Sending, R2, and access controls before using it.

Receive mail

Register an address with POST /api/mailboxes. Set agent to the exact MCP token principal allowed to use the mailbox.
Configure Cloudflare Email Routing to deliver that address to the Worker. Registration alone does not change DNS or routing.
List messages with GET /api/emails?mailbox=agent%40example.com. Read a message with GET /api/emails/{emailId}.

{
  "address": "agent@example.com",
  "agent": "scout"
}

Omit agent for a new dashboard-only mailbox. Omitting it when re-registering preserves the assignment; send "agent": null to unassign an existing mailbox.

Incoming mail is accepted only for registered addresses. Message data lives in the Mailbox Durable Object and attachment bytes in R2. Message detail includes the body and attachment manifest; GET /api/emails/{emailId}/attachments/{partId} streams a manifest-backed attachment as a forced download.

Send through approval

Create a draft with POST /api/drafts, then request POST /api/drafts/{draftId}/send. This queues a frozen email_send approval. The draft remains queued until a human approves it in Approvals or the configured Slack channel. Only then does the Worker call SEND_EMAIL; rejection releases the draft for editing.

The scoped email tools exposed through /mcp follow the same approval boundary. Treat mail content and attachments as untrusted data, not instructions for an agent.

Provider traffic

There is no public /api/provider route. Supported provider-backed sandbox execution uses Worker-side egress authorization and placeholder container credentials. Keep provider keys in the configured gateway rather than sending them in a task or container environment. Review Security and Configuration for the deployment boundaries.

GitHub webhook

POST/api/github/webhook

Receive a verified GitHub delivery

Requires the configured webhook secret, a valid signature, and a delivery identifier. Verified, deduplicated events can be forwarded to configured automations.

Header	Purpose
`x-hub-signature-256`	Verify the body against `GITHUB_WEBHOOK_SECRET`.
`x-github-delivery`	Identify the delivery for replay protection.
`x-github-event`	Name the GitHub event.

Missing webhook configuration returns 503; an invalid signature returns 401. Invalid JSON or a missing delivery identifier returns 400. Dedupe unavailability returns 503 for retry. An accepted delivery returns ok, the event name, and an optional action; duplicates can return deduped: true.

See GitHub and Automations for setup and configured event behavior. An accepted delivery is not evidence that coding work completed.

Reference coverage

Additional routes and source references

The Worker exposes more surfaces than this page documents, including approvals, sessions, audit and usage, screenshots, sandbox and computer controls, automations, memory, account setup, model configuration, authentication, subscriptions, channel callbacks, OAuth discovery, and MCP.

Use apps/backend/src/index.ts for dispatch order and apps/backend/src/request-auth.ts for authentication boundaries. Run routing is implemented in runs-routes.ts; the email schema lives in email-openapi.json; webhook verification and fan-out live in github-webhook-routes.ts.

The /agents/coding-orchestrator/* SDK lane is distinct from the HTTP endpoints shown here. Consult the implementation and transport-specific schema before using an undocumented route.

Next: use the TypeScript SDK or connect an MCP client.