> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/technical-reference/apis-and-mcp/rest-endpoint-reference.md).

# REST Endpoint Reference

Use the public REST endpoint catalog to find the operation for your task. Each entry identifies the request method, route, required inputs, and documented responses.

![Read the input contract before starting a run](https://1957915746-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSQ1Sgy933krTyK0S4JpP%2Fuploads%2FBj6tDNApdjPJzI364hXJ%2Frest-endpoint-reference.png?alt=media)

Set PROJECT\_VERSION to the saved version you intend to run. The endpoint reference defines each operation’s method, inputs, and responses; do not transfer parameters between endpoints.

<details>

<summary>Copy the example</summary>

```bash
curl --get \
  "$STACKAI_BASE_URL/v2/projects/$PROJECT_ID/io-schema" \
  --data-urlencode "version=$PROJECT_VERSION" \
  -H "Authorization: Bearer $STACKAI_API_KEY"

# Match input keys and types to the returned schema.
# Use the same saved version for the run request.
```

</details>

## Before you begin

A credential accepted by the selected endpoint and the required resource permissions.

## API reference terminology

| Term            | Definition                                                                                                                                                  |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| API version     | The request and response contract selected by an API route. It is separate from the saved workflow version you ask the API to run.                          |
| Request body    | The payload transmitted with an HTTP request. Interpret it using the content type expected by the endpoint.                                                 |
| Header          | A named value sent as HTTP request or response metadata. Authentication and signatures belong in the headers specified by the contract.                     |
| Query parameter | A named value carried in a URL’s query string. It is distinct from a similarly named body field; avoid putting secrets there.                               |
| HTTP status     | The numeric outcome returned for an HTTP request. Read the response body too; accepted work can still be running.                                           |
| Schema          | A definition of fields, types, required values, and supported constraints. Use it to validate the shape of data; it does not establish factual correctness. |

## Find a REST operation

1. Find the operation by resource and purpose.
2. Use its request schema and authentication contract.
3. Handle the documented response and any asynchronous follow-up before using the result.

Your client uses a documented public operation.

## Behavior and limitations

Route versions can coexist and differ in payloads, version selection, and error handling. Optional fields and detailed constraints remain part of the endpoint schema. Use only the routes listed in the public API contract.

## Public operations

Use the request and response fields below with the selected route. For authentication and version-selection rules, see the related references.

### GET `/inference/v0/runs/{org_id}/{run_id}`

Get Run

| Parameter | Location                                              | Required | Type   |
| --------- | ----------------------------------------------------- | -------- | ------ |
| `org_id`  | path                                                  | Yes      | string |
| `run_id`  | path                                                  | Yes      | string |
| Status    | Response                                              |          |        |
| ---       | ---                                                   |          |        |
| `200`     | Successful Response                                   |          |        |
| `404`     | Run not found or does not belong to this organization |          |        |
| `422`     | Validation Error                                      |          |        |

**Required scope:** `projects.read`. Resource permissions also apply.

### POST `/inference/v0/runs/{org_id}/{run_id}/resume`

Resume Run

| Parameter        | Location | Required | Type                          |
| ---------------- | -------- | -------- | ----------------------------- |
| `org_id`         | path     | Yes      | string                        |
| `run_id`         | path     | Yes      | string                        |
| `verbose`        | query    | No       | boolean                       |
| `execution_mode` | query    | No       | `in-memory`, `remote` or null |

**Request body:** `application/json`.

| Field           | Required                                                                                                                                                                                                                                                                                                                                                                                                                       | Type                                 |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |
| `resume_token`  | Yes                                                                                                                                                                                                                                                                                                                                                                                                                            | string                               |
| `response`      | Yes                                                                                                                                                                                                                                                                                                                                                                                                                            | string                               |
| `response_type` | No                                                                                                                                                                                                                                                                                                                                                                                                                             | `text`, `approval`, `choice` or null |
| Status          | Response                                                                                                                                                                                                                                                                                                                                                                                                                       |                                      |
| ---             | ---                                                                                                                                                                                                                                                                                                                                                                                                                            |                                      |
| `200`           | Returns the run-result envelope (same shape as a normal run): in-memory runs resume synchronously with a terminal state + outputs; out-of-band (Temporal/trigger) runs return state=RESUMED with empty outputs, and the client polls GET /runs/{org\_id}/{run\_id} for completion. With Accept: text/event-stream the continuation streams back as SSE for in-process and live Temporal runs (trigger-backed runs return 406). |                                      |
| `202`           | Returned with execution\_mode=remote and no Accept: text/event-stream on a durable run: the continuation runs in the background; the body carries the run\_id and a WebSocket handle. Watch the room or poll GET /runs/{org\_id}/{run\_id} for completion.                                                                                                                                                                     |                                      |
| `401`           | Invalid or expired resume token                                                                                                                                                                                                                                                                                                                                                                                                |                                      |
| `403`           | Run is paused on a step not resumable via the public API (only ask-human pauses are supported).                                                                                                                                                                                                                                                                                                                                |                                      |
| `404`           | Run not found or does not belong to this organization                                                                                                                                                                                                                                                                                                                                                                          |                                      |
| `406`           | Accept: text/event-stream was sent for a trigger-backed run, which has no event stream to relay. Retry without the Accept header and poll GET /runs/{org\_id}/{run\_id}, or pass execution\_mode=remote for a 202 + WebSocket handle.                                                                                                                                                                                          |                                      |
| `409`           | Run is not paused/resumable, or execution\_mode=remote was sent for an in-process run that can only resume inline.                                                                                                                                                                                                                                                                                                             |                                      |
| `422`           | Validation Error                                                                                                                                                                                                                                                                                                                                                                                                               |                                      |

**Required scope:** `projects.run`. Resource permissions also apply.

### POST `/inference/v0/run/{org_id}/{flow_id}`

Run Deployed Flow

| Parameter        | Location | Required | Type                          |
| ---------------- | -------- | -------- | ----------------------------- |
| `org_id`         | path     | Yes      | string                        |
| `flow_id`        | path     | Yes      | string                        |
| `version`        | query    | No       | integer                       |
| `verbose`        | query    | No       | boolean                       |
| `delta`          | query    | No       | boolean                       |
| `prefix`         | query    | No       | boolean                       |
| `execution_mode` | query    | No       | `in-memory`, `remote` or null |

**Request body:** `application/json`.

Body type: object.

| Status | Response                                                                                                                                                                                                                                                                           |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | The run-result envelope (same InferenceResponse shape as resume): a terminal state + outputs, or state=PAUSED with the pause payload when the run pauses on a human-in-the-loop step. With Accept: text/event-stream the run streams back as SSE InferenceResponse frames instead. |
| `202`  | Returned with execution\_mode=remote and no Accept: text/event-stream: the run executes durably in the background; the body carries the run\_id and a WebSocket handle to stream updates. Poll GET /runs/{org\_id}/{run\_id} for the terminal state.                               |
| `403`  | Project is not published                                                                                                                                                                                                                                                           |
| `422`  | Validation Error                                                                                                                                                                                                                                                                   |

**Required scope:** `projects.run`. Resource permissions also apply.

### GET `/v1/knowledge-bases/{knowledge_base_id}/resources`

List Resources

| Parameter           | Location            | Required | Type           |
| ------------------- | ------------------- | -------- | -------------- |
| `knowledge_base_id` | path                | Yes      | string         |
| `cursor`            | query               | No       | string or null |
| `page_size`         | query               | No       | integer        |
| `direction`         | query               | No       | `next`, `prev` |
| Status              | Response            |          |                |
| ---                 | ---                 |          |                |
| `200`               | Successful Response |          |                |
| `422`               | Validation Error    |          |                |

### POST `/v1/knowledge-bases/{knowledge_base_id}/resources`

Create Resource

| Parameter           | Location | Required | Type   |
| ------------------- | -------- | -------- | ------ |
| `knowledge_base_id` | path     | Yes      | string |

**Request body:** `multipart/form-data`.

| Field  | Required            | Type   |
| ------ | ------------------- | ------ |
| `file` | Yes                 | string |
| Status | Response            |        |
| ---    | ---                 |        |
| `202`  | Successful Response |        |
| `422`  | Validation Error    |        |

### GET `/v1/knowledge-bases/{knowledge_base_id}/resources/{resource_id}`

Get Resource By Id

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| `resource_id`       | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `200`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### DELETE `/v1/knowledge-bases/{knowledge_base_id}/resources/{resource_id}`

Delete Resource By Id

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| `resource_id`       | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `204`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### POST `/v1/knowledge-bases/{knowledge_base_id}/sync`

Synchronize Knowledge Base

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `202`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### GET `/v1/knowledge-bases`

Get Knowledge Bases

| Parameter   | Location            | Required | Type           |
| ----------- | ------------------- | -------- | -------------- |
| `cursor`    | query               | No       | string or null |
| `page_size` | query               | No       | integer        |
| `direction` | query               | No       | `next`, `prev` |
| Status      | Response            |          |                |
| ---         | ---                 |          |                |
| `200`       | Successful Response |          |                |
| `422`       | Validation Error    |          |                |

### POST `/v1/knowledge-bases`

Create Knowledge Base

**Request body:** `application/json`.

| Field                               | Required            | Type                                |
| ----------------------------------- | ------------------- | ----------------------------------- |
| `connection_id`                     | No                  | string or null                      |
| `connection_source_ids`             | No                  | array of string                     |
| `website_sources`                   | No                  | array of object                     |
| `source_file_authorization_enabled` | No                  | boolean                             |
| `name`                              | No                  | string                              |
| `description`                       | No                  | string                              |
| `indexing_params`                   | No                  | object                              |
| `org_level_role`                    | No                  | `viewer`, `editor`, `admin` or null |
| Status                              | Response            |                                     |
| ---                                 | ---                 |                                     |
| `201`                               | Successful Response |                                     |
| `422`                               | Validation Error    |                                     |

### GET `/v1/knowledge-bases/{knowledge_base_id}`

Get Knowledge Base By Id

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `200`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### PATCH `/v1/knowledge-bases/{knowledge_base_id}`

Update Knowledge Base

| Parameter           | Location | Required | Type   |
| ------------------- | -------- | -------- | ------ |
| `knowledge_base_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field                               | Required            | Type                                |
| ----------------------------------- | ------------------- | ----------------------------------- |
| `connection_id`                     | No                  | string or null                      |
| `connection_source_ids`             | No                  | array of string                     |
| `website_sources`                   | No                  | array of object                     |
| `source_file_authorization_enabled` | No                  | boolean                             |
| `name`                              | No                  | string                              |
| `description`                       | No                  | string                              |
| `indexing_params`                   | No                  | object or null                      |
| `org_level_role`                    | No                  | `viewer`, `editor`, `admin` or null |
| Status                              | Response            |                                     |
| ---                                 | ---                 |                                     |
| `200`                               | Successful Response |                                     |
| `422`                               | Validation Error    |                                     |

### DELETE `/v1/knowledge-bases/{knowledge_base_id}`

Delete Knowledge Base

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `204`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### GET `/v2/knowledge-bases`

List Knowledge Bases

| Parameter   | Location            | Required | Type           |
| ----------- | ------------------- | -------- | -------------- |
| `cursor`    | query               | No       | string or null |
| `page_size` | query               | No       | integer        |
| `direction` | query               | No       | `next`, `prev` |
| Status      | Response            |          |                |
| ---         | ---                 |          |                |
| `200`       | Successful Response |          |                |
| `422`       | Validation Error    |          |                |

### POST `/v2/knowledge-bases`

Create Knowledge Base

**Request body:** `application/json`.

| Field                               | Required            | Type                                |
| ----------------------------------- | ------------------- | ----------------------------------- |
| `connection_id`                     | No                  | string or null                      |
| `connection_source_ids`             | No                  | array of string                     |
| `website_sources`                   | No                  | array of object                     |
| `source_file_authorization_enabled` | No                  | boolean                             |
| `name`                              | No                  | string                              |
| `description`                       | No                  | string                              |
| `indexing_params`                   | No                  | object                              |
| `org_level_role`                    | No                  | `viewer`, `editor`, `admin` or null |
| Status                              | Response            |                                     |
| ---                                 | ---                 |                                     |
| `201`                               | Successful Response |                                     |
| `422`                               | Validation Error    |                                     |

### GET `/v2/knowledge-bases/{knowledge_base_id}`

Get Knowledge Base

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `200`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### PATCH `/v2/knowledge-bases/{knowledge_base_id}`

Update Knowledge Base

| Parameter           | Location | Required | Type   |
| ------------------- | -------- | -------- | ------ |
| `knowledge_base_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field                               | Required            | Type                                |
| ----------------------------------- | ------------------- | ----------------------------------- |
| `connection_id`                     | No                  | string or null                      |
| `connection_source_ids`             | No                  | array of string                     |
| `website_sources`                   | No                  | array of object                     |
| `source_file_authorization_enabled` | No                  | boolean                             |
| `name`                              | No                  | string                              |
| `description`                       | No                  | string                              |
| `indexing_params`                   | No                  | object or null                      |
| `org_level_role`                    | No                  | `viewer`, `editor`, `admin` or null |
| Status                              | Response            |                                     |
| ---                                 | ---                 |                                     |
| `200`                               | Successful Response |                                     |
| `422`                               | Validation Error    |                                     |

### DELETE `/v2/knowledge-bases/{knowledge_base_id}`

Delete Knowledge Base

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `204`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### GET `/v2/knowledge-bases/{knowledge_base_id}/metadata-schemas`

Get Knowledge Base Metadata Schemas

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `200`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### GET `/v2/knowledge-bases/{knowledge_base_id}/resources`

List Resources

| Parameter           | Location            | Required | Type           |
| ------------------- | ------------------- | -------- | -------------- |
| `knowledge_base_id` | path                | Yes      | string         |
| `cursor`            | query               | No       | string or null |
| `page_size`         | query               | No       | integer        |
| `direction`         | query               | No       | `next`, `prev` |
| Status              | Response            |          |                |
| ---                 | ---                 |          |                |
| `200`               | Successful Response |          |                |
| `422`               | Validation Error    |          |                |

### POST `/v2/knowledge-bases/{knowledge_base_id}/resources`

Upload Resource

| Parameter           | Location | Required | Type   |
| ------------------- | -------- | -------- | ------ |
| `knowledge_base_id` | path     | Yes      | string |

**Request body:** `multipart/form-data`.

| Field  | Required            | Type   |
| ------ | ------------------- | ------ |
| `file` | Yes                 | string |
| Status | Response            |        |
| ---    | ---                 |        |
| `202`  | Successful Response |        |
| `422`  | Validation Error    |        |

### GET `/v2/knowledge-bases/{knowledge_base_id}/resources/{resource_id}`

Get Resource By Id

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| `resource_id`       | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `200`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### DELETE `/v2/knowledge-bases/{knowledge_base_id}/resources/{resource_id}`

Delete Resource By Id

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| `resource_id`       | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `204`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### GET `/v2/knowledge-bases/{knowledge_base_id}/resources/{resource_id}/download`

Get Resource Download Url

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| `resource_id`       | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `200`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### POST `/v2/knowledge-bases/{knowledge_base_id}/query`

Query Knowledge Base

| Parameter           | Location | Required | Type   |
| ------------------- | -------- | -------- | ------ |
| `knowledge_base_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field            | Required            | Type                            |
| ---------------- | ------------------- | ------------------------------- |
| `query`          | Yes                 | string                          |
| `top_k`          | No                  | integer                         |
| `strategy`       | No                  | `semantic`, `keyword`, `hybrid` |
| `retrieval_type` | No                  | `docs`, `pages`, `chunks`       |
| Status           | Response            |                                 |
| ---              | ---                 |                                 |
| `200`            | Successful Response |                                 |
| `422`            | Validation Error    |                                 |

### POST `/v2/knowledge-bases/{knowledge_base_id}/sync`

Synchronize Knowledge Base

| Parameter           | Location            | Required | Type   |
| ------------------- | ------------------- | -------- | ------ |
| `knowledge_base_id` | path                | Yes      | string |
| Status              | Response            |          |        |
| ---                 | ---                 |          |        |
| `202`               | Successful Response |          |        |
| `422`               | Validation Error    |          |        |

### GET `/v2/projects/{project_id}/io-schema`

Get Project Io Schema

| Parameter    | Location                                                                          | Required | Type                        |
| ------------ | --------------------------------------------------------------------------------- | -------- | --------------------------- |
| `project_id` | path                                                                              | Yes      | string                      |
| `version`    | query                                                                             | No       | string or string or integer |
| Status       | Response                                                                          |          |                             |
| ---          | ---                                                                               |          |                             |
| `200`        | Successful Response                                                               |          |                             |
| `4XX`        | Other client errors use the same public error envelope                            |          |                             |
| `400`        | Invalid request parameters                                                        |          |                             |
| `401`        | Missing or invalid credentials                                                    |          |                             |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |                             |
| `404`        | Project or saved version not found in the caller's organization                   |          |                             |

**Required scope:** `projects.read`. Resource permissions also apply.

### GET `/v2/evals/datasets`

List Eval Datasets

| Parameter               | Location                                                                               | Required | Type                                       |
| ----------------------- | -------------------------------------------------------------------------------------- | -------- | ------------------------------------------ |
| `project_id`            | query                                                                                  | Yes      | string                                     |
| `search`                | query                                                                                  | No       | string or null                             |
| `offset`                | query                                                                                  | No       | integer                                    |
| `limit`                 | query                                                                                  | No       | integer                                    |
| `feeds_input_kind`      | query                                                                                  | No       | `start_node`, `legacy_input_nodes` or null |
| `feeds_input_keys`      | query                                                                                  | No       | array of string or null                    |
| `feeds_output_node_ids` | query                                                                                  | No       | array of string or null                    |
| Status                  | Response                                                                               |          |                                            |
| ---                     | ---                                                                                    |          |                                            |
| `200`                   | Successful Response                                                                    |          |                                            |
| `4XX`                   | Client error returned in the public API envelope                                       |          |                                            |
| `400`                   | Invalid request or pagination cursor                                                   |          |                                            |
| `401`                   | Missing or invalid credentials                                                         |          |                                            |
| `403`                   | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |          |                                            |
| `404`                   | Resource not found in the caller's organization                                        |          |                                            |
| `422`                   | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |          |                                            |

**Required scope:** `evals.read`. Resource permissions also apply.

### POST `/v2/evals/datasets`

Create Eval Dataset

**Request body:** `application/json`.

| Field           | Required                                                                               | Type           |
| --------------- | -------------------------------------------------------------------------------------- | -------------- |
| `project_id`    | Yes                                                                                    | string         |
| `name`          | Yes                                                                                    | string         |
| `description`   | No                                                                                     | string or null |
| `node_contract` | Yes                                                                                    | object         |
| Status          | Response                                                                               |                |
| ---             | ---                                                                                    |                |
| `201`           | Successful Response                                                                    |                |
| `4XX`           | Client error returned in the public API envelope                                       |                |
| `400`           | Invalid request or pagination cursor                                                   |                |
| `401`           | Missing or invalid credentials                                                         |                |
| `403`           | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                |
| `404`           | Resource not found in the caller's organization                                        |                |
| `422`           | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                |
| `409`           | Name conflict, concurrent operation, or dataset state prevents the operation           |                |

**Required scope:** `evals.create`. Resource permissions also apply.

### GET `/v2/evals/datasets/{dataset_id}`

Get Eval Dataset

| Parameter    | Location                                                                          | Required | Type   |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------ |
| `dataset_id` | path                                                                              | Yes      | string |
| Status       | Response                                                                          |          |        |
| ---          | ---                                                                               |          |        |
| `200`        | Successful Response                                                               |          |        |
| `4XX`        | Client error returned in the public API envelope                                  |          |        |
| `400`        | Invalid request or pagination cursor                                              |          |        |
| `401`        | Missing or invalid credentials                                                    |          |        |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`        | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### PATCH `/v2/evals/datasets/{dataset_id}`

Update Eval Dataset

| Parameter    | Location | Required | Type   |
| ------------ | -------- | -------- | ------ |
| `dataset_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field           | Required                                                                               | Type           |
| --------------- | -------------------------------------------------------------------------------------- | -------------- |
| `name`          | No                                                                                     | string or null |
| `description`   | No                                                                                     | string or null |
| `node_contract` | No                                                                                     | object or null |
| Status          | Response                                                                               |                |
| ---             | ---                                                                                    |                |
| `200`           | Successful Response                                                                    |                |
| `4XX`           | Client error returned in the public API envelope                                       |                |
| `400`           | Invalid request or pagination cursor                                                   |                |
| `401`           | Missing or invalid credentials                                                         |                |
| `403`           | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                |
| `404`           | Resource not found in the caller's organization                                        |                |
| `422`           | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                |
| `409`           | Name conflict, concurrent operation, or dataset state prevents the operation           |                |

**Required scope:** `evals.update`. Resource permissions also apply.

### DELETE `/v2/evals/datasets/{dataset_id}`

Delete Eval Dataset

| Parameter    | Location                                                                          | Required | Type   |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------ |
| `dataset_id` | path                                                                              | Yes      | string |
| Status       | Response                                                                          |          |        |
| ---          | ---                                                                               |          |        |
| `204`        | Successful Response                                                               |          |        |
| `4XX`        | Client error returned in the public API envelope                                  |          |        |
| `400`        | Invalid request or pagination cursor                                              |          |        |
| `401`        | Missing or invalid credentials                                                    |          |        |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`        | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.delete`. Resource permissions also apply.

### POST `/v2/evals/datasets/{dataset_id}/rows`

Add Eval Dataset Rows

| Parameter    | Location | Required | Type   |
| ------------ | -------- | -------- | ------ |
| `dataset_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field  | Required                                                                               | Type            |
| ------ | -------------------------------------------------------------------------------------- | --------------- |
| `rows` | Yes                                                                                    | array of object |
| Status | Response                                                                               |                 |
| ---    | ---                                                                                    |                 |
| `201`  | Successful Response                                                                    |                 |
| `4XX`  | Client error returned in the public API envelope                                       |                 |
| `400`  | Invalid request or pagination cursor                                                   |                 |
| `401`  | Missing or invalid credentials                                                         |                 |
| `403`  | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                 |
| `404`  | Resource not found in the caller's organization                                        |                 |
| `422`  | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                 |
| `409`  | Name conflict, concurrent operation, or dataset state prevents the operation           |                 |

**Required scope:** `evals.update`. Resource permissions also apply.

### GET `/v2/evals/datasets/{dataset_id}/rows`

List Eval Dataset Rows

| Parameter    | Location                                                                          | Required | Type    |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------- |
| `dataset_id` | path                                                                              | Yes      | string  |
| `offset`     | query                                                                             | No       | integer |
| `limit`      | query                                                                             | No       | integer |
| Status       | Response                                                                          |          |         |
| ---          | ---                                                                               |          |         |
| `200`        | Successful Response                                                               |          |         |
| `4XX`        | Client error returned in the public API envelope                                  |          |         |
| `400`        | Invalid request or pagination cursor                                              |          |         |
| `401`        | Missing or invalid credentials                                                    |          |         |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |         |
| `404`        | Resource not found in the caller's organization                                   |          |         |

**Required scope:** `evals.read`. Resource permissions also apply.

### POST `/v2/evals/datasets/{dataset_id}/imports`

Import Eval Dataset Rows

| Parameter    | Location | Required | Type   |
| ------------ | -------- | -------- | ------ |
| `dataset_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field     | Required                                                                               | Type            |
| --------- | -------------------------------------------------------------------------------------- | --------------- |
| `run_ids` | Yes                                                                                    | array of string |
| Status    | Response                                                                               |                 |
| ---       | ---                                                                                    |                 |
| `201`     | Successful Response                                                                    |                 |
| `4XX`     | Client error returned in the public API envelope                                       |                 |
| `400`     | Invalid request or pagination cursor                                                   |                 |
| `401`     | Missing or invalid credentials                                                         |                 |
| `403`     | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                 |
| `404`     | Resource not found in the caller's organization                                        |                 |
| `422`     | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                 |
| `409`     | Name conflict, concurrent operation, or dataset state prevents the operation           |                 |

**Required scope:** `evals.update`. Resource permissions also apply.

### GET `/v2/evals/datasets/{dataset_id}/rows/{row_id}`

Get Eval Dataset Row

| Parameter    | Location                                                                          | Required | Type   |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------ |
| `dataset_id` | path                                                                              | Yes      | string |
| `row_id`     | path                                                                              | Yes      | string |
| Status       | Response                                                                          |          |        |
| ---          | ---                                                                               |          |        |
| `200`        | Successful Response                                                               |          |        |
| `4XX`        | Client error returned in the public API envelope                                  |          |        |
| `400`        | Invalid request or pagination cursor                                              |          |        |
| `401`        | Missing or invalid credentials                                                    |          |        |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`        | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### PATCH `/v2/evals/datasets/{dataset_id}/rows/{row_id}`

Update Eval Dataset Row

| Parameter    | Location | Required | Type   |
| ------------ | -------- | -------- | ------ |
| `dataset_id` | path     | Yes      | string |
| `row_id`     | path     | Yes      | string |

**Request body:** `application/json`.

| Field             | Required                                                                               | Type           |
| ----------------- | -------------------------------------------------------------------------------------- | -------------- |
| `inputs`          | No                                                                                     | object or null |
| `expected_output` | No                                                                                     | object or null |
| Status            | Response                                                                               |                |
| ---               | ---                                                                                    |                |
| `200`             | Successful Response                                                                    |                |
| `4XX`             | Client error returned in the public API envelope                                       |                |
| `400`             | Invalid request or pagination cursor                                                   |                |
| `401`             | Missing or invalid credentials                                                         |                |
| `403`             | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                |
| `404`             | Resource not found in the caller's organization                                        |                |
| `422`             | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                |

**Required scope:** `evals.update`. Resource permissions also apply.

### DELETE `/v2/evals/datasets/{dataset_id}/rows/{row_id}`

Delete Eval Dataset Row

| Parameter    | Location                                                                          | Required | Type   |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------ |
| `dataset_id` | path                                                                              | Yes      | string |
| `row_id`     | path                                                                              | Yes      | string |
| Status       | Response                                                                          |          |        |
| ---          | ---                                                                               |          |        |
| `204`        | Successful Response                                                               |          |        |
| `4XX`        | Client error returned in the public API envelope                                  |          |        |
| `400`        | Invalid request or pagination cursor                                              |          |        |
| `401`        | Missing or invalid credentials                                                    |          |        |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`        | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.delete`. Resource permissions also apply.

### GET `/v2/evals/evaluators`

List Evaluators

| Parameter                       | Location                                                                               | Required | Type                    |
| ------------------------------- | -------------------------------------------------------------------------------------- | -------- | ----------------------- |
| `project_id`                    | query                                                                                  | Yes      | string                  |
| `search`                        | query                                                                                  | No       | string or null          |
| `compatible_with_dataset_id`    | query                                                                                  | No       | string or null          |
| `compatible_with_experiment_id` | query                                                                                  | No       | string or null          |
| `exclude_evaluator_ids`         | query                                                                                  | No       | array of string or null |
| `uses_expected_output`          | query                                                                                  | No       | boolean or null         |
| `offset`                        | query                                                                                  | No       | integer                 |
| `limit`                         | query                                                                                  | No       | integer                 |
| Status                          | Response                                                                               |          |                         |
| ---                             | ---                                                                                    |          |                         |
| `200`                           | Successful Response                                                                    |          |                         |
| `4XX`                           | Client error returned in the public API envelope                                       |          |                         |
| `400`                           | Invalid request or pagination cursor                                                   |          |                         |
| `401`                           | Missing or invalid credentials                                                         |          |                         |
| `403`                           | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |          |                         |
| `404`                           | Resource not found in the caller's organization                                        |          |                         |
| `422`                           | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |          |                         |

**Required scope:** `evals.read`. Resource permissions also apply.

### POST `/v2/evals/evaluators`

Create Evaluator

**Request body:** `application/json`.

| Field            | Required                                                                               | Type                                                                                                                                                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`     | Yes                                                                                    | string                                                                                                                                                                                                                                             |
| `name`           | Yes                                                                                    | string                                                                                                                                                                                                                                             |
| `description`    | No                                                                                     | string or null                                                                                                                                                                                                                                     |
| `evaluator_type` | Yes                                                                                    | `llm_judge`, `builtin_rule`                                                                                                                                                                                                                        |
| `config`         | Yes                                                                                    | object                                                                                                                                                                                                                                             |
| `judge_provider` | No                                                                                     | `Anthropic`, `Azure`, `Baseten`, `Bedrock`, `Cerebras`, `Core42`, `FireworksAI`, `Google`, `Google_service_account`, `Groq`, `Local`, `Meta`, `Mistral`, `Modular`, `OpenAI`, `OpenRouter`, `Perplexity`, `Replicate`, `TogetherAI`, `XAI` or null |
| `judge_model_id` | No                                                                                     | string or null                                                                                                                                                                                                                                     |
| `node_contract`  | Yes                                                                                    | object                                                                                                                                                                                                                                             |
| Status           | Response                                                                               |                                                                                                                                                                                                                                                    |
| ---              | ---                                                                                    |                                                                                                                                                                                                                                                    |
| `201`            | Successful Response                                                                    |                                                                                                                                                                                                                                                    |
| `4XX`            | Client error returned in the public API envelope                                       |                                                                                                                                                                                                                                                    |
| `400`            | Invalid request or pagination cursor                                                   |                                                                                                                                                                                                                                                    |
| `401`            | Missing or invalid credentials                                                         |                                                                                                                                                                                                                                                    |
| `403`            | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                                                                                                                                                                                                                                                    |
| `404`            | Resource not found in the caller's organization                                        |                                                                                                                                                                                                                                                    |
| `422`            | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                                                                                                                                                                                                                                                    |
| `409`            | Name conflict, concurrent operation, or dataset state prevents the operation           |                                                                                                                                                                                                                                                    |

**Required scope:** `evals.create`. Resource permissions also apply.

### GET `/v2/evals/evaluators/{evaluator_id}`

Get Evaluator

| Parameter      | Location                                                                          | Required | Type   |
| -------------- | --------------------------------------------------------------------------------- | -------- | ------ |
| `evaluator_id` | path                                                                              | Yes      | string |
| Status         | Response                                                                          |          |        |
| ---            | ---                                                                               |          |        |
| `200`          | Successful Response                                                               |          |        |
| `4XX`          | Client error returned in the public API envelope                                  |          |        |
| `400`          | Invalid request or pagination cursor                                              |          |        |
| `401`          | Missing or invalid credentials                                                    |          |        |
| `403`          | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`          | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### PATCH `/v2/evals/evaluators/{evaluator_id}`

Update Evaluator

| Parameter      | Location | Required | Type   |
| -------------- | -------- | -------- | ------ |
| `evaluator_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field            | Required                                                                               | Type                                                                                                                                                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | No                                                                                     | string or null                                                                                                                                                                                                                                     |
| `description`    | No                                                                                     | string or null                                                                                                                                                                                                                                     |
| `config`         | No                                                                                     | object or null                                                                                                                                                                                                                                     |
| `judge_provider` | No                                                                                     | `Anthropic`, `Azure`, `Baseten`, `Bedrock`, `Cerebras`, `Core42`, `FireworksAI`, `Google`, `Google_service_account`, `Groq`, `Local`, `Meta`, `Mistral`, `Modular`, `OpenAI`, `OpenRouter`, `Perplexity`, `Replicate`, `TogetherAI`, `XAI` or null |
| `judge_model_id` | No                                                                                     | string or null                                                                                                                                                                                                                                     |
| `node_contract`  | No                                                                                     | object or null                                                                                                                                                                                                                                     |
| Status           | Response                                                                               |                                                                                                                                                                                                                                                    |
| ---              | ---                                                                                    |                                                                                                                                                                                                                                                    |
| `200`            | Successful Response                                                                    |                                                                                                                                                                                                                                                    |
| `4XX`            | Client error returned in the public API envelope                                       |                                                                                                                                                                                                                                                    |
| `400`            | Invalid request or pagination cursor                                                   |                                                                                                                                                                                                                                                    |
| `401`            | Missing or invalid credentials                                                         |                                                                                                                                                                                                                                                    |
| `403`            | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                                                                                                                                                                                                                                                    |
| `404`            | Resource not found in the caller's organization                                        |                                                                                                                                                                                                                                                    |
| `422`            | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                                                                                                                                                                                                                                                    |
| `409`            | Name conflict, concurrent operation, or dataset state prevents the operation           |                                                                                                                                                                                                                                                    |

**Required scope:** `evals.update`. Resource permissions also apply.

### DELETE `/v2/evals/evaluators/{evaluator_id}`

Delete Evaluator

| Parameter      | Location                                                                          | Required | Type   |
| -------------- | --------------------------------------------------------------------------------- | -------- | ------ |
| `evaluator_id` | path                                                                              | Yes      | string |
| Status         | Response                                                                          |          |        |
| ---            | ---                                                                               |          |        |
| `204`          | Successful Response                                                               |          |        |
| `4XX`          | Client error returned in the public API envelope                                  |          |        |
| `400`          | Invalid request or pagination cursor                                              |          |        |
| `401`          | Missing or invalid credentials                                                    |          |        |
| `403`          | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`          | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.delete`. Resource permissions also apply.

### POST `/v2/evals/evaluator-previews`

Preview Evaluator

**Request body:** `application/json`.

| Field            | Required                                                                               | Type                                                                                                                                                                                                                                               |
| ---------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`     | Yes                                                                                    | string                                                                                                                                                                                                                                             |
| `evaluator_type` | Yes                                                                                    | `llm_judge`, `builtin_rule`                                                                                                                                                                                                                        |
| `config`         | Yes                                                                                    | object                                                                                                                                                                                                                                             |
| `judge_provider` | No                                                                                     | `Anthropic`, `Azure`, `Baseten`, `Bedrock`, `Cerebras`, `Core42`, `FireworksAI`, `Google`, `Google_service_account`, `Groq`, `Local`, `Meta`, `Mistral`, `Modular`, `OpenAI`, `OpenRouter`, `Perplexity`, `Replicate`, `TogetherAI`, `XAI` or null |
| `judge_model_id` | No                                                                                     | string or null                                                                                                                                                                                                                                     |
| `samples`        | Yes                                                                                    | array of object                                                                                                                                                                                                                                    |
| Status           | Response                                                                               |                                                                                                                                                                                                                                                    |
| ---              | ---                                                                                    |                                                                                                                                                                                                                                                    |
| `200`            | Successful Response                                                                    |                                                                                                                                                                                                                                                    |
| `4XX`            | Client error returned in the public API envelope                                       |                                                                                                                                                                                                                                                    |
| `400`            | Invalid request or pagination cursor                                                   |                                                                                                                                                                                                                                                    |
| `401`            | Missing or invalid credentials                                                         |                                                                                                                                                                                                                                                    |
| `403`            | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                                                                                                                                                                                                                                                    |
| `404`            | Resource not found in the caller's organization                                        |                                                                                                                                                                                                                                                    |
| `422`            | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                                                                                                                                                                                                                                                    |

**Required scope:** `evals.run`. Resource permissions also apply.

### GET `/v2/evals/evaluator-templates`

List Evaluator Templates

| Status | Response                                                                          |
| ------ | --------------------------------------------------------------------------------- |
| `200`  | Successful Response                                                               |
| `4XX`  | Client error returned in the public API envelope                                  |
| `400`  | Invalid request or pagination cursor                                              |
| `401`  | Missing or invalid credentials                                                    |
| `403`  | Denied permission, project folder access, or API-key scope (meta.required\_scope) |

**Required scope:** `evals.read`. Resource permissions also apply.

### GET `/v2/evals/experiments`

List Eval Experiments

| Parameter    | Location                                                                          | Required | Type           |
| ------------ | --------------------------------------------------------------------------------- | -------- | -------------- |
| `project_id` | query                                                                             | Yes      | string         |
| `dataset_id` | query                                                                             | No       | string or null |
| `search`     | query                                                                             | No       | string or null |
| `offset`     | query                                                                             | No       | integer        |
| `limit`      | query                                                                             | No       | integer        |
| Status       | Response                                                                          |          |                |
| ---          | ---                                                                               |          |                |
| `200`        | Successful Response                                                               |          |                |
| `4XX`        | Client error returned in the public API envelope                                  |          |                |
| `400`        | Invalid request or pagination cursor                                              |          |                |
| `401`        | Missing or invalid credentials                                                    |          |                |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |                |
| `404`        | Resource not found in the caller's organization                                   |          |                |

**Required scope:** `evals.read`. Resource permissions also apply.

### POST `/v2/evals/experiments`

Create Eval Experiment

**Request body:** `application/json`.

| Field                | Required                                                                               | Type              |
| -------------------- | -------------------------------------------------------------------------------------- | ----------------- |
| `dataset_id`         | Yes                                                                                    | string            |
| `project_version_id` | Yes                                                                                    | string or integer |
| `evaluator_ids`      | No                                                                                     | array of string   |
| `name`               | No                                                                                     | string or null    |
| `notes`              | No                                                                                     | string or null    |
| Status               | Response                                                                               |                   |
| ---                  | ---                                                                                    |                   |
| `201`                | Successful Response                                                                    |                   |
| `4XX`                | Client error returned in the public API envelope                                       |                   |
| `400`                | Invalid request or pagination cursor                                                   |                   |
| `401`                | Missing or invalid credentials                                                         |                   |
| `403`                | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                   |
| `404`                | Resource not found in the caller's organization                                        |                   |
| `422`                | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                   |
| `409`                | Name conflict, concurrent operation, or dataset state prevents the operation           |                   |

**Required scope:** `evals.create`. Resource permissions also apply.

### GET `/v2/evals/experiments/{experiment_id}`

Get Eval Experiment

| Parameter       | Location                                                                          | Required | Type   |
| --------------- | --------------------------------------------------------------------------------- | -------- | ------ |
| `experiment_id` | path                                                                              | Yes      | string |
| Status          | Response                                                                          |          |        |
| ---             | ---                                                                               |          |        |
| `200`           | Successful Response                                                               |          |        |
| `4XX`           | Client error returned in the public API envelope                                  |          |        |
| `400`           | Invalid request or pagination cursor                                              |          |        |
| `401`           | Missing or invalid credentials                                                    |          |        |
| `403`           | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`           | Resource not found in the caller's organization                                   |          |        |
| `503`           | Job launch was rejected or job state is temporarily unavailable                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### PATCH `/v2/evals/experiments/{experiment_id}`

Update Eval Experiment

| Parameter       | Location | Required | Type   |
| --------------- | -------- | -------- | ------ |
| `experiment_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field   | Required                                                                          | Type           |
| ------- | --------------------------------------------------------------------------------- | -------------- |
| `name`  | No                                                                                | string or null |
| `notes` | No                                                                                | string or null |
| Status  | Response                                                                          |                |
| ---     | ---                                                                               |                |
| `200`   | Successful Response                                                               |                |
| `4XX`   | Client error returned in the public API envelope                                  |                |
| `400`   | Invalid request or pagination cursor                                              |                |
| `401`   | Missing or invalid credentials                                                    |                |
| `403`   | Denied permission, project folder access, or API-key scope (meta.required\_scope) |                |
| `404`   | Resource not found in the caller's organization                                   |                |

**Required scope:** `evals.update`. Resource permissions also apply.

### DELETE `/v2/evals/experiments/{experiment_id}`

Delete Eval Experiment

| Parameter       | Location                                                                          | Required | Type   |
| --------------- | --------------------------------------------------------------------------------- | -------- | ------ |
| `experiment_id` | path                                                                              | Yes      | string |
| Status          | Response                                                                          |          |        |
| ---             | ---                                                                               |          |        |
| `204`           | Successful Response                                                               |          |        |
| `4XX`           | Client error returned in the public API envelope                                  |          |        |
| `400`           | Invalid request or pagination cursor                                              |          |        |
| `401`           | Missing or invalid credentials                                                    |          |        |
| `403`           | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`           | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.delete`. Resource permissions also apply.

### GET `/v2/evals/experiments/{experiment_id}/rows`

List Eval Experiment Rows

| Parameter       | Location                                                                          | Required | Type    |
| --------------- | --------------------------------------------------------------------------------- | -------- | ------- |
| `experiment_id` | path                                                                              | Yes      | string  |
| `offset`        | query                                                                             | No       | integer |
| `limit`         | query                                                                             | No       | integer |
| Status          | Response                                                                          |          |         |
| ---             | ---                                                                               |          |         |
| `200`           | Successful Response                                                               |          |         |
| `4XX`           | Client error returned in the public API envelope                                  |          |         |
| `400`           | Invalid request or pagination cursor                                              |          |         |
| `401`           | Missing or invalid credentials                                                    |          |         |
| `403`           | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |         |
| `404`           | Resource not found in the caller's organization                                   |          |         |
| `503`           | Job launch was rejected or job state is temporarily unavailable                   |          |         |

**Required scope:** `evals.read`. Resource permissions also apply.

### GET `/v2/evals/experiments/{experiment_id}/status`

Get Eval Experiment Status

| Parameter       | Location                                                                          | Required | Type   |
| --------------- | --------------------------------------------------------------------------------- | -------- | ------ |
| `experiment_id` | path                                                                              | Yes      | string |
| Status          | Response                                                                          |          |        |
| ---             | ---                                                                               |          |        |
| `200`           | Successful Response                                                               |          |        |
| `4XX`           | Client error returned in the public API envelope                                  |          |        |
| `400`           | Invalid request or pagination cursor                                              |          |        |
| `401`           | Missing or invalid credentials                                                    |          |        |
| `403`           | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`           | Resource not found in the caller's organization                                   |          |        |
| `503`           | Job launch was rejected or job state is temporarily unavailable                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### POST `/v2/evals/experiments/{experiment_id}/jobs`

Create Eval Experiment Job

| Parameter       | Location | Required | Type   |
| --------------- | -------- | -------- | ------ |
| `experiment_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field           | Required                                                                                                                                                                                                                                                                                          | Type                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| `mode`          | Yes                                                                                                                                                                                                                                                                                               | `generate`, `score` |
| `evaluator_ids` | No                                                                                                                                                                                                                                                                                                | array of string     |
| Status          | Response                                                                                                                                                                                                                                                                                          |                     |
| ---             | ---                                                                                                                                                                                                                                                                                               |                     |
| `202`           | Successful Response                                                                                                                                                                                                                                                                               |                     |
| `4XX`           | Client error returned in the public API envelope                                                                                                                                                                                                                                                  |                     |
| `400`           | Invalid request or pagination cursor                                                                                                                                                                                                                                                              |                     |
| `401`           | Missing or invalid credentials                                                                                                                                                                                                                                                                    |                     |
| `403`           | Denied permission, project folder access, or API-key scope (meta.required\_scope)                                                                                                                                                                                                                 |                     |
| `404`           | Resource not found in the caller's organization                                                                                                                                                                                                                                                   |                     |
| `422`           | Invalid evaluation contract, row shape, evaluator configuration, or filter combination                                                                                                                                                                                                            |                     |
| `409`           | The experiment already has an active job. When its identity is known, the error envelope includes meta.job\_id, meta.experiment\_id, meta.status\_url and a matching Location header. Poll that job until it reaches a final status, then retry. Other conflicts omit this metadata and Location. |                     |
| `503`           | Job launch was rejected or job state is temporarily unavailable                                                                                                                                                                                                                                   |                     |

**Required scope:** `evals.run`. Resource permissions also apply.

### GET `/v2/evals/experiments/{experiment_id}/jobs/{job_id}`

Get Eval Experiment Job

| Parameter       | Location                                                                          | Required | Type   |
| --------------- | --------------------------------------------------------------------------------- | -------- | ------ |
| `experiment_id` | path                                                                              | Yes      | string |
| `job_id`        | path                                                                              | Yes      | string |
| Status          | Response                                                                          |          |        |
| ---             | ---                                                                               |          |        |
| `200`           | Successful Response                                                               |          |        |
| `4XX`           | Client error returned in the public API envelope                                  |          |        |
| `400`           | Invalid request or pagination cursor                                              |          |        |
| `401`           | Missing or invalid credentials                                                    |          |        |
| `403`           | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`           | Resource not found in the caller's organization                                   |          |        |
| `503`           | Job launch was rejected or job state is temporarily unavailable                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### GET `/v2/evals/monitor-limits`

Get Eval Monitor Limits

| Status | Response                                                                          |
| ------ | --------------------------------------------------------------------------------- |
| `200`  | Successful Response                                                               |
| `4XX`  | Client error returned in the public API envelope                                  |
| `400`  | Invalid request or pagination cursor                                              |
| `401`  | Missing or invalid credentials                                                    |
| `403`  | Denied permission, project folder access, or API-key scope (meta.required\_scope) |

**Required scope:** `evals.read`. Resource permissions also apply.

### GET `/v2/evals/monitors`

List Eval Monitors

| Parameter    | Location                                                                          | Required | Type           |
| ------------ | --------------------------------------------------------------------------------- | -------- | -------------- |
| `project_id` | query                                                                             | Yes      | string         |
| `search`     | query                                                                             | No       | string or null |
| `offset`     | query                                                                             | No       | integer        |
| `limit`      | query                                                                             | No       | integer        |
| Status       | Response                                                                          |          |                |
| ---          | ---                                                                               |          |                |
| `200`        | Successful Response                                                               |          |                |
| `4XX`        | Client error returned in the public API envelope                                  |          |                |
| `400`        | Invalid request or pagination cursor                                              |          |                |
| `401`        | Missing or invalid credentials                                                    |          |                |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |                |
| `404`        | Resource not found in the caller's organization                                   |          |                |

**Required scope:** `evals.read`. Resource permissions also apply.

### POST `/v2/evals/monitors`

Create Eval Monitor

**Request body:** `application/json`.

| Field                   | Required                                                                               | Type           |
| ----------------------- | -------------------------------------------------------------------------------------- | -------------- |
| `project_id`            | Yes                                                                                    | string         |
| `name`                  | No                                                                                     | string or null |
| `evaluator_id`          | Yes                                                                                    | string         |
| `notifications_enabled` | No                                                                                     | boolean        |
| `sampling_rate`         | No                                                                                     | number         |
| `max_runs_daily`        | No                                                                                     | integer        |
| Status                  | Response                                                                               |                |
| ---                     | ---                                                                                    |                |
| `201`                   | Successful Response                                                                    |                |
| `4XX`                   | Client error returned in the public API envelope                                       |                |
| `400`                   | Invalid request or pagination cursor                                                   |                |
| `401`                   | Missing or invalid credentials                                                         |                |
| `403`                   | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |                |
| `404`                   | Resource not found in the caller's organization                                        |                |
| `422`                   | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |                |
| `409`                   | Name conflict, concurrent operation, or dataset state prevents the operation           |                |

**Required scope:** `evals.create`. Resource permissions also apply.

### GET `/v2/evals/monitors/{monitor_id}`

Get Eval Monitor

| Parameter    | Location                                                                          | Required | Type   |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------ |
| `monitor_id` | path                                                                              | Yes      | string |
| Status       | Response                                                                          |          |        |
| ---          | ---                                                                               |          |        |
| `200`        | Successful Response                                                               |          |        |
| `4XX`        | Client error returned in the public API envelope                                  |          |        |
| `400`        | Invalid request or pagination cursor                                              |          |        |
| `401`        | Missing or invalid credentials                                                    |          |        |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`        | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### PATCH `/v2/evals/monitors/{monitor_id}`

Update Eval Monitor

| Parameter    | Location | Required | Type   |
| ------------ | -------- | -------- | ------ |
| `monitor_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field            | Required                                                                          | Type            |
| ---------------- | --------------------------------------------------------------------------------- | --------------- |
| `name`           | No                                                                                | string or null  |
| `description`    | No                                                                                | string or null  |
| `enabled`        | No                                                                                | boolean or null |
| `sampling_rate`  | No                                                                                | number or null  |
| `max_runs_daily` | No                                                                                | integer or null |
| Status           | Response                                                                          |                 |
| ---              | ---                                                                               |                 |
| `200`            | Successful Response                                                               |                 |
| `4XX`            | Client error returned in the public API envelope                                  |                 |
| `400`            | Invalid request or pagination cursor                                              |                 |
| `401`            | Missing or invalid credentials                                                    |                 |
| `403`            | Denied permission, project folder access, or API-key scope (meta.required\_scope) |                 |
| `404`            | Resource not found in the caller's organization                                   |                 |
| `409`            | Name conflict, concurrent operation, or dataset state prevents the operation      |                 |

**Required scope:** `evals.update`. Resource permissions also apply.

### DELETE `/v2/evals/monitors/{monitor_id}`

Delete Eval Monitor

| Parameter    | Location                                                                          | Required | Type   |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------ |
| `monitor_id` | path                                                                              | Yes      | string |
| Status       | Response                                                                          |          |        |
| ---          | ---                                                                               |          |        |
| `204`        | Successful Response                                                               |          |        |
| `4XX`        | Client error returned in the public API envelope                                  |          |        |
| `400`        | Invalid request or pagination cursor                                              |          |        |
| `401`        | Missing or invalid credentials                                                    |          |        |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`        | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.delete`. Resource permissions also apply.

### GET `/v2/evals/monitors/{monitor_id}/score-stats`

Get Eval Monitor Score Stats

| Parameter    | Location                                                                          | Required | Type                      |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------------------------- |
| `monitor_id` | path                                                                              | Yes      | string                    |
| `window`     | query                                                                             | No       | `24h`, `7d`, `30d`, `all` |
| Status       | Response                                                                          |          |                           |
| ---          | ---                                                                               |          |                           |
| `200`        | Successful Response                                                               |          |                           |
| `4XX`        | Client error returned in the public API envelope                                  |          |                           |
| `400`        | Invalid request or pagination cursor                                              |          |                           |
| `401`        | Missing or invalid credentials                                                    |          |                           |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |                           |
| `404`        | Resource not found in the caller's organization                                   |          |                           |

**Required scope:** `evals.read`. Resource permissions also apply.

### GET `/v2/evals/monitors/{monitor_id}/alert`

Get Eval Monitor Alert

| Parameter    | Location                                                                          | Required | Type   |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------ |
| `monitor_id` | path                                                                              | Yes      | string |
| Status       | Response                                                                          |          |        |
| ---          | ---                                                                               |          |        |
| `200`        | Successful Response                                                               |          |        |
| `4XX`        | Client error returned in the public API envelope                                  |          |        |
| `400`        | Invalid request or pagination cursor                                              |          |        |
| `401`        | Missing or invalid credentials                                                    |          |        |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`        | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### PATCH `/v2/evals/monitors/{monitor_id}/alert`

Update Eval Monitor Alert

| Parameter    | Location | Required | Type   |
| ------------ | -------- | -------- | ------ |
| `monitor_id` | path     | Yes      | string |

**Request body:** `application/json`.

| Field                   | Required                                                                          | Type            |
| ----------------------- | --------------------------------------------------------------------------------- | --------------- |
| `threshold`             | No                                                                                | number or null  |
| `warning_threshold`     | No                                                                                | number or null  |
| `min_samples`           | No                                                                                | integer or null |
| `window_max_runs`       | No                                                                                | integer or null |
| `window_hours`          | No                                                                                | integer or null |
| `min_effect_size`       | No                                                                                | number or null  |
| `recovery_threshold`    | No                                                                                | number or null  |
| `renotify_hours`        | No                                                                                | integer or null |
| `notifications_enabled` | No                                                                                | boolean or null |
| Status                  | Response                                                                          |                 |
| ---                     | ---                                                                               |                 |
| `200`                   | Successful Response                                                               |                 |
| `4XX`                   | Client error returned in the public API envelope                                  |                 |
| `400`                   | Invalid request or pagination cursor                                              |                 |
| `401`                   | Missing or invalid credentials                                                    |                 |
| `403`                   | Denied permission, project folder access, or API-key scope (meta.required\_scope) |                 |
| `404`                   | Resource not found in the caller's organization                                   |                 |

**Required scope:** `evals.update`. Resource permissions also apply.

### GET `/v2/evals/monitors/{monitor_id}/sampled-runs`

List Eval Monitor Sampled Runs

| Parameter    | Location                                                                          | Required | Type                      |
| ------------ | --------------------------------------------------------------------------------- | -------- | ------------------------- |
| `monitor_id` | path                                                                              | Yes      | string                    |
| `window`     | query                                                                             | No       | `24h`, `7d`, `30d`, `all` |
| `cursor`     | query                                                                             | No       | string or null            |
| `page_size`  | query                                                                             | No       | integer                   |
| `direction`  | query                                                                             | No       | `next`, `prev`            |
| Status       | Response                                                                          |          |                           |
| ---          | ---                                                                               |          |                           |
| `200`        | Successful Response                                                               |          |                           |
| `4XX`        | Client error returned in the public API envelope                                  |          |                           |
| `400`        | Invalid request or pagination cursor                                              |          |                           |
| `401`        | Missing or invalid credentials                                                    |          |                           |
| `403`        | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |                           |
| `404`        | Resource not found in the caller's organization                                   |          |                           |

**Required scope:** `evals.read`. Resource permissions also apply.

### POST `/v2/evals/runs/{run_id}/scores`

Create Eval Run Score

| Parameter | Location | Required | Type   |
| --------- | -------- | -------- | ------ |
| `run_id`  | path     | Yes      | string |

**Request body:** `application/json`.

| Field          | Required                                                                               | Type   |
| -------------- | -------------------------------------------------------------------------------------- | ------ |
| `evaluator_id` | Yes                                                                                    | string |
| Status         | Response                                                                               |        |
| ---            | ---                                                                                    |        |
| `201`          | Successful Response                                                                    |        |
| `4XX`          | Client error returned in the public API envelope                                       |        |
| `400`          | Invalid request or pagination cursor                                                   |        |
| `401`          | Missing or invalid credentials                                                         |        |
| `403`          | Denied permission, project folder access, or API-key scope (meta.required\_scope)      |        |
| `404`          | Resource not found in the caller's organization                                        |        |
| `422`          | Invalid evaluation contract, row shape, evaluator configuration, or filter combination |        |

**Required scope:** `evals.run`. Resource permissions also apply.

### GET `/v2/evals/runs/{run_id}/scores`

List Eval Run Scores

| Parameter   | Location                                                                          | Required | Type           |
| ----------- | --------------------------------------------------------------------------------- | -------- | -------------- |
| `run_id`    | path                                                                              | Yes      | string         |
| `cursor`    | query                                                                             | No       | string or null |
| `page_size` | query                                                                             | No       | integer        |
| `direction` | query                                                                             | No       | `next`, `prev` |
| Status      | Response                                                                          |          |                |
| ---         | ---                                                                               |          |                |
| `200`       | Successful Response                                                               |          |                |
| `4XX`       | Client error returned in the public API envelope                                  |          |                |
| `400`       | Invalid request or pagination cursor                                              |          |                |
| `401`       | Missing or invalid credentials                                                    |          |                |
| `403`       | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |                |
| `404`       | Resource not found in the caller's organization                                   |          |                |

**Required scope:** `evals.read`. Resource permissions also apply.

### GET `/v2/evals/scores/{score_id}`

Get Eval Run Score

| Parameter  | Location                                                                          | Required | Type   |
| ---------- | --------------------------------------------------------------------------------- | -------- | ------ |
| `score_id` | path                                                                              | Yes      | string |
| Status     | Response                                                                          |          |        |
| ---        | ---                                                                               |          |        |
| `200`      | Successful Response                                                               |          |        |
| `4XX`      | Client error returned in the public API envelope                                  |          |        |
| `400`      | Invalid request or pagination cursor                                              |          |        |
| `401`      | Missing or invalid credentials                                                    |          |        |
| `403`      | Denied permission, project folder access, or API-key scope (meta.required\_scope) |          |        |
| `404`      | Resource not found in the caller's organization                                   |          |        |

**Required scope:** `evals.read`. Resource permissions also apply.

### GET `/analytics/org/{org_id}/flows/{flow_id}`

List Flow Runs

| Parameter    | Location            | Required | Type           |
| ------------ | ------------------- | -------- | -------------- |
| `flow_id`    | path                | Yes      | string         |
| `org_id`     | path                | Yes      | string         |
| `page`       | query               | No       | integer        |
| `page_size`  | query               | No       | integer        |
| `start_date` | query               | No       | string or null |
| `end_date`   | query               | No       | string or null |
| `user_id`    | query               | No       | string or null |
| `state`      | query               | No       | string or null |
| Status       | Response            |          |                |
| ---          | ---                 |          |                |
| `200`        | Successful Response |          |                |
| `422`        | Validation Error    |          |                |

### GET `/v2/providers`

List Providers

| Parameter | Location            | Required | Type    |
| --------- | ------------------- | -------- | ------- |
| `offset`  | query               | No       | integer |
| `limit`   | query               | No       | integer |
| Status    | Response            |          |         |
| ---       | ---                 |          |         |
| `200`     | Successful Response |          |         |
| `422`     | Validation Error    |          |         |

### GET `/v2/providers/{provider_id}`

Get Provider

| Parameter     | Location            | Required | Type   |
| ------------- | ------------------- | -------- | ------ |
| `provider_id` | path                | Yes      | string |
| Status        | Response            |          |        |
| ---           | ---                 |          |        |
| `200`         | Successful Response |          |        |
| `422`         | Validation Error    |          |        |

### GET `/v2/providers/{provider_id}/actions`

List Provider Actions

| Parameter     | Location            | Required | Type    |
| ------------- | ------------------- | -------- | ------- |
| `provider_id` | path                | Yes      | string  |
| `offset`      | query               | No       | integer |
| `limit`       | query               | No       | integer |
| Status        | Response            |          |         |
| ---           | ---                 |          |         |
| `200`         | Successful Response |          |         |
| `422`         | Validation Error    |          |         |

### GET `/v2/providers/{provider_id}/actions/{action_id}`

Get Provider Action

| Parameter     | Location            | Required | Type   |
| ------------- | ------------------- | -------- | ------ |
| `provider_id` | path                | Yes      | string |
| `action_id`   | path                | Yes      | string |
| Status        | Response            |          |        |
| ---           | ---                 |          |        |
| `200`         | Successful Response |          |        |
| `422`         | Validation Error    |          |        |

### GET `/v2/providers/{provider_id}/triggers`

List Provider Triggers

| Parameter     | Location            | Required | Type    |
| ------------- | ------------------- | -------- | ------- |
| `provider_id` | path                | Yes      | string  |
| `offset`      | query               | No       | integer |
| `limit`       | query               | No       | integer |
| Status        | Response            |          |         |
| ---           | ---                 |          |         |
| `200`         | Successful Response |          |         |
| `422`         | Validation Error    |          |         |

### GET `/v2/providers/{provider_id}/triggers/{trigger_id}`

Get Provider Trigger

| Parameter     | Location            | Required | Type   |
| ------------- | ------------------- | -------- | ------ |
| `provider_id` | path                | Yes      | string |
| `trigger_id`  | path                | Yes      | string |
| Status        | Response            |          |        |
| ---           | ---                 |          |        |
| `200`         | Successful Response |          |        |
| `422`         | Validation Error    |          |        |

### POST `/v2/providers/{provider_id}/actions/{action_id}/run`

Run Provider Action

| Parameter     | Location | Required | Type   |
| ------------- | -------- | -------- | ------ |
| `provider_id` | path     | Yes      | string |
| `action_id`   | path     | Yes      | string |

**Request body:** `application/json`.

| Field           | Required            | Type           |
| --------------- | ------------------- | -------------- |
| `connection_id` | No                  | string or null |
| `inputs`        | Yes                 | object         |
| Status          | Response            |                |
| ---             | ---                 |                |
| `200`           | Successful Response |                |
| `422`           | Validation Error    |                |

### GET `/v2/connections`

List Connections

| Parameter     | Location            | Required | Type           |
| ------------- | ------------------- | -------- | -------------- |
| `provider_id` | query               | No       | string or null |
| `offset`      | query               | No       | integer        |
| `limit`       | query               | No       | integer        |
| Status        | Response            |          |                |
| ---           | ---                 |          |                |
| `200`         | Successful Response |          |                |
| `422`         | Validation Error    |          |                |

### POST `/v2/webhooks/subscriptions`

Create Webhook Subscription

**Request body:** `application/json`.

| Field         | Required            | Type                                                                                                            |
| ------------- | ------------------- | --------------------------------------------------------------------------------------------------------------- |
| `url`         | Yes                 | string                                                                                                          |
| `event_types` | Yes                 | array of `run.started`, `run.step.succeeded`, `run.step.failed`, `run.succeeded`, `run.failed`, `run.cancelled` |
| Status        | Response            |                                                                                                                 |
| ---           | ---                 |                                                                                                                 |
| `201`         | Successful Response |                                                                                                                 |
| `422`         | Validation Error    |                                                                                                                 |

### GET `/v2/webhooks/subscriptions`

List Webhook Subscriptions

| Parameter | Location            | Required | Type    |
| --------- | ------------------- | -------- | ------- |
| `offset`  | query               | No       | integer |
| `limit`   | query               | No       | integer |
| Status    | Response            |          |         |
| ---       | ---                 |          |         |
| `200`     | Successful Response |          |         |
| `422`     | Validation Error    |          |         |

### DELETE `/v2/webhooks/subscriptions/{subscription_id}`

Delete Webhook Subscription

| Parameter         | Location            | Required | Type   |
| ----------------- | ------------------- | -------- | ------ |
| `subscription_id` | path                | Yes      | string |
| Status            | Response            |          |        |
| ---               | ---                 |          |        |
| `204`             | Successful Response |          |        |
| `422`             | Validation Error    |          |        |

### POST `/v2/runs`

Start Run

**Request body:** `application/json`.

| Field             | Required                                                                                        | Type            |
| ----------------- | ----------------------------------------------------------------------------------------------- | --------------- |
| `project_id`      | Yes                                                                                             | string          |
| `input`           | Yes                                                                                             | object          |
| `project_version` | No                                                                                              | integer or null |
| Status            | Response                                                                                        |                 |
| ---               | ---                                                                                             |                 |
| `201`             | Run created. Execution is asynchronous; poll the Location URL for progress.                     |                 |
| `400`             | Invalid request body.                                                                           |                 |
| `401`             | Authentication required.                                                                        |                 |
| `402`             | Organization usage limit reached.                                                               |                 |
| `403`             | Project run permission or credential scope required.                                            |                 |
| `404`             | Project or requested project version not found, project not published, or run logging disabled. |                 |
| `500`             | Run start or response retrieval failed; execution may already have started.                     |                 |
| `503`             | Run reservation failed; execution was not dispatched.                                           |                 |
| `422`             | Validation Error                                                                                |                 |

### GET `/v2/runs`

List Runs

| Parameter         | Location                            | Required | Type                                                                                                                                               |
| ----------------- | ----------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_id`      | query                               | No       | string or null                                                                                                                                     |
| `status`          | query                               | No       | `queued`, `running`, `paused`, `succeeded`, `failed`, `cancelled` or null                                                                          |
| `run_type`        | query                               | No       | `workflow_builder`, `form`, `batch`, `chat_assistant`, `agent_assistant`, `trigger`, `scheduled`, `sub_workflow`, `api`, `eval`, `unknown` or null |
| `created_by_id`   | query                               | No       | string or null                                                                                                                                     |
| `created_at__gte` | query                               | No       | string or null                                                                                                                                     |
| `created_at__lte` | query                               | No       | string or null                                                                                                                                     |
| `cursor`          | query                               | No       | string or null                                                                                                                                     |
| `page_size`       | query                               | No       | integer                                                                                                                                            |
| Status            | Response                            |          |                                                                                                                                                    |
| ---               | ---                                 |          |                                                                                                                                                    |
| `200`             | Successful Response                 |          |                                                                                                                                                    |
| `400`             | Invalid cursor or filter.           |          |                                                                                                                                                    |
| `401`             | Authentication required.            |          |                                                                                                                                                    |
| `403`             | Analytics read permission required. |          |                                                                                                                                                    |
| `422`             | Validation Error                    |          |                                                                                                                                                    |

### GET `/v2/runs/{run_id}`

Get Run

| Parameter | Location                                                    | Required | Type   |
| --------- | ----------------------------------------------------------- | -------- | ------ |
| `run_id`  | path                                                        | Yes      | string |
| Status    | Response                                                    |          |        |
| ---       | ---                                                         |          |        |
| `200`     | Successful Response                                         |          |        |
| `400`     | Invalid run ID.                                             |          |        |
| `401`     | Authentication required.                                    |          |        |
| `403`     | Analytics read permission required or run logging disabled. |          |        |
| `404`     | Run not found.                                              |          |        |
| `422`     | Validation Error                                            |          |        |

### POST `/v2/runs/{run_id}/cancel`

Cancel Run

| Parameter | Location                                                                        | Required | Type   |
| --------- | ------------------------------------------------------------------------------- | -------- | ------ |
| `run_id`  | path                                                                            | Yes      | string |
| Status    | Response                                                                        |          |        |
| ---       | ---                                                                             |          |        |
| `202`     | Cancellation accepted. Poll the Location URL for the current run state.         |          |        |
| `400`     | Invalid run ID.                                                                 |          |        |
| `401`     | Authentication required.                                                        |          |        |
| `403`     | Project run permission or credential scope required, or run logging disabled.   |          |        |
| `404`     | Run not found, inaccessible, or not owned by the authenticated actor.           |          |        |
| `409`     | Run is no longer cancellable.                                                   |          |        |
| `500`     | Cancellation signalling failed; the request may already have changed run state. |          |        |
| `422`     | Validation Error                                                                |          |        |

### POST `/v2/runs/{run_id}/resume`

Resume Run

| Parameter | Location | Required | Type   |
| --------- | -------- | -------- | ------ |
| `run_id`  | path     | Yes      | string |

**Request body:** `application/json`.

| Field           | Required                                                                      | Type                                 |
| --------------- | ----------------------------------------------------------------------------- | ------------------------------------ |
| `resume_token`  | Yes                                                                           | string                               |
| `response`      | Yes                                                                           | string                               |
| `response_type` | No                                                                            | `text`, `approval`, `choice` or null |
| Status          | Response                                                                      |                                      |
| ---             | ---                                                                           |                                      |
| `202`           | Resume accepted. Poll the Location URL for the current run state.             |                                      |
| `400`           | Invalid or expired resume token, run ID or request body.                      |                                      |
| `401`           | Authentication required.                                                      |                                      |
| `402`           | Organization usage limit reached.                                             |                                      |
| `403`           | Project run permission or credential scope required, or run logging disabled. |                                      |
| `404`           | Run not found or inaccessible.                                                |                                      |
| `409`           | The run cannot be resumed through this endpoint in its current state.         |                                      |
| `500`           | Resume failed; usage may already have been charged.                           |                                      |
| `422`           | Validation Error                                                              |                                      |

### GET `/v2/skills`

List Skills

| Parameter | Location                                                                    | Required | Type    |
| --------- | --------------------------------------------------------------------------- | -------- | ------- |
| `offset`  | query                                                                       | No       | integer |
| `limit`   | query                                                                       | No       | integer |
| Status    | Response                                                                    |          |         |
| ---       | ---                                                                         |          |         |
| `200`     | Successful Response                                                         |          |         |
| `4XX`     | Other client errors use the same public error envelope                      |          |         |
| `400`     | Invalid request parameters                                                  |          |         |
| `401`     | Authentication required                                                     |          |         |
| `403`     | Permission denied; insufficient API-key scope includes meta.required\_scope |          |         |

**Required scope:** `skills.read`. Resource permissions also apply.

### POST `/v2/skills`

Create Skill

**Request body:** `multipart/form-data`.

| Field          | Required                                                                    | Type            |
| -------------- | --------------------------------------------------------------------------- | --------------- |
| `files`        | No                                                                          | array of string |
| `name`         | No                                                                          | string or null  |
| `description`  | No                                                                          | string or null  |
| `instructions` | No                                                                          | string or null  |
| `actions`      | No                                                                          | array of string |
| Status         | Response                                                                    |                 |
| ---            | ---                                                                         |                 |
| `201`          | Created                                                                     |                 |
| `4XX`          | Other client errors use the same public error envelope                      |                 |
| `400`          | Invalid request parameters                                                  |                 |
| `401`          | Authentication required                                                     |                 |
| `403`          | Permission denied; insufficient API-key scope includes meta.required\_scope |                 |
| `409`          | Name or version conflict                                                    |                 |
| `422`          | Invalid skill bundle, including oversized uploads                           |                 |
| `500`          | The skill could not be saved.                                               |                 |

**Required scope:** `skills.create`. Resource permissions also apply.

### GET `/v2/skills/{skill_id}`

Get Skill

| Parameter  | Location                                                                    | Required | Type   |
| ---------- | --------------------------------------------------------------------------- | -------- | ------ |
| `skill_id` | path                                                                        | Yes      | string |
| Status     | Response                                                                    |          |        |
| ---        | ---                                                                         |          |        |
| `200`      | Successful Response                                                         |          |        |
| `4XX`      | Other client errors use the same public error envelope                      |          |        |
| `400`      | Invalid request parameters                                                  |          |        |
| `401`      | Authentication required                                                     |          |        |
| `403`      | Permission denied; insufficient API-key scope includes meta.required\_scope |          |        |
| `404`      | Skill or version not found                                                  |          |        |

**Required scope:** `skills.read`. Resource permissions also apply.

### DELETE `/v2/skills/{skill_id}`

Delete Skill

| Parameter  | Location                                                                    | Required | Type   |
| ---------- | --------------------------------------------------------------------------- | -------- | ------ |
| `skill_id` | path                                                                        | Yes      | string |
| Status     | Response                                                                    |          |        |
| ---        | ---                                                                         |          |        |
| `204`      | Successful Response                                                         |          |        |
| `4XX`      | Other client errors use the same public error envelope                      |          |        |
| `400`      | Invalid request parameters                                                  |          |        |
| `401`      | Authentication required                                                     |          |        |
| `403`      | Permission denied; insufficient API-key scope includes meta.required\_scope |          |        |
| `404`      | Skill or version not found                                                  |          |        |

**Required scope:** `skills.delete`. Resource permissions also apply.

### GET `/v2/skills/{skill_id}/versions`

List Skill Versions

| Parameter  | Location                                                                    | Required | Type    |
| ---------- | --------------------------------------------------------------------------- | -------- | ------- |
| `skill_id` | path                                                                        | Yes      | string  |
| `offset`   | query                                                                       | No       | integer |
| `limit`    | query                                                                       | No       | integer |
| Status     | Response                                                                    |          |         |
| ---        | ---                                                                         |          |         |
| `200`      | Successful Response                                                         |          |         |
| `4XX`      | Other client errors use the same public error envelope                      |          |         |
| `400`      | Invalid request parameters                                                  |          |         |
| `401`      | Authentication required                                                     |          |         |
| `403`      | Permission denied; insufficient API-key scope includes meta.required\_scope |          |         |
| `404`      | Skill or version not found                                                  |          |         |

**Required scope:** `skills.read`. Resource permissions also apply.

### POST `/v2/skills/{skill_id}/versions`

Create Skill Version

| Parameter  | Location | Required | Type   |
| ---------- | -------- | -------- | ------ |
| `skill_id` | path     | Yes      | string |

**Request body:** `multipart/form-data`.

| Field          | Required                                                                    | Type            |
| -------------- | --------------------------------------------------------------------------- | --------------- |
| `files`        | No                                                                          | array of string |
| `name`         | No                                                                          | string or null  |
| `description`  | No                                                                          | string or null  |
| `instructions` | No                                                                          | string or null  |
| `actions`      | No                                                                          | array of string |
| `carry_paths`  | No                                                                          | array of string |
| `base_version` | No                                                                          | integer or null |
| Status         | Response                                                                    |                 |
| ---            | ---                                                                         |                 |
| `201`          | Created                                                                     |                 |
| `4XX`          | Other client errors use the same public error envelope                      |                 |
| `400`          | Invalid request parameters                                                  |                 |
| `401`          | Authentication required                                                     |                 |
| `403`          | Permission denied; insufficient API-key scope includes meta.required\_scope |                 |
| `404`          | Skill or version not found                                                  |                 |
| `409`          | Name or version conflict                                                    |                 |
| `422`          | Invalid skill bundle, including oversized uploads                           |                 |
| `500`          | The skill could not be saved.                                               |                 |

**Required scope:** `skills.update`. Resource permissions also apply.

### GET `/v2/skills/{skill_id}/versions/{version}`

Get Skill Version

| Parameter  | Location                                                                    | Required | Type    |
| ---------- | --------------------------------------------------------------------------- | -------- | ------- |
| `skill_id` | path                                                                        | Yes      | string  |
| `version`  | path                                                                        | Yes      | integer |
| Status     | Response                                                                    |          |         |
| ---        | ---                                                                         |          |         |
| `200`      | Successful Response                                                         |          |         |
| `4XX`      | Other client errors use the same public error envelope                      |          |         |
| `400`      | Invalid request parameters                                                  |          |         |
| `401`      | Authentication required                                                     |          |         |
| `403`      | Permission denied; insufficient API-key scope includes meta.required\_scope |          |         |
| `404`      | Skill or version not found                                                  |          |         |

**Required scope:** `skills.read`. Resource permissions also apply.

## Related resources

[API Versions and Compatibility](https://docs.stackai.com/technical-reference/apis-and-mcp/api-versions-and-compatibility.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/technical-reference/apis-and-mcp/rest-endpoint-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
