Normative, not implementation-specific: every endpoint below is taken from the 2026-08-11 specification. HarnessRouter Community Edition is the reference implementation; a different conformant server may implement a subset according to its declared conformance class and capabilities, and may expose additional non-normative routes. Do not treat a HarnessRouter-only route as UHP.
Transport and auth
- 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.
1. Discovery and versioning
| Endpoint | Method | Purpose | Class |
|---|
/v1/uhp | GET | Capability discovery: protocol versions, default version, conformance class, capability booleans, 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 |
2. Harnesses and models
| 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 skill's complete file set for round-trip integrity. | Full |
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, and optional budgets/instructions/tools. | 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 |
4. Sessions 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 of a session. | Extended |
/v1/sessions/{session_id}/cancel | POST | Cancel whatever is running in the session. | Extended |
/v1/sessions/{session_id}/share | POST | Publish a read-only shared view (optional). | Full |
/v1/sessions/{session_id}/share | GET | Fetch the shared view (optional). | Full |
/v1/traces/{session_id} | DELETE | Delete a session and its history; cancels any in-flight task first. | Full |
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 |
Object model
The surface above operates on six object types, each with an object field and a type-distinguishing id prefix: harness (chrn_), response (resp_), session (hsess), file (file_), container (cntr_), 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.
Related pages
Read getting started, conformance, architecture, the specification guide, and HarnessRouter Community Edition.
Primary sources