# GET /v1/harnesses

Source: <https://everruns.com/docs/api/operations/list_harnesses/>

GET

/v1/harnesses

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/harnesses';
const options = {method: 'GET'};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
curl --request GET \
  --url https://app.everruns.com/api/v1/harnesses
```

* Production APIapp.everruns.com/api/v1/harnesses

## 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

Media typeapplication/json

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

Wrapper that adds API and UI links to a serialized resource.

Uses `self_url` (not `url`) for the API link to avoid collision with resources that already have a `url` field (e.g. McpServer). The `allowed_actions` array carries state-aware hypermedia links — empty (and omitted from the wire shape) until the underlying resource opts into the convention by overriding `ResourceUrlable::allowed_actions`.

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

**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**

Human-readable display name shown in UI.

string | null

**embedder\_metadata**

Arbitrary key-value metadata injected into LLM requests for observability. Keys from system context (session\_id, org\_id, etc.) always take precedence.

object

***key***

additional properties

string

**icon**

Display glyph name rendered by the UI (e.g. “message-circle”).

Built-in harnesses declare it in their definition; custom harnesses leave it unset and fall back to the UI’s generic harness glyph.

string | null

**id**

required

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

string

**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

**mcpServers**

Remote MCP servers scoped to this harness and inherited by descendant layers.

object

***key***

additional properties

Session-, agent-, or harness-scoped remote MCP server configuration.

This intentionally mirrors the `mcpServers` object shape used by common MCP client config files while staying within Everruns’ current remote-HTTP-only support.

object

**actsAs**

Identity whose grant this attachment requests.

string

Allowed values: none service user user\_or\_service

**args**

Arguments passed to the stdio `command`.

Array\<string>

**auth\_mode**

Authentication mode used when executing tools from this scoped server.

string

Allowed values: none api\_key oauth

**command**

Executable to spawn for a stdio transport server.

string | null

**connectInChat**

Whether a missing sign-in may pause the turn with an in-chat Connect card (`ask`, the default) or fails the call with a settings link (`never`).

string

Allowed values: ask never

**deferred**

Whether the server’s tools are listed only when the model asks for them through tool search (`false`, the default, lists them at turn start).

boolean

**elicitation\_policy**

Which elicitation modes this server may use (`url` by default).

string

Allowed values: url url\_and\_form none

**env**

Environment variables set for the stdio `command`.

object

***key***

additional properties

string

**headers**

Additional HTTP headers sent on MCP requests (HTTP transport only).

object

***key***

additional properties

string

**oauth\_provider\_id**

Provider id used to resolve a user-scoped bearer token.

string | null

**protocol\_mode**

Protocol-era adoption policy for the MCP client (`auto` negotiates).

string

Allowed values: auto 2025-03-26 2025-06-18 2026-07-28

**tool\_discovery**

Whether to discover tool definitions live from this server.

boolean

**tool\_labels**

Risk labels for this server’s tools, by the tool’s own name: `read_only` never asks for approval in the normal mode, `changes` always asks. They win over the tool’s annotations and over a catalog preset’s saved labels. Honored on harness, agent and person-owned servers; dropped from session-scoped servers.

object

***key***

additional properties

A person’s saved risk label for one MCP tool.

Decision (2026-10-10): a person’s label always wins over the tool’s own annotations, because a remote server describes itself and a person who owns the integration knows better. `read_only` also clears `open_world`, since tool approval treats an outward-reaching tool like a destructive one; without that a read-only MCP tool would still ask every time.

string

Allowed values: read\_only changes

**type**

MCP transport type. Only remote HTTP is supported today.

string

Allowed values: http stdio

**url**

URL of the remote MCP server endpoint. Required for HTTP transport; empty/ignored for stdio.

string

**use**

One of:

* string

  Organization catalog preset that supplies transport and authentication policy.

  string

* null

  null

**name**

required

Name, unique per org (e.g. “conversation”).

string

**network\_access**

One of:

* 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>

* null

  null

**parallel\_tool\_calls**

Request-level parallel tool calling preference (EVE-598).

`None` (default) preserves provider defaults. `Some(true)` signals the provider that parallel tool calls are wanted; `Some(false)` requests at most one tool call per turn and forces serial execution. Merged across harness/agent/session layers (overlay wins).

boolean | null

**parent\_harness\_id**

Optional parent harness that this harness inherits from.

string | null

**status**

required

Current lifecycle status of the harness.

string

Allowed values: active archived deleted

**system\_prompt**

System prompt that defines the harness’s base behavior.

Forms the foundation of the prompt stack. Optional: when absent the harness contributes no base prompt, so the effective prompt comes entirely from the parent harness (if any), the agent, the session, and capability contributions. Empty/whitespace-only values normalize to `None`.

string | null

**tags**

Tags for organizing and filtering harnesses.

Array\<string>

**updated\_at**

required

Timestamp when the harness was last updated.

string format: date-time

**app\_count**

required

Number of non-deleted apps using this resource.

integer format: int64

**session\_count**

required

Number of sessions using this resource.

integer format: int64

**allowed\_actions**

State-aware hypermedia actions the caller can take on this resource next (e.g. `cancel`, `events`, `update`). Omitted from the wire shape when empty so resources that haven’t opted into the convention don’t grow their payloads.

Array\<object>

Agent-actionable link describing a follow-up the caller can take. Used in two contexts:

* **Error recovery** — `ErrorResponse.allowed_actions` carries `rel`s like `retry`, `retry-later`, `unarchive`, `get-existing` so the agent knows the right next call after a 4xx/429.
* **Entity hypermedia** — `WithUrls<T>.allowed_actions` carries state-aware `rel`s like `cancel`, `events`, `self`, `update` on the entity itself so the agent can follow links instead of reconstructing routes from prose.

The shape is intentionally identical across both contexts; the closed `rel` vocabulary distinguishes them.

object

**hint**

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”, “Cancel the active turn for this session.”).

string | null

**href**

Absolute (preferred) or relative URL the caller may invoke directly. **Always present on entity hypermedia actions** (`WithUrls<T>.allowed_actions`); **optional on error-recovery actions** (`ErrorResponse.allowed_actions`) where the matching `operation_id` is enough and the URI is implicit from the failed call.

string | null

**method**

HTTP method to use against `href`. Required for entity hypermedia actions; usually omitted on error-recovery actions where the same operation is retried with its original method.

string | null

**operation\_id**

OpenAPI `operationId` the caller should invoke. Lets an MCP client resolve the call without parsing `href`.

string | null

**rel**

required

Link relation describing the action. Examples: `self`, `cancel`, `pause`, `resume`, `events`, `retry`, `retry-later`, `unarchive`, `get-existing`, `delete`, `update`.

string

**schema\_ref**

OpenAPI `$ref` to the request-body schema, when the action takes one (e.g. `#/components/schemas/UpdateSessionRequest`). Lets a tool-calling agent fetch the input shape without scanning the whole spec.

string | null

**self\_url**

required

Full API endpoint URL for this resource.

string

**ui\_link**

required

Alias for `view_url`, used by command and MCP outputs.

string

**view\_url**

required

Full UI URL for viewing this resource.

string

##### Example

```json
{
  "data": [
    {
      "archived_at": "2026-05-26T00:00:00Z",
      "created_at": "2026-04-01T10:00:00Z",
      "default_model_id": "model_01933b5a00007000800000000000001",
      "deleted_at": "2026-05-26T00:00:00Z",
      "description": "Default harness with file-system + secrets capabilities; safe baseline for new agents.",
      "display_name": "Conversation",
      "embedder_metadata": {
        "env": "production",
        "team": "platform"
      },
      "icon": "message-circle",
      "id": "harness_01933b5a00007000800000000000001",
      "is_built_in": false,
      "mcpServers": {
        "additionalProperty": {
          "actsAs": "none",
          "auth_mode": "none",
          "connectInChat": "ask",
          "elicitation_policy": "url",
          "protocol_mode": "auto",
          "tool_labels": {
            "additionalProperty": "read_only"
          },
          "type": "http",
          "use": "catalog:linear"
        }
      },
      "name": "conversation",
      "network_access": {
        "allowed": [
          "*.example.com",
          "https://api.acme.com/"
        ],
        "blocked": [
          "169.254.169.254"
        ]
      },
      "parallel_tool_calls": true,
      "parent_harness_id": "harness_01933b5a000070008000000000000602",
      "status": "active",
      "system_prompt": "You are an Everruns agent. Be concise, cite sources when possible, and decline tasks outside your assigned scope.",
      "tags": [
        "baseline",
        "production"
      ],
      "updated_at": "2026-05-20T14:00:00Z",
      "allowed_actions": [
        {
          "method": "POST"
        }
      ]
    }
  ]
}
```

### 403

Forbidden

### 500

Internal server error