HarnessRouter

https://harnessrouter.ai/docs
Admin
HarnessRouter is an API router and runtime platform that connects backend applications to...
Tokens:9,963
Snippets:167
Trust Score:6.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Example: Keep build-time and runtime separate

Source: https://harnessrouter.ai/docs/host-app-vs-runtime-agent

This example illustrates the distinction between the build-time requirements for a contract review product and the specific task data sent to the HarnessRouter runtime agent.

```text
Ask your coding agent to build:
A contract review product with upload, progress, preview, download, and revise.

What your product sends to HarnessRouter at runtime:
Review this uploaded agreement and return a checklist, redline notes, and generated files.
```

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

### First frame SSE example

Source: https://harnessrouter.ai/docs/streaming-events

An example of the initial data frame received from the HarnessRouter stream, containing the response ID and session metadata.

```text
data: {"type":"response.created","sequence_number":0,"response":{"id":"resp_...","status":"in_progress","metadata":{"session_id":"hsess..."}}}
```

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

### GET /v1/harnesses

Source: https://harnessrouter.ai/docs/harnesses-api

Lists all configured agents visible to the Workspace key.

```APIDOC
## GET /v1/harnesses

### Description
Lists configured agents visible to the Workspace key.

### Method
GET

### Endpoint
/v1/harnesses
```

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

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

Source: https://harnessrouter.ai/docs/harnesses-api

Reads details for a specific configured agent.

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

### Description
Reads one configured agent.

### Method
GET

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

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

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

### GET /v1/models

Source: https://harnessrouter.ai/docs/models

Retrieves the global model catalog, keyed by backend.

```APIDOC
## GET /v1/models

### Description
Returns the global model catalog keyed by backend.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **backends** (object) - A map of backend identifiers to their respective default models and available model lists.
```

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

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

Source: https://harnessrouter.ai/docs/sessions-and-files

Retrieves an archive of generated files.

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

### Description
Returns generated artifacts as a zip file while preserving folder hierarchy.

### Method
GET

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

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session.
#### Query Parameters
- **changed** (boolean) - Optional - If true, includes only the latest turn.
- **files** (string) - Optional - A comma-separated list of specific file IDs to include.
```

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

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

Source: https://harnessrouter.ai/docs/sessions-and-files

Retrieves details for a specific session.

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

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

### Method
GET

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

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

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

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

Source: https://harnessrouter.ai/docs/files-and-artifacts

Retrieves a PDF rendition of an Office file artifact.

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

### Description
Provides a server-converted PDF preview for supported Office file types.

### Method
GET

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

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier for the session.
- **file_id** (string) - Required - The unique identifier for the file artifact.
```

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

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

Source: https://harnessrouter.ai/docs/models

Retrieves the model set allowed for a specific configured agent.

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

### Description
Returns the model set allowed for one configured agent.

### Method
GET

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

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

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

### GET /v1/sessions

Source: https://harnessrouter.ai/docs/sessions-and-files

Retrieves a list of sessions associated with a specific harness ID.

```APIDOC
## GET /v1/sessions

### Description
Retrieves a list of sessions for a given harness ID.

### Method
GET

### Endpoint
/v1/sessions

### Parameters
#### Query Parameters
- **harness** (string) - Required - The ID of the harness.
- **limit** (integer) - Optional - The maximum number of sessions to return (default 20).
```

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

### GET /v1/containers/{session_id}/files/{file_id}/content

Source: https://harnessrouter.ai/docs/files-and-artifacts

Retrieves the content of a specific file artifact from a session.

```APIDOC
## GET /v1/containers/{session_id}/files/{file_id}/content

### Description
Fetches the raw bytes of a generated file artifact. This URL should be accessed server-side using a Bearer key and the bytes relayed to the client.

### Method
GET

### Endpoint
/v1/containers/{session_id}/files/{file_id}/content

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier for the session.
- **file_id** (string) - Required - The unique identifier for the file artifact.
```

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

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

Source: https://harnessrouter.ai/docs/sessions-and-files

Retrieves files associated with a specific session.

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

### Description
Retrieves files associated with a specific session, with optional filtering for changed files.

### Method
GET

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

### Parameters
#### Path Parameters
- **session_id** (string) - Required - The unique identifier of the session.
#### Query Parameters
- **changed** (boolean) - Optional - If true, returns only files from the latest turn.
```

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

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

Source: https://harnessrouter.ai/docs/sessions-and-files

Retrieves the turns associated with a specific session.

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

### Description
Retrieves the list of turns for a specific session.

### Method
GET

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

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

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

### Model catalog JSON structure

Source: https://harnessrouter.ai/docs/models

The response format for the GET /v1/models endpoint, showing the organization of models by backend.

```json
{
  "backends": {
    "codex": { "default": "<id>", "models": [] },
    "claude": { "default": "<id>", "models": [] },
    "hermes": { "default": "<id>", "models": [] }
  }
}
```

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

### Create a configured agent via POST /v1/harnesses

Source: https://harnessrouter.ai/docs/harnesses-api

Use this request to create a new configured agent. The request body requires a name, base model, default model, and system prompt.

```http
POST /v1/harnesses
Content-Type: application/json

{
  "name": "Contract Review Agent",
  "base": "claude-code",
  "default_model": "<allowed model id>",
  "system_prompt": "<runtime-agent instructions>",
  "mcp_servers": [],
  "skills": []
}
```

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

### POST /v1/harnesses

Source: https://harnessrouter.ai/docs/harnesses-api

Creates a new configured agent.

```APIDOC
## POST /v1/harnesses

### Description
Creates a configured agent.

### Method
POST

### Endpoint
/v1/harnesses

### Request Body
- **name** (string) - Required - The name of the agent
- **base** (string) - Required - The base model or configuration type
- **default_model** (string) - Required - The allowed model ID
- **system_prompt** (string) - Required - Runtime-agent instructions
- **mcp_servers** (array) - Optional - List of MCP servers
- **skills** (array) - Optional - List of skills

### Request Example
{
  "name": "Contract Review Agent",
  "base": "claude-code",
  "default_model": "<allowed model id>",
  "system_prompt": "<runtime-agent instructions>",
  "mcp_servers": [],
  "skills": []
}
```

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

### POST /{harness_id}/v1/responses request

Source: https://harnessrouter.ai/docs/run-a-task

Sends a task input to the configured agent. The Idempotency-Key header is required, and setting stream to true enables visible progress.

```http
POST /{harness_id}/v1/responses
Idempotency-Key: <uuid>
Content-Type: application/json

{
  "input": "Review this uploaded agreement and return a checklist.",
  "stream": true
}
```

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

### Server-side feature to harness mapping

Source: https://harnessrouter.ai/docs/feature-key-to-harness-mapping

Maps product feature keys to specific harness identifiers on the server to ensure secure agent selection.

```javascript
const harnessByFeature = {
  contract_review: "chrn_...",
  game_generation: "chrn_..."
};

const harnessId = harnessByFeature[featureKey];
```

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

### Reference file in input content block

Source: https://harnessrouter.ai/docs/upload-files

Demonstrates how to include an uploaded file in a task input using the input_file type and the corresponding file_id.

```json
{
  "input": [
    {
      "role": "user",
      "content": [
        { "type": "input_file", "file_id": "file_..." },
        { "type": "input_text", "text": "Review this agreement." }
      ]
    }
  ],
  "stream": true
}
```

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

### POST /v1/files

Source: https://harnessrouter.ai/docs/upload-files

Uploads a file to the server to be used as a reference in tasks. Requires a multipart/form-data request.

```APIDOC
## POST /v1/files

### Description
Uploads a file to the server. This is required before the file can be referenced in a task.

### Method
POST

### Endpoint
/v1/files

### Request Body
- **purpose** (string) - Required - The purpose of the file (e.g., "user_data").
- **file** (file) - Required - The file content to upload.

### Request Example
POST /v1/files
Authorization: Bearer $HR_API_KEY
Content-Type: multipart/form-data

purpose=user_data
file=@agreement.docx
```

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

### PUT /v1/harnesses/{id}

Source: https://harnessrouter.ai/docs/harnesses-api

Updates an existing configured agent.

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

### Description
Updates one configured agent.

### Method
PUT

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

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

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

### POST /{harness_id}/v1/responses

Source: https://harnessrouter.ai/docs/run-a-task

Executes a single user task against a configured agent identified by the harness_id.

```APIDOC
## POST /{harness_id}/v1/responses

### Description
Run one user task against a configured agent. Prefer streaming when users need visible progress.

### Method
POST

### Endpoint
/{harness_id}/v1/responses

### Parameters
#### Path Parameters
- **harness_id** (string) - Required - The ID of the configured agent.

#### Request Headers
- **Idempotency-Key** (uuid) - Required - A unique key for request idempotency.
- **Content-Type** (string) - Required - Must be application/json.

#### Request Body
- **input** (string) - Required - The task description or input for the agent.
- **stream** (boolean) - Optional - Whether to enable streaming for the response.

### Request Example
{
  "input": "Review this uploaded agreement and return a checklist.",
  "stream": true
}
```

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

### Server-side proxy flow

Source: https://harnessrouter.ai/docs/server-side-proxy-pattern

A visual representation of the request flow from the browser through the backend to HarnessRouter.

```text
Browser
  -> POST /api/product-feature
  -> validate product user and tenant
  -> map feature_key to harness_id
  -> call HarnessRouter with HR_API_KEY
  -> return product-shaped stream or JSON
```

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

### POST /{harness_id}/v1/responses

Source: https://harnessrouter.ai/docs/continue-a-session

Resumes a session by providing the previous response ID and session metadata to continue work.

```APIDOC
## POST /{harness_id}/v1/responses

### Description
Continues a session from a saved response to perform follow-up work or reconnect to a task context.

### Method
POST

### Endpoint
/{harness_id}/v1/responses

### Parameters
#### Path Parameters
- **harness_id** (string) - Required - The unique identifier for the harness.

#### Request Body
- **input** (string) - Required - The instruction for continuing the work.
- **previous_response_id** (string) - Required - The ID of the response to continue from.
- **metadata** (object) - Required - Contains the session_id.
- **stream** (boolean) - Optional - Whether to stream the response.

### Request Example
{
  "input": "Continue where you left off and finish the remaining work.",
  "previous_response_id": "<response id>",
  "metadata": { "session_id": "<session id>" },
  "stream": true
}
```

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

### Production Base URL

Source: https://harnessrouter.ai/docs/base-url

The base URL for all API requests to the HarnessRouter service.

```APIDOC
## Base URL

### Description
All runtime and management requests should be built against the production HarnessRouter API host.

### Production URL
`https://api.harnessrouter.ai`

### Notes
- All requests must use `/v1` paths as defined in the Unified Harness Protocol.
- Model and harness discovery require a Workspace API key.
```

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

### Upload file via POST /v1/files

Source: https://harnessrouter.ai/docs/upload-files

Uploads a file using a multipart/form-data request. Requires an authorization bearer token and specifies the purpose and file path.

```http
POST /v1/files
Authorization: Bearer $HR_API_KEY
Content-Type: multipart/form-data

purpose=user_data
file=@agreement.docx
```

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

### Production API Base URL

Source: https://harnessrouter.ai/docs/base-url

The base URL for all production API requests.

```text
https://api.harnessrouter.ai
```

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

### Continue session request

Source: https://harnessrouter.ai/docs/continue-a-session

Sends a POST request to the responses endpoint to resume work from a previous response. Requires the previous_response_id and session_id in the metadata.

```http
POST /{harness_id}/v1/responses
Content-Type: application/json

{
  "input": "Continue where you left off and finish the remaining work.",
  "previous_response_id": "<response id>",
  "metadata": { "session_id": "<session id>" },
  "stream": true
}
```

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

### Files response shape

Source: https://harnessrouter.ai/docs/files-and-artifacts

The JSON structure returned when fetching files, containing session metadata and a list of file objects with their respective paths, sizes, and download URLs.

```json
{
  "session_id": "hsess...",
  "count": 1,
  "files": [
    {
      "path": "index.html",
      "bytes": 12117,
      "media_type": "text/html",
      "file_id": "cfile_...",
      "download_url": "https://api.harnessrouter.ai/v1/containers/hsess.../files/cfile.../content"
    }
  ]
}
```

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

### Authentication Header

Source: https://harnessrouter.ai/docs/authentication

The HarnessRouter API requires authentication via a Bearer token passed in the Authorization header. This must be performed server-side to ensure the API key is not exposed to the browser.

```APIDOC
## Authentication

### Description
Authenticate requests to the HarnessRouter API using a Bearer token. This method must be implemented on the server side; the browser should never call the API directly with the Workspace API key.

### Header
- **Authorization**: Bearer $HR_API_KEY
```

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

### POST /v1/sessions/{session_id}/cancel

Source: https://harnessrouter.ai/docs/cancel-a-session

Cancels a running session explicitly. This should be used when a user intentionally stops work, as closing an SSE connection does not stop the server-side agent.

```APIDOC
## POST /v1/sessions/{session_id}/cancel

### Description
Cancels a running session explicitly. Closing an SSE connection does not stop the server-side agent, so this endpoint should be used when the user intentionally stops work.

### Method
POST

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

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

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

### Authorization Header

Source: https://harnessrouter.ai/docs/authentication

The Authorization header must include the Bearer token using the $HR_API_KEY environment variable.

```http
Authorization: Bearer $HR_API_KEY
```

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

### DELETE /v1/harnesses/{id}

Source: https://harnessrouter.ai/docs/harnesses-api

Deletes a specific configured agent.

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

### Description
Deletes one configured agent.

### Method
DELETE

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

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

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

### Cancel session POST request

Source: https://harnessrouter.ai/docs/cancel-a-session

The endpoint used to explicitly cancel a running session by its ID.

```http
POST /v1/sessions/{session_id}/cancel
```
Tokens:
Raw