GET /v1/harnesses/{harness_id}

GET

/v1/harnesses/{harness_id}

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

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

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

Accepts either a harness ID (e.g. harness_01933b5a...) or a name (e.g. generic). The virtual name default resolves to the org’s configured default harness. Names are resolved within the caller’s org.

Parameters

Path Parameters

harness_id

required

string

Harness ID (prefixed) or name

Responses

200

Harness found

application/json

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).

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

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

auth_mode

Authentication mode used when executing tools from this scoped server.

string

Allowed values: none api_key o_auth

headers

Additional HTTP headers sent on MCP requests.

object

key

additional properties

string

oauth_provider_id

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

string | null

tool_discovery

Whether to discover tool definitions live from this server.

boolean

type

MCP transport type. Only remote HTTP is supported today.

string

Allowed values: http

url

required

URL of the remote MCP server endpoint.

string

name

required

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

string

network_access

One of:

null
object

null

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

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

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

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

{
  "default_model_id": "model_01933b5a00007000800000000000001",
  "id": "harness_01933b5a00007000800000000000001",
  "mcpServers": {
    "additionalProperty": {
      "auth_mode": "none",
      "type": "http"
    }
  },
  "network_access": {
    "allowed": [
      "*.example.com",
      "https://api.acme.com/"
    ],
    "blocked": [
      "169.254.169.254"
    ]
  },
  "parent_harness_id": "harness_01933b5a000070008000000000000602",
  "status": "active"
}

403

Forbidden

404

Harness not found

500

Internal server error