Skip to content
UHPUHPDeveloper Guide
Independent developer guide. Not affiliated with HarnessRouter or the official UHP project.

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

Protocol: 2026-10-19Static SSG

Use the endpoint families below as a client integration checklist. The first-task guide explains prerequisites; this page locates the wire operations.

  1. Discover the server and its supported versions before presenting credentials.
  2. Identify a configured harness and compatible model within the caller’s scope.
  3. Submit one response request and retain its identity before following events or continuation.
  4. Resolve the terminal task result before fetching artifacts or starting a dependent turn.
  5. 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 documentProtocol identity, version membership, class and capability consistency
An accepted responseIts response ID, status and selected harness/model metadata
A partial resultTerminal cause and output; partial content alone is not success
A file or artifact referenceIts authorized retrieval route and ownership scope
An errorHTTP 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/uhp requires Authorization: Bearer <token>.
  • Version is negotiated with the UHP-Version request/response header; every response, including errors, carries the version actually used.
  • Before using anything above Core, read GET /v1/uhp and rely only on advertised capabilities.
EndpointMethodPurposeClass
/v1/uhpGETCapability 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 / responseDeclare 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.

EndpointMethodPurposeClass
/v1/harnessesGETList configured harnesses in the caller’s scope (the list MAY be empty).Core
/v1/harnesses/{harness_id}GETFetch one harness object; 404 with harness_not_found if unknown.Core
/v1/modelsGETModel catalog grouped by backend, with per-model availability.Core
/v1/harnesses/{harness_id}/modelsGETModels available for a specific harness.Core
/v1/harnessesPOSTCreate 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}PUTReplace mutable configuration. MUST NOT change id, base, or createdAt.Full
/v1/harnesses/{harness_id}DELETEDelete a harness. MUST NOT delete its sessions or responses.Full
/v1/harnesses/{harness_id}/skills/{skill_id}/filesGETList a direct skill’s complete file set for round-trip integrity.Full
/v1/harnesses/{harness_id}/plugins/{plugin_name}/filesGETRetrieve the stored files for one installed Agent Plugins package.Full, plugins capability
/v1/harnesses/{harness_id}/exportPOSTExport the configured harness as an installable Agent Plugins package, omitting credentials and recording omissions.Full, plugins capability

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.

EndpointMethodPurposeClass
/v1/responsesPOSTRun 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}GETRead a stored response back.Core
/v1/responses/{response_id}/input_itemsGETReconstruct the input the task was created with.Core
/v1/responses/{response_id}/cancelPOSTCancel a running task.Core
/v1/responses/{response_id}DELETEDelete a stored response. MUST NOT cancel a running task.Core
Idempotency-Key (header)requestMake 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

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, with incomplete_details.reason input_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_request item, carrying its own id, status, kind (choice, confirmation, text or secret), its options and its expires_at. The turn’s last message carries the question as text as well, so a client that renders only message items shows it.
  • The answer is an input_response item on the next task, chained on that response with previous_response_id. It stands alone in the input array, with no role. 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.

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”
EndpointMethodPurposeClass
/v1/sessionsGETList sessions, cursor-paginated.Extended
/v1/sessions/{session_id}GETInspect a session.Extended
/v1/sessions/{session_id}/turnsGETOrdered task history. Turn items carry id and status and SHOULD carry available user/assistant/tool/file content.Extended
/v1/sessions/{session_id}/cancelPOSTCancel whatever is running in the session.Extended
/v1/sessions/{session_id}DELETECanonical 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}/sharePOSTPublish 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}/shareGETRead 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}/shareDELETERevoke sharing. Revocation applies to every link minted for the session.Full, optional capability

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.

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.

EndpointMethodPurposeClass
/v1/filesPOSTUpload a file (multipart/form-data) and reference it by id.Extended
/v1/sessions/{session_id}/filesGETList every artifact of a session, including earlier tasks.Extended
/v1/containers/{container_id}/files/{file_id}/contentGETDownload raw artifact bytes with the file’s own media type.Extended
/v1/containers/{container_id}/files/{file_id}/pdfGETRendered PDF preview, if implemented (501/502 otherwise).Extended
/v1/sessions/{session_id}/files/archiveGETDownload all session artifacts as one archive.Extended

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.

EndpointMethodPurpose
/v1/environmentsGET / POSTList or create reusable project state.
/v1/environments/{id}GET / PUT / DELETEInspect, update metadata or delete all versions; deletion refuses an active build.
/v1/environments/{id}/filesGETRead the source tree.
/v1/environments/{id}/files/{path}GET / PUT / DELETERead/write file bytes or remove a file/directory tree within the Environment root.
/v1/environments/{id}/directoriesPOSTCreate an empty directory using a path body field.
/v1/environments/{id}/importPOSTImport an archive body or a JSON git source; replace explicitly clears prior source.
/v1/environments/runtimesGETDiscover available build runtimes.
/v1/environments/packages/check?manager=&spec=GETOptional registry check; unsupported servers return 404.
/v1/environments/{id}/buildPOSTStart a new build and receive its version number.
/v1/environments/{id}/builds/{version}GETInspect status, stage, log and installed packages.
/v1/environments/{id}/versionsGETList builds and the active version.
/v1/environments/{id}/versions/{version}/activatePOSTActivate a finished version, including rollback.
/v1/environments/{id}/harnessesGETInspect 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.

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.

Read getting started, conformance, architecture, Harness Plugins, the specification guide, and HarnessRouter Community Edition.

The following September sources document the inherited surface and its introduction: