curl --request POST \
  --url http://localhost:8000/harness/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Hello",
  "harness_name": "harness",
  "run_agent_request": {
    "user_id": "user-001",
    "session_id": "session-001"
  }
}
'

{
  "harness_name": "harness",
  "overwrite": false,
  "output": "Hello",
  "error": null
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Harness invocation

Invoke Harness

Available only on KeyAuth deployments; waits for completion and returns JSON. Shared OAuth deployments do not expose this endpoint. Overrides apply only to this request, with omitted fields inherited from deployment; harness_merge and harness_enhance are not supported

tools and skills append to existing configuration. mcp_servers replaces the full list, and an empty list clears MCP for this request. Execution failures can still return HTTP 200; inspect error, which is null on success. MCP-only overrides may leave overwrite false

POST

harness

invoke

curl --request POST \
  --url http://localhost:8000/harness/invoke \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "Hello",
  "harness_name": "harness",
  "run_agent_request": {
    "user_id": "user-001",
    "session_id": "session-001"
  }
}
'

{
  "harness_name": "harness",
  "overwrite": false,
  "output": "Hello",
  "error": null
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Use this endpoint on KeyAuth deployments, with text in prompt and user/session identifiers in run_agent_request. harness_name is echoed in the request and response; sessions still use the harness_agent application. Shared OAuth deployments do not expose this endpoint harness applies only to this invocation; omitted fields inherit deployment settings. tools appends registered built-in tools, while mcp_servers replaces the remote MCP list

This endpoint runs the agent and saves session events. It can call models, tools, and cloud resources; retries can repeat external actions

The response arrives after completion. Check that error is null; HTTP 200 or overwrite alone does not establish success. On failure, output is an empty string

Authorizations

Authorization

string

header

required

Optional locally without a gateway; cloud deployments use the Runtime API key or user-pool JWT required by that deployment, never the model API key

Body

application/json

prompt

string

required

User message for this invocation

harness_name

string

required

Harness name echoed in the request and response; sessions use the fixed harness_agent namespace

run_agent_request

RunAgentRequest · object

required

User, session, and model-call limit for this invocation

Show child attributes

harness

HarnessOverrides · object | null

Per-request overrides; omitted fields inherit the deployed configuration

Show child attributes

Response

Invocation result; inspect the error field

harness_name

string

required

Harness name echoed in the request and response; sessions use the fixed harness_agent namespace

output

string

required

Text output after completion; empty on failure

overwrite

boolean

default:false

Whether general Harness overrides were applied; may be false for MCP-only overrides

error

string | null

Invocation error; null on success

Last modified on September 19, 2026

Agent API Server API

Harness Runtime API

Invoke Harness

Authorizations

Body

Response