UHP HTTP API map
Find the UHP 2026-09-28 endpoint for a task, session, artifact or reusable Environment, and check which capability must be advertised before calling it.
Page reviewed 4 Oct 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.
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. | 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. | Capability |
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 |
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. 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
- Current UHP 2026-09-12 Tasks source
- Current UHP 2026-09-12 Sessions source
- Current UHP 2026-09-12 Files source
- 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