# GET /v1/capabilities - List available capabilities with pagination

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

GET

/v1/capabilities

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/capabilities';
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/capabilities
```

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

## Parameters

### Query Parameters

**search**

string

Search by name/description

**offset**

integer format: int32

Pagination offset (default: 0)

**limit**

integer format: int32

Page size (default: 20, max: 100)

**include\_retired**

boolean

Include retired capabilities (default: false)

## Responses

### 200

Paginated list of capabilities

Media typeapplication/json

Response wrapper for paginated list endpoints. Includes pagination metadata along with the data array.

`next_url` and `prev_url` are populated by the \[`decorate_pagination_links`] middleware after the handler returns, so handlers don’t need to thread the request URL into every construction site.

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

**agent\_count**

Number of active agents referencing this capability in the org.

integer format: int64

**category**

Category for grouping in UI

string | null

**config\_schema**

JSON Schema for capability-specific per-agent config.

object

**config\_ui\_schema**

React-jsonschema-form uiSchema hints for rendering config\_schema.

object

**dependencies**

IDs of capabilities that this capability depends on. When this capability is selected, its dependencies are automatically included.

Array\<string>

**description**

required

Description of what this capability provides

string

**docs\_slug**

Slug under the [capability documentation](https://everruns.com/docs/capabilities/) when public docs exist.

string | null

**features**

UI feature strings this capability contributes to. Multiple capabilities can contribute the same feature.

Array\<string>

**harness\_count**

Number of active harnesses referencing this capability in the org.

integer format: int64

**icon**

Icon name (for UI rendering)

string | null

**id**

required

Unique capability identifier

string

**is\_guardrail**

Whether this capability is a guardrail (constrains agent behavior rather than granting abilities). Used for UI grouping and filtering.

boolean

**is\_mcp**

Whether this is an MCP server capability (for UI badge)

boolean

**is\_skill**

Whether this is an Agent Skill capability (for UI badge)

boolean

**localizations**

Localized display strings keyed by lowercase language tag (e.g. “uk”). The “en” entry carries only `config_description`, since the base name/description/config\_schema strings are already English.

object

***key***

additional properties

Localized display strings for one locale of a capability.

object

**config\_description**

One-line summary of what this capability’s config controls.

string | null

**config\_overlay**

Overlay merged into `config_schema` before rendering: mirrors the schema property tree with `title`/`description`/`enum_labels` leaves.

object

**description**

Localized description; absent means fall back to `description`.

string | null

**name**

Localized display name; absent means fall back to `name`.

string | null

**name**

required

Display name

string

**risk\_level**

TM-AGENT-005: Risk level. High-risk capabilities require admin approval.

string

Allowed values: low medium high

**status**

required

Current status

string

**system\_prompt**

System prompt addition contributed by this capability

string | null

**tool\_definitions**

Tool definitions provided by this capability

Array\<object>

object

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

**limit**

required

Maximum number of items per page.

integer format: int32

**next\_url**

Absolute URL for the next page, with `offset` advanced by `limit`. Omitted from the response (field absent) when this is the last page.

string | null

**offset**

required

Current offset (starting position).

integer format: int32

**prev\_url**

Absolute URL for the previous page, with `offset` rolled back by `limit`. Omitted from the response (field absent) when this is the first page.

string | null

**total**

required

Total number of items matching the query (across all pages).

integer format: int32

##### Example

```json
{
  "data": [
    {
      "agent_count": 42,
      "category": "filesystem",
      "dependencies": [
        "approval"
      ],
      "description": "Read, write, edit, list, grep, delete, and stat files in the session workspace.",
      "docs_slug": "session_file_system",
      "features": [
        "file_browser"
      ],
      "harness_count": 7,
      "icon": "Folder",
      "id": "session_file_system",
      "is_guardrail": false,
      "is_mcp": false,
      "is_skill": false,
      "localizations": {
        "uk": {
          "description": "Монтує спільні файли пам'яті в сесії.",
          "name": "Пам'ять"
        }
      },
      "name": "Session File System",
      "risk_level": "low",
      "status": "active",
      "system_prompt": "You can read and write files in /workspace via the session_file_system tools.",
      "tool_definitions": [
        {
          "description": "Read a file from the session workspace.",
          "name": "read_file"
        },
        {
          "description": "Write or overwrite a file in the session workspace.",
          "name": "write_file"
        }
      ],
      "allowed_actions": [
        {
          "method": "POST"
        }
      ]
    }
  ]
}
```

### 400

Invalid query parameters

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"
}
```