UHP HTTP API map
Find the UHP 2026-10-04 endpoint for a task, session, artifact or reusable Environment, and check which capability must be advertised before calling it.
Page reviewed 20 Nov 2026 Source and review policy
Transport and auth
Section titled “Transport and auth”Read this map in operation order
Section titled “Read this map in operation order”Use the endpoint families below as a client integration checklist. The first-task guide explains prerequisites; this page locates the wire operations.
- Discover the server and its supported versions before presenting credentials.
- Identify a configured harness and compatible model within the caller’s scope.
- Submit one response request and retain its identity before following events or continuation.
- Resolve the terminal task result before fetching artifacts or starting a dependent turn.
- Use session, sharing, plugin or Environment operations only at the class/capability advertised for them.
| If your client receives… | Inspect before the next request |
|---|---|
| A discovery document | Protocol identity, version membership, class and capability consistency |
| An accepted response | Its response ID, status and selected harness/model metadata |
| A partial result | Terminal cause and output; partial content alone is not success |
| A file or artifact reference | Its authorized retrieval route and ownership scope |
| An error | HTTP status, machine-readable type/code, negotiated version and safe retry conditions |
Configure tool authority at the harness layer. Sending Responses-shaped tools or include does not grant capability: the task contract reserves and ignores them and reports that in metadata.ignored_fields. An SDK accepting the JSON is insufficient evidence that the operation had the intended effect.
- All requests are HTTP over TLS (loopback plaintext is permitted for development).
- Every endpoint except
GET /v1/uhprequiresAuthorization: Bearer <token>. - Version is negotiated with the
UHP-Versionrequest/response header; every response, including errors, carries the version actually used. - Before using anything above Core, read
GET /v1/uhpand rely only on advertised capabilities.
1. Discovery and versioning
Section titled “1. Discovery and versioning”| Endpoint | Method | Purpose | Class |
|---|---|---|---|
/v1/uhp | GET | Capability discovery: protocol versions, default version, conformance class, capability booleans, plugin schemas when applicable, and implementation identity. Served without a bearer token. | Always |
UHP-Version (header) | request / response | Declare or learn the negotiated protocol version; absent on request means the server’s default. | Always |
A server implementing Harness Plugins advertises the plugins capability and supported plugin_schemas. A server can conform to 2026-09-28 while reporting plugins: false and environments: false. Discover each independently. A server that can end a task by asking the person advertises the separate input_requests capability; a server that does not never ends a turn with incomplete_details.reason input_required.
2. Harnesses, models and plugins
Section titled “2. Harnesses, models and plugins”| Endpoint | Method | Purpose | Class |
|---|---|---|---|
/v1/harnesses | GET | List configured harnesses in the caller’s scope (the list MAY be empty). | Core |
/v1/harnesses/{harness_id} | GET | Fetch one harness object; 404 with harness_not_found if unknown. | Core |
/v1/models | GET | Model catalog grouped by backend, with per-model availability. | Core |
/v1/harnesses/{harness_id}/models | GET | Models available for a specific harness. | Core |
/v1/harnesses | POST | Create a harness; 422 with unsupported_base for an unsupported base. Takes an optional Idempotency-Key, honoured when the harness_idempotency capability is advertised. | Full |
/v1/harnesses/{harness_id} | PUT | Replace mutable configuration. MUST NOT change id, base, or createdAt. | Full |
/v1/harnesses/{harness_id} | DELETE | Delete a harness. MUST NOT delete its sessions or responses. | Full |
/v1/harnesses/{harness_id}/skills/{skill_id}/files | GET | List a direct skill’s complete file set for round-trip integrity. | Full |
/v1/harnesses/{harness_id}/plugins/{plugin_name}/files | GET | Retrieve the stored files for one installed Agent Plugins package. | Full, plugins capability |
/v1/harnesses/{harness_id}/export | POST | Export the configured harness as an installable Agent Plugins package, omitting credentials and recording omissions. | Full, plugins capability |
Harness Plugins
Section titled “Harness Plugins”UHP 2026-09-12 adds a plugins array to the harness surface. A plugin is an Agent Plugins 1.0.0 package; UHP does not define a competing package format. The server derives manifest, mcpServers, skills and skipped from the package, preserves direct harness mcpServers/skills as separate configuration, and combines enabled direct/plugin components when the harness runs.
The sub-protocol supports Agent Plugins stdio MCP entries because the package supplies the filesystem roots required to materialize the process inside the agent sandbox. Read Harness Plugins for package and export semantics.
3. Responses and tasks
Section titled “3. Responses and tasks”| Endpoint | Method | Purpose | Class |
|---|---|---|---|
/v1/responses | POST | Run a task. Bodies carry input, model, metadata.harness_id, stream, previous_response_id, optional budgets/instructions, and Responses-compatible reserved tools/include fields. | Core |
/v1/responses/{response_id} | GET | Read a stored response back. | Core |
/v1/responses/{response_id}/input_items | GET | Reconstruct the input the task was created with. | Core |
/v1/responses/{response_id}/cancel | POST | Cancel a running task. | Core |
/v1/responses/{response_id} | DELETE | Delete a stored response. MUST NOT cancel a running task. | Core |
Idempotency-Key (header) | request | Make a submit idempotent when the idempotency capability is advertised; on POST /v1/harnesses it makes a create idempotent when the separate harness_idempotency capability is advertised. The key is the client’s to keep unique: the reference implementation dedupes a repeated key within the session that sent it, and a key reused in another session starts that session’s own work rather than returning the first session’s turn. | Capability |
A task can end by asking the person
Section titled “A task can end by asking the person”With the input_requests capability, a harness that needs one answer — a choice between alternatives, a confirmation before an action that cannot be undone, a value it must not guess, a secret it must not invent — ends the turn rather than inventing one:
- The response ends
incomplete, withincomplete_details.reasoninput_required. Nothing waits: the turn is over and its working directory is kept as after any turn. The question stands until it is answered, passed over, or expires. - The question is the response’s last
input_requestitem, carrying its ownid,status,kind(choice,confirmation,textorsecret), itsoptionsand itsexpires_at. The turn’s lastmessagecarries the question as text as well, so a client that renders onlymessageitems shows it. - The answer is an
input_responseitem on the next task, chained on that response withprevious_response_id. It stands alone in theinputarray, with norole. A request carries at most one. - Anything else chained on that response passes the question over, and the server says which happened.
Three refusals name what went wrong with an answer: input_not_pending (409 — the response has no pending request for it: unknown, already answered, or passed over), input_request_expired (410 — the answer came after the request’s expires_at, so the harness has to ask again) and input_response_invalid (422 — the answer does not fit the request’s kind or options; the request stays pending). A confirm has to offer both answers, or none for yes and no — a lone yes is refused and the agent is told why — and the question’s text and the option’s id are quoted when the answer goes back, so a question cannot pass off its own words as a message from the person.
Reserved tools and include
Section titled “Reserved tools and include”Current UHP source explicitly marks tools and include as reserved and ignored. A conformant server accepts a request carrying them, does not act on them, and names each carried reserved field in the returned Response’s metadata.ignored_fields. A request that carried neither must not be told either was ignored.
Do not use tools as a per-request capability or MCP grant. UHP’s tool loop belongs to the configured harness, and widening the harness’s configured authority from an ordinary task request would be an escalation primitive. Configure direct MCP servers/skills on the harness or install an authorized Harness Plugin instead.
4. Sessions, deletion, sharing and cancellation
Section titled “4. Sessions, deletion, sharing and cancellation”| Endpoint | Method | Purpose | Class |
|---|---|---|---|
/v1/sessions | GET | List sessions, cursor-paginated. | Extended |
/v1/sessions/{session_id} | GET | Inspect a session. | Extended |
/v1/sessions/{session_id}/turns | GET | Ordered task history. Turn items carry id and status and SHOULD carry available user/assistant/tool/file content. | Extended |
/v1/sessions/{session_id}/cancel | POST | Cancel whatever is running in the session. | Extended |
/v1/sessions/{session_id} | DELETE | Canonical session deletion path. Cancels any in-flight task first, deletes stored history/working-folder state, makes the session unreadable, and requires a later GET of the session to return 404. | Full |
/v1/sessions/{session_id}/share | POST | Publish a read-only shared view. The protocol form is bodyless POST; compatible implementations MAY also accept an enabled body. | Full, optional capability |
/v1/sessions/{session_id}/share | GET | Read the session’s share object. A published share carries a required url, which MAY be relative to the UHP base URL. | Full, optional capability |
/v1/sessions/{session_id}/share | DELETE | Revoke sharing. Revocation applies to every link minted for the session. | Full, optional capability |
Branch a session from an earlier response
Section titled “Branch a session from an earlier response”A request that carries previous_response_id and the top-level branch: true starts a new session from that response’s committed files and the transcript up to it. The original session, its working files and its transcript are left exactly as they were, so a branch never rewrites the line it came from. The answer carries a new metadata.session_id and metadata.branched_from naming the response it branched from; the branch’s own session detail carries the origin, and its copied turns are marked imported: true.
This is optional at every class, so read capabilities.session_branching from discovery before sending branch: true. A server without the capability may ignore the field and continue the original session, which is why the capability is read first and the new session id and branched_from are checked afterwards. A response that is still running, or whose checkpoint position was never recorded, cannot be a branch point: the request is refused 409 with code: "branch_unavailable". branch is true, false, null or absent, and null is the same as absent; any other value, and true without previous_response_id, is refused 400 with code: "invalid_input" and param: "branch".
A branch restores the user’s files, not installed dependencies or native CLI state, and it never carries a credential of the source’s turns. The reference implementation copies committed files from Git into a fresh session repository, excluding Git internals, the CLI home, ignored files and dependency directories.
Resume a turn the server cut short
Section titled “Resume a turn the server cut short”A turn the server itself ends — a restart, or a shutdown that drains its running turns — is reported failed with error.detail.reason interrupted. That reason is distinct from a budget stop (max_steps, timeout), from a question (input_required), and from a turn the client cancelled. Beside the reason, the error says what the interruption left behind: workspace is kept, checkpoint or lost, and effects_may_repeat is true when the step that was running may run again.
On a server that advertises the resume capability, the client continues the turn by chaining a resume item on that response in input, the way an input_response answers a question:
{ "previous_response_id": "resp_a1b2c3", "input": [ { "type": "resume", "note": "carry on, but skip the tests" } ] }The note is the person’s words for the harness, and reach it as such. A resume is single-use and explicit: one that names a response that is not interrupted, or one a later task in the session has already resumed or passed over, is refused 409 with code: "resume_not_pending". A server that reports the resume capability MUST accept a resume whose workspace is lost, carrying on from the conversation alone.
Session deletion path and compatibility alias
Section titled “Session deletion path and compatibility alias”The protocol-named operation is DELETE /v1/sessions/{session_id}. The older DELETE /v1/traces/{session_id} predates the session vocabulary. A server MAY continue to serve the old path; the reference implementation keeps it as an alias to the same handler, but clients SHOULD use /v1/sessions/{session_id}.
Deletion is not merely cancellation. The server must cancel live work first, delete the session and its stored transcript/trace/working-folder state, stop that state counting toward enforced storage or memory allowances, answer 2xx, and make a later GET /v1/sessions/{session_id} return 404. Session deletion also makes any published shared view unreadable.
These semantics originated in the preceding 2026-08-11 line and carry forward unchanged into 2026-09-12.
5. Files and artifacts
Section titled “5. Files and artifacts”| Endpoint | Method | Purpose | Class |
|---|---|---|---|
/v1/files | POST | Upload a file (multipart/form-data) and reference it by id. | Extended |
/v1/sessions/{session_id}/files | GET | List every artifact of a session, including earlier tasks. | Extended |
/v1/containers/{container_id}/files/{file_id}/content | GET | Download raw artifact bytes with the file’s own media type. | Extended |
/v1/containers/{container_id}/files/{file_id}/pdf | GET | Rendered PDF preview, if implemented (501/502 otherwise). | Extended |
/v1/sessions/{session_id}/files/archive | GET | Download all session artifacts as one archive. | Extended |
6. Environments, builds and versions
Section titled “6. Environments, builds and versions”All operations below require the optional environments capability. Environment conformance checks are Full-class and capability-gated. The package-spec check is additionally optional even when Environments are supported.
| Endpoint | Method | Purpose |
|---|---|---|
/v1/environments | GET / POST | List or create reusable project state. |
/v1/environments/{id} | GET / PUT / DELETE | Inspect, update metadata or delete all versions; deletion refuses an active build. |
/v1/environments/{id}/files | GET | Read the source tree. |
/v1/environments/{id}/files/{path} | GET / PUT / DELETE | Read/write file bytes or remove a file/directory tree within the Environment root. |
/v1/environments/{id}/directories | POST | Create an empty directory using a path body field. |
/v1/environments/{id}/import | POST | Import an archive body or a JSON git source; replace explicitly clears prior source. |
/v1/environments/runtimes | GET | Discover available build runtimes. |
/v1/environments/packages/check?manager=&spec= | GET | Optional registry check; unsupported servers return 404. |
/v1/environments/{id}/build | POST | Start a new build and receive its version number. |
/v1/environments/{id}/builds/{version} | GET | Inspect status, stage, log and installed packages. |
/v1/environments/{id}/versions | GET | List builds and the active version. |
/v1/environments/{id}/versions/{version}/activate | POST | Activate a finished version, including rollback. |
/v1/environments/{id}/harnesses | GET | Inspect harnesses that reference the Environment. |
Creating or editing source does not make it runnable. A successful build becomes active; a failed build preserves the previous active version. Select the default through the harness’s environment field or override a task through metadata.environment. The Tasks chapter’s top-level environment table row remains stale; the patched schema, Environments chapter and executable checks use metadata. See the field-location evidence and lifecycle.
Object model
Section titled “Object model”The task/session surface operates on harness, response, session, file, container and streamed event objects, and on the two item kinds the asking-the-person flow adds — input_request and input_response — which travel through the same stream as every other item type. A response is one task; a session chains responses that share context and a working directory; a container holds a session’s files. Harness Plugins are configuration packages attached to a harness and exposed through the optional plugin capability rather than a replacement task/session object model.
Related pages
Section titled “Related pages”Read getting started, conformance, architecture, Harness Plugins, the specification guide, and HarnessRouter Community Edition.
Primary sources
Section titled “Primary sources”- UHP 2026-09-28 specification at v0.29.0
- Environments endpoint contract at v0.29.0
- Patched task schema at v0.29.0
The following September sources document the inherited surface and its introduction:
- UHP current protocol README
- UHP 2026-09-12 specification directory
- UHP 2026-09-12 Plugins chapter
- PR #165 — Harness Plugins and UHP 2026-09-12
- UHP 2026-09-12 Tasks source, read at
a7406cbd - UHP 2026-09-12 Sessions source, read at
a7406cbd - UHP 2026-09-12 Files source, read at
a7406cbd - PR #46 — reserved request-field semantics
- PR #60 — protocol-named session deletion and F-08
- PR #53 — session-sharing source/schema clarification
- PR #55 — R-08 bodyless share-publication check