Skip to content
EverrunsEverruns
Everruns Cloud is open in early access. Run agents without operating the platform.

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": { "actsAs": "none", "args": [ "example" ], "auth_mode": "none", "command": "example", "connectInChat": "ask", "deferred": true, "elicitation_policy": "url", "env": { "additionalProperty": "example" }, "headers": { "additionalProperty": "example" }, "oauth_provider_id": "example", "protocol_mode": "auto", "tool_discovery": true, "type": "http", "url": "example", "use": "catalog:linear" } }, "parent_harness_id": "harness_01933b5a000070008000000000000602", "system_prompt": "You are a research assistant." }'

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/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
actsAs

Identity whose grant this attachment requests.

string
Allowed values: none service user user_or_service
Example
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
Example
api_key
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
Example
ask
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
Example
url
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
Example
auto
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 stdio
Example
http
url

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

string
use
One of:

Organization catalog preset that supplies transport and authentication policy.

string
Example
catalog:linear
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

System prompt to render as the base prompt for the preview. Optional: omit to preview a harness that contributes no base prompt of its own.

string | null
Example
You are a research assistant.

Responses

Section titled “ Responses ”

200

Section titled “200”

Harness preview generated

Media typeapplication/json

Preview response showing merged prompt and tools

object
features
required

Session features from effective capabilities and their dependencies.

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

500

Section titled “500”

Internal server error

Media typeapplication/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 with the application/problem+json content type.

object
allowed_actions

Recovery actions the caller can take next.

Array<object>

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

  • Error recovery — ErrorResponse.allowed_actions carries rels 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 rels 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
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
{
  "allowed_actions": [
    {
      "method": "POST"
    }
  ],
  "code": "session_not_found",
  "detail": "Session session_01933b5a000070008000000000000001 not found in org org_01933b5a000070008000000000000001.",
  "instance": "/v1/sessions/session_01933b5a000070008000000000000001",
  "retry_after_seconds": 30,
  "status": 404,
  "title": "Session not found",
  "type": "https://docs.everruns.com/errors/session_not_found"
}