@cursor/july 0.1.113 → 0.2.0

package/dist/docs/reference/http-api.md

@@ -1,31 +1,30 @@
-# HTTP API reference
-
-Agent SDK hosts expose the same public HTTP surface. In the default
-multi-agent layout each agent is namespaced under its slug
-(`/<slug>/v1/session`, `/<slug>/playground`), with host-level routes at
-the root. With `--mode single`, one agent serves the same surface
-unslugged (`/v1/*`).
-
-Unless noted otherwise, routes run the agent's HTTP auth chain: the
-default is `localDevStrict()` (loopback only), replaced by `bearerAuth` under
-`--bearer-token` or `allowAll()` under `--allow-anonymous`. Session
-routes also require the caller to be the session's owner (`403`
-otherwise). Errors return JSON
-`{ ok: false, error: "<code>", message? }` with a matching HTTP status.
-
-## Host-level routes (multi-agent mode)
-
-These routes live at the host root, above any agent. The two index
-routes exist only while the playground is enabled (`--no-playground`
-removes them) and run no auth. The documentation site is mounted in
-both layouts and removed by `--no-docs`.
-
-| Route                      | What it does                                                                                                                 |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
-| `GET /`                    | A web index of every mounted agent, linking to playgrounds (playground only)                                                 |
-| `GET /v1/agents`           | The JSON index of mounted agents (playground only, no auth)                                                                  |
-| `GET /docs`, `GET /docs/*` | This documentation, served as a static site (both layouts, no auth)                                                          |
-| `GET /v1/health`           | Host-level liveness, no auth                                                                                                 |
+# HTTP API
+
+Agent SDK hosts expose one public HTTP surface. In the default
+multi-agent layout, each agent uses `/<slug>/v1/*`; `--mode single`
+serves the same routes at `/v1/*`. Routes use the agent's HTTP auth
+chain, and session-owned resources return `403` to another principal.
+
+Unless a section says otherwise, the default auth policy is
+`localDevStrict()`. `--bearer-token` replaces it with bearer auth, and
+`--allow-anonymous` replaces it with anonymous access. Built-in JSON
+routes use `{ ok: false, error: "<code>", message? }` for errors; MCP
+uses JSON-RPC, and custom channel handlers define their own responses.
+
+## Host routes
+
+These routes live at the host root in multi-agent mode. The index routes
+exist only when the playground is enabled.
+
+| Route | Contract |
+| --- | --- |
+| `GET /` | HTML index of mounted agents; no auth |
+| `GET /v1/agents` | JSON index of mounted agents; no auth |
+| `GET /docs`, `GET /docs/*` | Documentation site in either layout; no auth |
+| `GET /v1/health` | Host liveness; no auth |
+
+`--no-playground` removes the two index routes. `--no-docs` removes the
+documentation site.
 
 ## Start a session
 
@@ -39,18 +38,18 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session \
 #  "playgroundUrl":"…?sessionId=ses_…","traceUrl":"…/v1/session/ses_…/events"}
 ```
 
-The response returns as soon as the message is accepted; follow the
-stream for progress. The continuation token is the follow-up credential,
-and `playgroundUrl` deep-links the session in the playground.
+Once accepted, the response returns `sessionId` for inspection and
+`continuationToken` for follow-ups; follow the stream for progress.
 
-| Body field | Meaning |
+| Body field | Contract |
 | --- | --- |
 | `message` | Required user message |
-| `title` | Session title |
+| `title` | Display title |
 | `dryRun` | Run read tools and stub write tools |
-| `asOf` | ISO-8601 instant with a timezone, frozen at create; the prompt states it, `ctx.now()` returns it, and tool calls with relative, later-than-`asOf`, or omitted schema-declared time bounds are refused. `400` when unusable |
-| `workspaceFiles` | UTF-8 files written into the session workspace |
+| `asOf` | ISO-8601 instant with a timezone; sets `ctx.now()` and rejects omitted, relative, or later declared tool time arguments. Invalid values return `400` |
+| `workspaceFiles` | Relative files added to the session workspace |
 | `cloud` | Per-session cloud options merged over the agent defaults |
+| `purpose` | Use `"eval"` to mark regression traffic |
 
 ## Send a follow-up
 
@@ -62,15 +61,15 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/session/ses_… \
   -d '{"continuationToken":"http:…","message":"Make it shorter."}'
 ```
 
-Works for any chat session, including ones created by custom channels.
-Each accepted follow-up rotates the token, and the response carries the
-new one. Sending to a busy session interrupts the in-flight turn, waits
-for it to settle, then sends.
+The route accepts any chat session, including one created by a custom
+channel. Each accepted follow-up rotates the continuation token and
+returns the replacement. A message sent to a busy session interrupts
+the active turn before starting.
 
-Expect `409` on a stale token or a task session. Task sessions do not accept
-follow-ups. Expect `403` when the caller is not the session owner.
+The route returns `409` for a stale token or task session, and `403`
+when the caller doesn't own the session.
 
-## Stream a session
+## Stream or replay session events
 
 `GET /v1/session/:sessionId/stream` is the live NDJSON feed.
 
@@ -78,44 +77,36 @@ follow-ups. Expect `403` when the caller is not the session owner.
 curl -N 'http://127.0.0.1:3000/<slug>/v1/session/ses_…/stream?startIndex=0'
 ```
 
-One NDJSON event per line, from `startIndex`, then following live. The
-default is `0`: omitting the parameter replays the entire recorded
-stream before following. Pass the last index you've seen plus one to
-resume without duplicates. The stream is durable and reconnectable. For
-the vocabulary, see
-[Sessions](/docs/reference/sessions.md#which-events-can-i-stream).
+The route replays one event per line from `startIndex`, then follows new
+events. The default `0` replays the full stream. To reconnect without
+duplicates, pass the last index you received plus one.
 
 `GET /v1/session/:sessionId/events` returns a one-shot NDJSON dump.
-Pass `?format=json` for `{ sessionId, events, playgroundUrl }`.
-
-## Stop and list
-
-`POST /v1/session/:sessionId/stop` interrupts the in-flight turn without
-sending a new message. `GET /v1/sessions` lists sessions owned by the
-calling principal. Under `serve --dev` on loopback it includes all
-sessions, which is how webhook and schedule sessions show up in the
-playground.
+Pass `?format=json` for `{ sessionId, events, playgroundUrl }`. See
+[Stream events](/docs/reference/sessions.md#stream-events) for the event vocabulary.
 
-## Session cost
+## Manage sessions
 
-`GET /v1/session/:sessionId/cost` returns the session's cost report:
-per-turn token usage and the engine's estimated cost, folded from
-`turn.completed` events. It runs the same owner check as the other
-session routes and returns `404` for an unknown session. The
-[`agent-sdk cost`](/docs/reference/cli.md#cost) command reports the same data.
+| Route | Contract |
+| --- | --- |
+| `POST /v1/session/:sessionId/stop` | Interrupt the active turn without sending another message |
+| `GET /v1/sessions` | List sessions owned by the caller |
+| `GET /v1/session/:sessionId/cost` | Return per-turn token usage and estimated cost |
 
-## Approvals
+On loopback under `serve --dev`, the session list includes every
+principal so webhook and schedule sessions appear in the playground.
+The cost route returns `404` for an unknown session.
 
-Two routes list and resolve parked tool calls.
+## Resolve tool approvals
 
-| Route                                           | What it does                                                   |
-| ----------------------------------------------- | -------------------------------------------------------------- |
-| `GET /v1/session/:sessionId/approvals`          | Pending human-in-the-loop tool approvals                       |
-| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one: `{"decision":"approve"}` or `{"decision":"deny"}` |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/session/:sessionId/approvals` | List pending tool approvals |
+| `POST /v1/session/:sessionId/approvals/:callId` | Resolve one with `{"decision":"approve"}` or `{"decision":"deny"}` |
 
 For the lifecycle, see [Gate a tool on human approval](/docs/reference/tools.md#gate-a-tool-on-human-approval).
 
-## Call a tool directly
+## Call a tool without a model turn
 
 `POST /v1/tools/:toolName` runs a server tool with no model turn.
 
@@ -127,130 +118,115 @@ curl -X POST http://127.0.0.1:3000/<slug>/v1/tools/inspect_pr \
 #  "isError":false,"result":{…},"durationMs":12}
 ```
 
-It runs an authored server tool in-process: schema-validated, no model
-turn. An optional `"sessionId"` in the body runs it inside an existing
-session and records it on that session's stream (`409 session_busy`
-for a write-effect call while a turn runs; reads run alongside the
-turn). Agent-execution tools are rejected with `400`, and
-unknown tools with `404` and the list of available names. For the
-semantics, see [Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
+| Body field | Contract |
+| --- | --- |
+| `input` | Tool input; defaults to `{}` |
+| `sessionId` | Bind the call to an existing session |
+| `continuationToken` | Bind the call by its wire continuation token; mutually exclusive with `sessionId` |
 
-An optional `"continuationToken"` (`<channelId>:<key>`, as
-`/v1/sessions` lists it; mutually exclusive with `sessionId`) addresses
-the session by continuation token instead; malformed tokens are
-rejected with `400 invalid_continuation_token`. For the semantics, see
-[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn).
+Omit both identifiers for an unbound call. Agent-execution tools return
+`400`, and an unknown name returns `404` with the available names. See
+[Tools](/docs/reference/tools.md#call-a-tool-without-a-model-turn) for session
+binding, busy-session rules, and error codes.
 
-## Discovery
+## Discovery routes
 
 These read-only routes describe the running agent.
 
-| Route                  | What it does                                                                                                                                                                             |
-| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `GET /v1/info`         | The discovered surface: model, tools, skills, MCP connections, subagents, channels and routes (with schemas), schedules, hooks, diagnostics |
-| `GET /v1/tools`        | The live tool catalog: authored server tools plus advertised MCP passthroughs under model-facing names, as light `{ name, title?, source? }` entries. `session` / `continuationToken` query parameters bind the listing to a session identity (advertised inventories can be tenant-scoped); a connection whose listing fails is skipped and reported in `connectionErrors` |
-| `GET /v1/tools/:name`  | One catalog tool's full description: description, execution, `needsApproval`, `effect`, input and output schemas, source connection. Same session binding as the listing; unknown names get `404` with the available names |
-| `GET /v1/health`       | Per-agent liveness, no auth                                                                                                                                                              |
-| `GET /v1/logs?after=N` | Recent server log lines, with a polling cursor                                                                                                                                           |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/info` | Return the discovered model, tools, skills, connections, subagents, channels, schedules, hooks, and diagnostics |
+| `GET /v1/tools` | Return live server tools and advertised MCP tools as `{ name, title?, source? }`; bind tenant-scoped listings with `session` or `continuationToken` |
+| `GET /v1/tools/:name` | Return one tool's description, execution mode, approval and effect rules, schemas, and source |
+| `GET /v1/health` | Return per-agent liveness; no auth |
+| `GET /v1/logs?after=N` | Return recent server logs and the next polling cursor |
 
-## Artifacts
+An unknown tool name returns `404` with available names. If an MCP
+connection can't list its tools, the catalog skips that connection and
+includes it in `connectionErrors`.
 
-Two routes read durable artifacts tagged by `ctx.artifacts` or
-`tag_artifact`. See [Artifacts](/docs/reference/artifacts.md).
+## List and download artifacts
 
-| Route                            | What it does                                                                                          |
-| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| `GET /v1/artifacts`              | List artifacts as `{ artifacts }`, newest-updated first. Filter with `?kind=`, `?sessionId=`, and `?limit=` (a positive integer) |
-| `GET /v1/artifacts/:id/content`  | Download one artifact's file or blob payload. Served as an attachment, never rendered inline; `404` when the artifact is unknown or carries no content |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/artifacts` | Return `{ artifacts }`, newest-updated first; filter with `kind`, `sessionId`, and a positive `limit` |
+| `GET /v1/artifacts/:id/content` | Download an artifact's file or blob as an attachment; return `404` when no content exists |
 
-Session ownership applies the same way as `GET /v1/sessions`: under
-`serve --dev` on loopback (or `--allow-anonymous`) the list spans all
-principals, while bearer or custom channel auth keeps strict
-per-principal isolation.
+The list follows the same ownership rules as `GET /v1/sessions`. See
+[Artifacts](/docs/reference/artifacts.md) for tagging and record fields.
 
-## Custom channel routes
+## Call custom channel routes
 
-Authored routes mount under `/v1/channels/<id>` with the methods, paths,
-and Zod schemas the channel declared (a
-`POST /<slug>/v1/channels/drive` route, say). Bodies are validated before
-handlers run (`400` on schema violations), and each channel's auth chain
-applies. The GitHub channel verifies `X-Hub-Signature-256` when a
-secret is configured. See [Channels](/docs/reference/channels.md).
+Authored routes mount under `/v1/channels/<id>` with their declared
+methods and paths. The host validates their Zod body and query schemas
+before calling the handler, returning `400` on failure. Each channel's
+auth chain applies. See [Channels](/docs/reference/channels.md).
 
 ## MCP endpoint
 
-`/v1/mcp` serves the Model Context Protocol over streamable HTTP
-(stateless; POST carries the protocol, and GET/DELETE return
-spec-compliant 405s). The tools are `ask` (delegate a message, bounded
-waits), `check` (poll a running session), and `call_tool` (deterministic
-server-tool passthrough, present when the agent has server tools). The
-route runs the same auth chain as the session API. Peer wiring:
-[MCP connections](/docs/reference/connections.md#peer-mcp-connection).
+Both MCP routes use stateless streamable HTTP. Send protocol requests
+with `POST`; `GET` and `DELETE` return `405`.
 
-`/v1/mcp/tools` is a second stateless MCP endpoint exposing only the
-agent's deterministic server tools. Hosted cloud turns call back into
-it through the URL configured by `serve --cloud-tools-url`. Unlike
-`/v1/mcp`, it runs the CLI-level auth chain (loopback, bearer, or
-anonymous), not any authored channel auth.
+| Route | Tools and auth |
+| --- | --- |
+| `/v1/mcp` | `ask`, `check`, and `call_tool` when server tools exist; uses the session API auth chain |
+| `/v1/mcp/tools` | Deterministic server tools only; uses the CLI-level loopback, bearer, or anonymous auth chain |
+
+See [MCP connections](/docs/reference/connections.md#peer-mcp-connection) to connect
+one agent to another.
 
 ## Playground eval routes
 
-The playground Evals tab and `agent-sdk eval --prod` / `--url` use these:
+The playground Evals tab and remote eval commands use these routes:
 
-| Route                           | What it does                                                                                               |
-| ------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `GET /v1/dev/evals`             | List discovered eval datapoints and project config                                                         |
-| `GET /v1/dev/evals/runs`        | List recent run snapshots, newest first                                                                    |
-| `POST /v1/dev/evals/runs`       | Start an eval run (`{filterIds?, tags?}`); `202` with a snapshot (`runId` is the Eval ID), `404` when nothing matches, `409` when one is running |
-| `GET /v1/dev/evals/runs/:runId` | Poll a run's progress                                                                                      |
-| `POST /v1/dev/evals/runs/:runId/cancel` | Cancel a running batch; `200` with snapshot, `404` unknown, `409` when not running |
+| Route | Contract |
+| --- | --- |
+| `GET /v1/dev/evals` | List discovered cases and eval config |
+| `GET /v1/dev/evals/runs` | List recent run snapshots, newest first |
+| `POST /v1/dev/evals/runs` | Start `{ filterIds?, tags?, timeoutMs?, verbose? }`; return `202`, `404` for no match, or `409` while another run is active |
+| `GET /v1/dev/evals/runs/:runId` | Return progress and the final snapshot |
+| `POST /v1/dev/evals/runs/:runId/cancel` | Cancel an active run; return `404` when unknown or `409` when no longer running |
 
-Eval runs are asynchronous. Poll the run route for case progress and
-the final `completed` or `failed` status. Batch errors appear on the
-snapshot returned by the poll. Entries within `filterIds` and `tags`
-use OR semantics. When both fields are present, a case must match one
-entry from each field. Listed runs persist across restarts when
-durable storage is configured. Otherwise they are
-process-memory only.
+Poll the run route until its status is `completed`, `failed`, or
+`cancelled`. Entries within `filterIds` and `tags` use OR semantics;
+when both fields are present, a case must match each group.
 
 ## Dev-mode routes
 
 These routes exist only under `serve --dev`.
 
-| Route                                | What it does                                                                                               |
-| ------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
+| Route | Contract |
+| --- | --- |
 | `POST /v1/dev/schedules/:scheduleId` | Dispatch a schedule by hand, exactly once. Returns `{scheduleId, sessionIds}` |
-| `GET /v1/dev/reminders`              | List reminders                                                                                             |
-| `POST /v1/dev/reminders/:reminderId` | Fire a reminder by hand                                                                                    |
+| `GET /v1/dev/reminders` | List reminders |
+| `POST /v1/dev/reminders/:reminderId` | Fire a reminder by hand |
 
 Schedules and reminders never fire automatically in dev mode. These
-routes are the only way they run, which keeps iteration deterministic.
+routes run them manually.
 
 ## Playground assets
 
 `GET /playground` and `GET /playground/assets/:file` serve the
-playground (omitted with `--no-playground`). It calls the JSON API
-above and has no privileged surface.
+playground. `--no-playground` removes both routes.
 
 ## Status codes
 
-Error responses use a small, consistent set of status codes.
-
-| Code  | Meaning here                                                                                                               |
-| ----- | -------------------------------------------------------------------------------------------------------------------------- |
-| `400` | Schema-invalid body or query, agent-execution tool called on the host, malformed request                                   |
-| `401` | No auth policy admitted the request                                                                                        |
-| `403` | Authenticated, but not the session owner                                                                                   |
-| `404` | Unknown session, tool, schedule, reminder, or eval run; no eval datapoints match a run request                              |
-| `405` | Wrong method (GET on the MCP endpoint, say)                                                                                |
-| `409` | Stale continuation token, a busy session-bound tool call, a non-followable task session, or an eval run already in progress |
-| `202` | Accepted for background work (GitHub `{ task }` hooks, eval runs)                                                          |
-
-## What's next
+Built-in routes use these common status codes.
 
-Continue with these pages:
-
-- [Sessions and streaming](/docs/reference/sessions.md): the handles and events these
-  routes traffic in
-- [Channels](/docs/reference/channels.md): authoring your own routes
-- [Deployment](/docs/deployment.md): auth on real hosts
+| Code | Meaning |
+| --- | --- |
+| `400` | Invalid body, query, tool input, or request shape |
+| `401` | No auth policy admitted the request |
+| `403` | The caller is authenticated but doesn't own the resource |
+| `404` | A named resource doesn't exist, or an eval selection matches no cases |
+| `405` | The route doesn't accept this method |
+| `409` | The resource state rejects the request, such as a stale token or busy write |
+| `202` | The request was accepted for asynchronous work |
+| `500` | A write-effect tool can't create its session workspace (`workspace_unavailable`) |
+
+## Related
+
+- [Sessions](/docs/reference/sessions.md)
+- [Channels](/docs/reference/channels.md)
+- [Tools](/docs/reference/tools.md)
+- [Deployment](/docs/deployment.md)