Unified Harness Protocol

https://unifiedharnessprotocol.org
Admin
Unified Harness Protocol is an open standard and shared contract for running complete AI agent...
Tokens:39,934
Snippets:377
Trust Score:4.2
Update:1 month ago
Show doc for...
Tokens:
Raw
### GET /v1/harnesses

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Lists available harnesses.

```APIDOC
## GET /v1/harnesses

### Description
Lists all available harnesses.

### Method
GET

### Endpoint
/v1/harnesses
```

--------------------------------

### GET /v1/models

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Lists available models.

```APIDOC
## GET /v1/models

### Description
Lists all available models.

### Method
GET

### Endpoint
/v1/models
```

--------------------------------

### Run the conformance suite

Source: https://unifiedharnessprotocol.org/serving

Install the conformance suite and run it against your server to verify compliance with the core contract.

```bash
pip install -e protocol/conformance
uhp-conformance --base-url https://your-server --api-key "$KEY" --class core
```

--------------------------------

### GET /v1/sessions/{id}/files

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Lists files for a session.

```APIDOC
## GET /v1/sessions/{id}/files

### Description
Lists files associated with a specific session.

### Method
GET

### Endpoint
/v1/sessions/{id}/files

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.
```

--------------------------------

### GET /v1/sessions

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Lists sessions.

```APIDOC
## GET /v1/sessions

### Description
Lists all sessions.

### Method
GET

### Endpoint
/v1/sessions
```

--------------------------------

### Simple String Input

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/tasks

A basic input example using a single string to define the task.

```json
{ "input": "Summarise README.md" }
```

--------------------------------

### GET /v1/uhp

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves core protocol information.

```APIDOC
## GET /v1/uhp

### Description
Retrieves core information about the Unified Harness Protocol implementation.

### Method
GET

### Endpoint
/v1/uhp
```

--------------------------------

### Run UHP Conformance Suite

Source: https://unifiedharnessprotocol.org/

Install the conformance package and execute the suite against a server using the specified base URL and API key.

```bash
pip install -e protocol/conformance
uhp-conformance --base-url https://your-server --api-key "$KEY"
```

--------------------------------

### Select harness via metadata

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/tasks

Example of specifying the harness_id within the metadata object to select a configured harness.

```json
{ "metadata": { "harness_id": "chrn_…" } }
```

--------------------------------

### Run UHP Conformance Suite

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Install the conformance package and execute the test suite against a server using the specified base URL, API key, and conformance class.

```bash
pip install -e protocol/conformance
uhp-conformance --base-url https://your-server --api-key "$KEY" --class extended
```

--------------------------------

### GET /v1/harnesses/{id}/models

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Lists models for a specific harness.

```APIDOC
## GET /v1/harnesses/{id}/models

### Description
Lists models associated with a specific harness.

### Method
GET

### Endpoint
/v1/harnesses/{id}/models

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the harness.
```

--------------------------------

### GET /v1/harnesses/{harness_id}/skills/{skill_id}/files

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/harnesses

Retrieves the complete file list for a specific skill associated with a harness.

```APIDOC
## GET /v1/harnesses/{harness_id}/skills/{skill_id}/files

### Description
Retrieves the complete file list for a specific skill associated with a harness.

### Method
GET

### Endpoint
/v1/harnesses/{harness_id}/skills/{skill_id}/files

### Parameters
#### Path Parameters
- **harness_id** (string) - Required - The unique identifier of the harness.
- **skill_id** (string) - Required - The unique identifier of the skill.
```

--------------------------------

### GET /v1/containers/{cid}/files/{fid}/pdf

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves file as PDF.

```APIDOC
## GET /v1/containers/{cid}/files/{fid}/pdf

### Description
Retrieves a specific file as a PDF.

### Method
GET

### Endpoint
/v1/containers/{cid}/files/{fid}/pdf

### Parameters
#### Path Parameters
- **cid** (string) - Required - The container ID.
- **fid** (string) - Required - The file ID.
```

--------------------------------

### Harness Management Endpoints

Source: https://unifiedharnessprotocol.org/schema/uhp-2026-08-11.openapi.yaml

Defines the GET and POST operations for listing and creating configured harnesses under /v1/harnesses.

```yaml
/v1/harnesses:
    get:
      tags: [Harnesses]
      operationId: listHarnesses
      summary: List configured harnesses
      responses:
        '200':
          description: Harnesses within the caller's scope. May be empty.
          content:
            application/json:
              schema:
                type: object
                required: [harnesses]
                properties:
                  harnesses:
                    type: array
                    items: { $ref: '#/components/schemas/Harness' }
        '401': { $ref: '#/components/responses/Unauthorized' }
    post:
      tags: [Harnesses]
      operationId: createHarness
      summary: Create a configured harness
      description: Conformance class Full. Check the `harness_management` capability first.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/HarnessCreate' }
      responses:
        '200':
          description: The created harness
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Harness' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '422': { $ref: '#/components/responses/UnprocessableEntity' }
```

--------------------------------

### GET /v1/sessions/{session_id}/files

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/files

Lists all artifacts associated with a specific session.

```APIDOC
## GET /v1/sessions/{session_id}/files

### Description
Retrieves a list of all artifacts produced during the specified session.

### Method
GET

### Endpoint
/v1/sessions/{session_id}/files

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **files** (array) - A list of file objects containing id, container_id, filename, bytes, and created_at.
```

--------------------------------

### GET /v1/models

Source: https://unifiedharnessprotocol.org/schema/uhp-2026-08-11.openapi.yaml

Retrieves the model catalogue, grouped by backend, including availability information.

```APIDOC
## GET /v1/models

### Description
Retrieves the model catalogue, grouped by backend, including availability information.

### Method
GET

### Endpoint
/v1/models
```

--------------------------------

### Complex Array Input

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/tasks

An input example using an array of items, supporting both text and file data.

```json
{
  "input": [
    { "role": "user", "content": [
        { "type": "input_text", "text": "Summarise this report." },
        { "type": "input_file", "filename": "q3.pdf", "file_data": "data:application/pdf;base64,…" }
    ]}
  ]
}
```

--------------------------------

### List sessions with GET /v1/sessions

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/sessions

Retrieves a list of sessions. Pagination is cursor-based, and the server must return next_cursor: null on the last page.

```http
GET /v1/sessions?limit=20&cursor=&harness=chrn_…
```

```json
{
  "sessions": [
    {
      "id": "hsess7e78…",
      "object": "session",
      "harness_id": "chrn_…",
      "title": "Summarise README.md",
      "status": "completed",
      "created_at": 1786400000,
      "updated_at": 1786400240
    }
  ],
  "next_cursor": null
}
```

--------------------------------

### GET /v1/containers/{container_id}/files/{file_id}/pdf

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/files

Requests a rendered PDF preview of a document.

```APIDOC
## GET /v1/containers/{container_id}/files/{file_id}/pdf

### Description
Requests a rendered preview of the specified file in PDF format.

### Method
GET

### Endpoint
/v1/containers/{container_id}/files/{file_id}/pdf

### Parameters
#### Path Parameters
- **container_id** (string) - Required - The ID of the container.
- **file_id** (string) - Required - The ID of the file.

### Response
#### Success Response (200)
- **pdf** (binary) - The rendered PDF content.
```

--------------------------------

### Discover all harnesses via GET /v1/harnesses

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/harnesses

Retrieves a list of available harnesses within the caller's scope. The response includes an array of harness objects, which may be empty if no harnesses are configured.

```http
GET /v1/harnesses
```

```json
{
  "harnesses": [
    {
      "id": "chrn_08dae611630d467ab3e67ed792570ae5",
      "object": "harness",
      "name": "Research agent",
      "base": "claude-code",
      "baseLabel": "Claude Code",
      "defaultModel": "claude-sonnet-4.6",
      "systemPrompt": "",
      "mcpServers": [],
      "skills": [],
      "disabledTools": [],
      "maxStep": null,
      "timeoutSeconds": null,
      "createdAt": 1786403298205
    }
  ]
}
```

--------------------------------

### Capability discovery endpoint

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/lifecycle

Clients use this GET request to determine if a server supports UHP and to discover its capabilities.

```http
GET /v1/uhp
```

--------------------------------

### Retrieve a specific harness via GET /v1/harnesses/{harness_id}

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/harnesses

Fetches a single harness object by its ID. Returns a 404 error with code "harness_not_found" if the ID does not exist.

```http
GET /v1/harnesses/{harness_id}
```

--------------------------------

### Discover harnesses and execute tasks

Source: https://unifiedharnessprotocol.org/

Use the first command to list available harnesses and the second to initiate a task with streaming enabled. The stream uses Server-Sent Events, and subsequent requests should include the previous_response_id to maintain conversation context.

```bash
curl -s https://your-uhp-server/v1/harnesses -H "Authorization: Bearer $KEY"
```

```bash
curl -s -N https://your-uhp-server/v1/responses \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{
        "input": "Summarise README.md in three bullets.",
        "model": "claude-sonnet-4.6",
        "metadata": { "harness_id": "chrn_…" },
        "stream": true
      }'
```

--------------------------------

### GET /v1/sessions/{id}

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves session details.

```APIDOC
## GET /v1/sessions/{id}

### Description
Retrieves details for a specific session.

### Method
GET

### Endpoint
/v1/sessions/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.
```

--------------------------------

### GET /v1/sessions/{id}/turns

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves turns for a session.

```APIDOC
## GET /v1/sessions/{id}/turns

### Description
Retrieves the turns associated with a specific session.

### Method
GET

### Endpoint
/v1/sessions/{id}/turns

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.
```

--------------------------------

### POST /v1/harnesses

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Creates a new harness.

```APIDOC
## POST /v1/harnesses

### Description
Creates a new harness.

### Method
POST

### Endpoint
/v1/harnesses
```

--------------------------------

### GET /v1/responses/{id}

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves a specific task response.

```APIDOC
## GET /v1/responses/{id}

### Description
Retrieves a specific task response by its ID.

### Method
GET

### Endpoint
/v1/responses/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the response.
```

--------------------------------

### Run a task request

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/tasks

The POST request to /v1/responses to initiate a task, including headers and the JSON body.

```http
POST /v1/responses
Authorization: Bearer <token>
Content-Type: application/json
```

```json
{
  "input": "Summarise README.md in three bullets.",
  "model": "claude-sonnet-4.6",
  "metadata": { "harness_id": "chrn_08dae611630d467ab3e67ed792570ae5" },
  "stream": true
}
```

--------------------------------

### GET /v1/harnesses/{id}

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves details for a specific harness.

```APIDOC
## GET /v1/harnesses/{id}

### Description
Retrieves details for a specific harness by its ID.

### Method
GET

### Endpoint
/v1/harnesses/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the harness.
```

--------------------------------

### GET /v1/sessions/{id}/share

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves session share information.

```APIDOC
## GET /v1/sessions/{id}/share

### Description
Retrieves share information for a specific session.

### Method
GET

### Endpoint
/v1/sessions/{id}/share

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the session.
```

--------------------------------

### Generate Python client with openapi-python-client

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/schema

Use the openapi-python-client CLI to generate a Python client from the OpenAPI specification.

```bash
openapi-python-client generate --path protocol/schema/uhp-2026-08-11.openapi.yaml
```

--------------------------------

### Define Harness Skills

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/harnesses

Configure skills as folders containing necessary files, scripts, and assets.

```json
{ "skills": [
    { "name": "vault-manual", "enabled": true, "files": [
        { "path": "SKILL.md",            "content": "---\nname: vault-manual\n---\n…" },
        { "path": "references/codes.md", "content": "…" },
        { "path": "scripts/helper.sh",   "content": "#!/bin/sh\n…" },
        { "path": "assets/logo.png",     "content_b64": "iVBORw0KGgo…" }
    ]}
] }
```

--------------------------------

### GET /v1/responses/{id}/input_items

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves input items for a response.

```APIDOC
## GET /v1/responses/{id}/input_items

### Description
Retrieves input items for a specific task response.

### Method
GET

### Endpoint
/v1/responses/{id}/input_items

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the response.
```

--------------------------------

### Retrieve Skill Files

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/harnesses

Fetch the complete file list for a specific skill within a harness.

```http
GET /v1/harnesses/{harness_id}/skills/{skill_id}/files
```

--------------------------------

### GET /v1/sessions/{session_id}/share

Source: https://unifiedharnessprotocol.org/schema/uhp-2026-08-11.openapi.yaml

Retrieves the current share status of a session.

```APIDOC
## GET /v1/sessions/{session_id}/share

### Description
Read the session's share back.

### Method
GET

### Endpoint
/v1/sessions/{session_id}/share

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
- **SessionShare** (object) - The share object.
```

--------------------------------

### HarnessRouter reference implementation test summary

Source: https://unifiedharnessprotocol.org/conformance

The output of the HarnessRouter reference implementation test suite run on 2026-09-04.

```text
  Summary
    64/64 passed · 0 failed · 0 skipped · 0 errored
    CONFORMANT — UHP 2026-08-11 (full)
```

--------------------------------

### GET /v1/sessions/{session_id}/turns

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/sessions

Retrieves the ordered task history of a session.

```APIDOC
## GET /v1/sessions/{session_id}/turns

### Description
Returns the ordered task history of the session, allowing a client to rebuild a transcript.

### Method
GET

### Endpoint
/v1/sessions/{session_id}/turns

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session.

### Response
#### Success Response (200)
- **id** (string) - The response id of the turn.
- **status** (string) - The turn's status.
```

--------------------------------

### Create a harness

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/harnesses

Sends a POST request to /v1/harnesses to create a new harness. The base field is required and must be supported by the server.

```http
POST /v1/harnesses
```

```json
{ "name": "Research agent", "base": "claude-code", "default_model": "claude-sonnet-4.6" }
```

--------------------------------

### List Available Models

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/harnesses

Retrieve the list of available models from the server.

```http
GET /v1/models
```

```json
{
  "backends": {
    "claude": {
      "default": "claude-sonnet-4.6",
      "models": [
        { "id": "claude-sonnet-4.6", "label": "claude-sonnet-4.6", "backend": "claude",
          "available": true, "default": true }
      ]
    }
  }
}
```

--------------------------------

### GET /v1/containers/{cid}/files/{fid}/content

Source: https://unifiedharnessprotocol.org/spec/2026-08-11

Retrieves file content.

```APIDOC
## GET /v1/containers/{cid}/files/{fid}/content

### Description
Retrieves the content of a specific file within a container.

### Method
GET

### Endpoint
/v1/containers/{cid}/files/{fid}/content

### Parameters
#### Path Parameters
- **cid** (string) - Required - The container ID.
- **fid** (string) - Required - The file ID.
```

--------------------------------

### POST /v1/responses

Source: https://unifiedharnessprotocol.org/

Executes a task on a specific harness and returns a stream of events.

```APIDOC
## POST /v1/responses

### Description
Run a task on a harness and receive a stream of Server-Sent Events. The final event contains the completed response object.

### Method
POST

### Endpoint
/v1/responses

### Request Body
- **input** (string) - Required - The task prompt or input.
- **model** (string) - Required - The model identifier to use.
- **metadata** (object) - Optional - Contains harness_id for the task.
- **stream** (boolean) - Optional - Whether to stream the response.
- **previous_response_id** (string) - Optional - Used to continue a conversation from a previous response.
```

--------------------------------

### GET /v1/sessions/{session_id}/files/archive

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/files

Downloads all artifacts of a session as a single archive.

```APIDOC
## GET /v1/sessions/{session_id}/files/archive

### Description
Returns every artifact of the session as a single archive file.

### Method
GET

### Endpoint
/v1/sessions/{session_id}/files/archive

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The ID of the session.

### Response
#### Success Response (200)
- **archive** (binary) - The archive containing all session artifacts.
```

--------------------------------

### List Session Files

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/files

Retrieve a list of all artifacts associated with a specific session.

```http
GET /v1/sessions/{session_id}/files
```

```json
{ "files": [ { "id": "file_…", "container_id": "cntr_…", "filename": "report.md",
               "bytes": 2048, "created_at": 1786400240 } ] }
```

--------------------------------

### GET /v1/responses/{response_id}

Source: https://unifiedharnessprotocol.org/spec/2026-08-11/streaming

Retrieve a response by its ID to follow a task after a connection disconnect.

```http
GET /v1/responses/{response_id}
```
Tokens:
Raw