POST /v1/harnesses

POST

/v1/harnesses

• Production API

Request Body ^required

Request to create a new harness

object

capabilities

Capabilities to enable with per-harness configuration.

Array<object>

Per-agent capability configuration

Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.

object

config

Per-agent configuration for this capability (capability-specific)

ref

required

Reference to the capability ID

string

Example

[
  {
    "config": {},
    "ref": "current_time"
  },
  {
    "config": {},
    "ref": "web_fetch"
  }
]

default_model_id

Default LLM model ID for this harness. Lowest priority in model chain.

string | null

Example

model_01933b5a00007000800000000000001

description

Description of what the harness does.

string | null

Example

Research harness with planning and web capabilities

display_name

required

Human-readable display name shown in UI.

string

Example

Deep Research

initial_files

Starter files copied into each new session for this harness.

Array<object>

Starter file copied into a new session from an agent or harness.

object

content

required

File content: plain text or base64-encoded binary.

string

encoding

Content encoding: text or base64.

string

is_readonly

Prevent session-side edits or deletes when true.

boolean

path

required

Absolute path within the session workspace. /workspace prefix is accepted.

string

name

required

URL/CLI-friendly addressable name, unique per org. Format: lowercase alphanumeric and hyphens, like a GitHub repo name.

string

Example

deep-research

network_access

One of:

null

null

object

Network access list controlling which hosts/URLs sessions can reach.

object

allowed

Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).

Array<string>

blocked

Blocked host patterns. Always denied, even if matched by allowed.

Array<string>

parent_harness_id

Optional parent harness to inherit from.

string | null

Example

harness_01933b5a000070008000000000000602

system_prompt

required

The system prompt defining the harness’s base behavior.

string

Example

You are a research assistant with deep analytical capabilities.

tags

Tags for organizing harnesses.

Array<string>

Example

[
  "research",
  "planning"
]

Responses

201

Harness created

Harness configuration for sessions. A harness defines the base behavior and capabilities that apply to all sessions.

object

archived_at

Timestamp when the harness was archived.

string | null format: date-time

capabilities

Capabilities enabled for this harness with per-harness configuration.

Array<object>

Per-agent capability configuration

Associates a capability with an agent, including optional per-agent configuration. The config field allows the same capability to behave differently per-agent.

object

config

Per-agent configuration for this capability (capability-specific)

ref

required

Reference to the capability ID

string

created_at

required

Timestamp when the harness was created.

string format: date-time

default_model_id

Default LLM model ID for this harness. Lowest priority in chain: controls > session > agent > harness.

string | null

Example

model_01933b5a00007000800000000000001

deleted_at

Timestamp when the harness was deleted.

string | null format: date-time

description

Human-readable description of what the harness does.

string | null

display_name

required

Human-readable display name shown in UI.

string

id

required

Unique identifier for the harness (format: harness_{32-hex}).

string

Example

harness_01933b5a00007000800000000000001

initial_files

Starter files copied into each new session for this harness.

Array<object>

Starter file copied into a new session from an agent or harness.

object

content

required

File content: plain text or base64-encoded binary.

string

encoding

Content encoding: text or base64.

string

is_readonly

Prevent session-side edits or deletes when true.

boolean

path

required

Absolute path within the session workspace. /workspace prefix is accepted.

string

is_built_in

Whether this harness is built-in (system-managed, readonly). Built-in harnesses are provisioned during org initialization and cannot be modified or deleted via the API. Users can copy them.

boolean

name

required

URL/CLI-friendly addressable name, unique per org. Format: [a-z0-9]+(-[a-z0-9]+)*, max 64 chars. No consecutive hyphens.

string

network_access

One of:

null

null

object

Network access list controlling which hosts/URLs sessions can reach. Merged with agent and session layers (allowed: intersect, blocked: union).

object

allowed

Allowed host patterns. If non-empty, only matching URLs are permitted. An empty list means “no restriction from this layer” (inherit parent).

Array<string>

blocked

Blocked host patterns. Always denied, even if matched by allowed.

Array<string>

parent_harness_id

Optional parent harness that this harness inherits from.

string | null

Example

harness_01933b5a000070008000000000000602

status

required

Current lifecycle status of the harness.

string

Allowed values: active archived deleted

system_prompt

required

System prompt that defines the harness’s base behavior. Forms the foundation of the prompt stack.

string

tags

Tags for organizing and filtering harnesses.

Array<string>

updated_at

required

Timestamp when the harness was last updated.

string format: date-time

400

Invalid input

Standard error response for API endpoints.

object

error

required

Error message describing what went wrong.

string

403

Forbidden

Standard error response for API endpoints.

object

error

required

Error message describing what went wrong.

string

500

Internal server error

Standard error response for API endpoints.

object

error

required

Error message describing what went wrong.

string