GET /v1/harnesses

GET

/v1/harnesses

• Production API

Parameters

Query Parameters

search

string | null

Search by name or description (case-insensitive substring match).

include_archived

boolean | null

Include archived harnesses. Deleted harnesses never appear in lists.

Responses

200

List of harnesses

Response wrapper for list endpoints. All list endpoints return responses wrapped in a data field.

object

data

required

Array of items returned by the list operation.

Array<object>

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

403

Forbidden

500

Internal server error