Skip to content
Everruns Everruns

POST /v1/harnesses/preview

POST
/v1/harnesses/preview
 
curl --request POST \
  --url https://app.everruns.com/api/v1/harnesses/preview \
  --header 'Content-Type: application/json' \
  --data '{ "capabilities": [ { "config": {}, "ref": "web.search" }, { "config": { "root": "/workspace" }, "ref": "filesystem.read" } ], "mcpServers": { "additionalProperty": { "auth_mode": "none", "headers": { "additionalProperty": "example" }, "oauth_provider_id": "example", "tool_discovery": true, "type": "http", "url": "example" } }, "parent_harness_id": "harness_01933b5a000070008000000000000602", "system_prompt": "You are a research assistant." }'

Request Body required

Section titled “Request Body required ”
Media type application/json

Request to preview harness shape with capabilities applied

object
capabilities

Capability configurations to layer onto the preview. Empty list means none.

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": "web.search"
  },
  {
    "config": {
      "root": "/workspace"
    },
    "ref": "filesystem.read"
  }
]
mcpServers

MCP servers scoped to this preview, keyed by scope (shared / per-agent / etc.). Use the camelCase key mcpServers (preferred) or the snake_case alias mcp_servers. Empty by default.

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
Example 
api_key
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
Example 
http
url
required

URL of the remote MCP server endpoint.

string
parent_harness_id

Parent harness to extend. When set, its prompt, capabilities, and MCP servers are merged with the fields in this request before rendering.

string | null
Example 
harness_01933b5a000070008000000000000602
system_prompt
required

System prompt to render as the base prompt for the preview.

string
Example 
You are a research assistant.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Harness preview generated

Media type application/json

Preview response showing merged prompt and tools

object
system_prompt
required
string
tools
required
Array<object>
object
Example generated
{
  "system_prompt": "example",
  "tools": [
    {}
  ]
}

500

Section titled “500 ”

Internal server error

Media type application/json

Standard error response.

Wire shape is RFC 9457 Problem Details: every error response includes title and status, and may include detail, code, allowed_actions, retry_after_seconds, instance, and type. The content type is rewritten to application/problem+json by [problem_json_content_type].

object
allowed_actions

Recovery actions the caller can take next.

Array<object>

Agent-actionable recovery hint attached to an error response.

object
hint

Short, agent-readable hint (e.g. “Shorten ‘name’ to <= 200 chars.”).

string | null
href

Optional absolute or relative URL the caller may invoke directly.

string | null
operation_id

OpenAPI operationId the caller should invoke to recover.

string | null
rel
required

Link relation describing the action (e.g. retry, get-existing, unarchive, retry-later).

string
code

Stable, machine-readable error code (snake_case).

string | null
detail

Human-readable explanation specific to this occurrence.

string | null
instance

Request URI for this occurrence.

string | null
retry_after_seconds

Seconds the caller should wait before retrying (429 / transient 503).

integer | null format: int32
status
required

HTTP status code; mirrors the response status line.

integer format: int32
title
required

Short, human-readable summary of the problem (e.g. “Not Found”).

string
type

RFC 9457 problem type URI. Optional; identifies the problem class.

string | null
Example generated
{
  "allowed_actions": [
    {
      "hint": "example",
      "href": "example",
      "operation_id": "example",
      "rel": "example"
    }
  ],
  "code": "example",
  "detail": "example",
  "instance": "example",
  "retry_after_seconds": 1,
  "status": 1,
  "title": "example",
  "type": "example"
}