# POST /v1/agents/preview - Preview the final agent shape with capabilities applied

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

POST

/v1/agents/preview

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/agents/preview';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"capabilities":[{"config":{},"ref":"current_time"},{"config":{},"ref":"test_math"}],"harness_id":"harness_01933b5a000070008000000000000001","initial_files":[{"content":"example","encoding":"example","is_readonly":true,"path":"example"}],"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,"tool_labels":{"additionalProperty":"read_only"},"type":"http","url":"example","use":"catalog:linear"}},"system_prompt":"You are a helpful customer support agent.","tools":[{}]}'
};


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

```sh
curl --request POST \
  --url https://app.everruns.com/api/v1/agents/preview \
  --header 'Content-Type: application/json' \
  --data '{ "capabilities": [ { "config": {}, "ref": "current_time" }, { "config": {}, "ref": "test_math" } ], "harness_id": "harness_01933b5a000070008000000000000001", "initial_files": [ { "content": "example", "encoding": "example", "is_readonly": true, "path": "example" } ], "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, "tool_labels": { "additionalProperty": "read_only" }, "type": "http", "url": "example", "use": "catalog:linear" } }, "system_prompt": "You are a helpful customer support agent.", "tools": [ {} ] }'
```

* Production APIapp.everruns.com/api/v1/agents/preview

Returns the merged system prompt and all tools that would be available to the agent. This is useful for previewing what the agent will look like before saving.

## Request Bodyrequired

Media typeapplication/json

Request to preview the final agent shape with capabilities applied

object

**capabilities**

Capabilities to apply with per-agent 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

##### Example

```json
[
  {
    "config": {},
    "ref": "current_time"
  },
  {
    "config": {},
    "ref": "test_math"
  }
]
```

**harness\_id**

One of:

* string

  Harness to layer beneath this draft. Omit to preview the agent layer alone.

  string

  /^harness\_\[0-9a-f]{32}$/

  ##### Example

  ```plaintext
  harness_01933b5a000070008000000000000001
  ```

* null

  null

**initial\_files**

Draft starter files; agent paths override inherited harness files.

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

**mcpServers**

Remote MCP servers scoped to the previewed agent.

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

```plaintext
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

```plaintext
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

```plaintext
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

```plaintext
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

```plaintext
auto
```

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

##### Example

```plaintext
http
```

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

  ##### Example

  ```plaintext
  catalog:linear
  ```

* null

  null

**system\_prompt**

required

The base system prompt (before capability additions)

string

##### Example

```plaintext
You are a helpful customer support agent.
```

**tools**

Client-side tools to include in the preview.

Array\<object>

object

## Responses

### 200

Agent preview generated

Media typeapplication/json

Response showing the final agent shape after applying capabilities

object

**features**

required

Session features from effective capabilities and their dependencies.

Array\<string>

**findings**

required

Advisory findings from built-in checks

Array\<object>

A single advisory finding about an agent configuration.

object

**category**

required

string

Allowed values: structure completeness effectiveness safety cost

**fix**

Proposed replacement text (phase 2+; always absent for builtin rules).

string | null

**location**

One of:

* object

  Pointer to the config field (and optional byte span within it) a finding refers to.

  object

  **end**

  integer | null format: int32

  **field**

  required

  Config field name, e.g. `system_prompt`, `tools`.

  string

  **start**

  Byte offset range into the field’s authored text, when applicable.

  integer | null format: int32

* null

  null

**message**

required

Human-readable explanation. Safe to render in user-facing messages.

string

**rule\_id**

required

Stable rule identifier, e.g. `prompt.duplicate_paragraphs`.

string

**severity**

required

Advisory severity. There is deliberately no `error`: checks never gate save/publish.

string

Allowed values: warning info suggestion

**source**

required

Which tier produced the finding.

string

Allowed values: builtin llm health\_check

**initial\_files**

required

Effective starter files after merging the harness and agent.

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

**system\_prompt**

required

The full system prompt with capability additions prepended

string

**tools**

required

All tool definitions from capabilities

Array\<object>

object

##### Example

```json
{
  "findings": [
    {
      "category": "structure",
      "severity": "warning",
      "source": "builtin"
    }
  ]
}
```

### 403

Harness view permission required

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): 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 `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

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

```json
{
  "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://everruns.com/docs/errors/session_not_found"
}
```

### 404

Harness not found

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): 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 `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

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

```json
{
  "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://everruns.com/docs/errors/session_not_found"
}
```

### 500

Internal server error

Media typeapplication/json

Standard error response.

Wire shape is [RFC 9457 Problem Details](https://www.rfc-editor.org/rfc/rfc9457): 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 `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

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

```json
{
  "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://everruns.com/docs/errors/session_not_found"
}
```