Orlo Platform API

Application and agent integrations at api.useorlo.com. Authenticate with a runtime key scoped to one organization. Configure people-only actions in the Orlo console. Read the workflow guides at docs.useorlo.com/engineers.

Version 0.2.0 Base URL: https://api.useorlo.com

Authentication

runtimeKey

Type: HTTP bearer

Runtime key created by an admin in Settings → Keys. Each operation lists its required scope.

Find an endpoint

104 endpoints

Tasks

GET/v1/tasks

List tasks

Required scope: tasks.read.

Parameters

Name	Location	Type	Description
`archived`	query	`string`	— Example: `exclude`

Responses

200Task list

application/json

object

Fields 10

Field	Type	Description
`tasks`	`array<object>`	—
`tasks[].id`	`string (uuid)`	—
`tasks[].name`	`string`	—
`tasks[].current_version_id`	`string (uuid) \| null`	—
`tasks[].config`	`object`	—
`tasks[].created_at`	`string (date-time)`	—
`tasks[].updated_at`	`string (date-time)`	—
`tasks[].archived_at`	`string (date-time) \| null`	—
`tasks[].current_version_number`	`integer \| null`	—
`tasks[].current_description`	`string \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "tasks": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "current_version_id": "11111111-1111-4111-8111-111111111111",
      "created_at": "2026-10-14T12:00:00Z",
      "updated_at": "2026-10-14T12:00:00Z",
      "archived_at": "2026-10-14T12:00:00Z",
      "current_version_number": 0,
      "current_description": "string"
    }
  ]
}

POST/v1/tasks

Create a task and first task version

Required scope: tasks.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 17

Field	Type	Description
`name`Required	`string`	—
`description`	`string`	—
`input_schema`	`object`	—
`output_schema`	`object`	—
`examples`	`array<object>`	—
`validation_config`	`object`	—
`prompt_template`	`string`	—
`config`	`object`	Task-level settings. On update, retain other config values; this field replaces the object. Response reuse applies to live requests immediately.
`config.response_cache`	`object`	—
`config.response_cache.enabled`	`boolean`	Opt into eligible exact-response reuse for up to five minutes. Prompt releases only, temperature 0–0.1, without sources, adapters or consensus. Default: false.
`config.release_policy`	`object`	—
`config.release_policy.version`Required	`integer`	Allowed: 1.
`config.release_policy.mode`Required	`string`	Allowed: "advisory", "required".
`config.release_policy.minimum_samples`Required	`integer`	Minimum: 2. Maximum: 100000.
`config.release_policy.confidence`Required	`number`	Minimum: 0.9. Maximum: 0.999.
`config.release_policy.max_score_drop`Required	`number`	Minimum: 0. Maximum: 1.
`skill_version_ids`	`array<string (uuid)>`	Published skill version ids to pin, in order. Omit on update to keep the previous references; an empty array removes them.

Nested fields marked required are required when their parent object is present.

Example

{
  "name": "Support ticket routing",
  "description": "Route incoming support tickets.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "string"
      }
    },
    "required": [
      "ticket"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "category": {
        "type": "string"
      }
    }
  },
  "prompt_template": "Classify this ticket: {{ticket}}",
  "examples": [
    {
      "input": {
        "ticket": "I cannot sign in"
      },
      "expected_output": {
        "category": "account_access"
      }
    }
  ]
}

Responses

201Task created

application/json

object

Fields 4

Field	Type	Description
`id`	`string (uuid)`	—
`name`	`string`	—
`version`	`object`	—
`created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "created_at": "2026-10-14T12:00:00Z"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/tasks/{id}

Get one task

Required scope: tasks.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Task detail

application/json

object

Fields 6

Field	Type	Description
`id`	`string (uuid)`	—
`name`	`string`	—
`config`	`object`	—
`created_at`	`string (date-time)`	—
`updated_at`	`string (date-time)`	—
`current_version`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "created_at": "2026-10-14T12:00:00Z",
  "updated_at": "2026-10-14T12:00:00Z"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

PUT/v1/tasks/{id}

Update a task by creating a new task version

Required scope: tasks.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 17

Field	Type	Description
`description`	`string`	—
`input_schema`	`object`	—
`output_schema`	`object`	—
`examples`	`array<object>`	—
`validation_config`	`object`	—
`prompt_template`	`string`	—
`config`	`object`	Task-level settings. On update, retain other config values; this field replaces the object. Response reuse applies to live requests immediately.
`config.response_cache`	`object`	—
`config.response_cache.enabled`	`boolean`	Opt into eligible exact-response reuse for up to five minutes. Prompt releases only, temperature 0–0.1, without sources, adapters or consensus. Default: false.
`config.release_policy`	`object`	—
`config.release_policy.version`Required	`integer`	Allowed: 1.
`config.release_policy.mode`Required	`string`	Allowed: "advisory", "required".
`config.release_policy.minimum_samples`Required	`integer`	Minimum: 2. Maximum: 100000.
`config.release_policy.confidence`Required	`number`	Minimum: 0.9. Maximum: 0.999.
`config.release_policy.max_score_drop`Required	`number`	Minimum: 0. Maximum: 1.
`skill_version_ids`	`array<string (uuid)>`	Published skill version ids to pin, in order. Omit on update to keep the previous references; an empty array removes them.
`expected_version_id`	`string (uuid)`	The task version you edited. A changed version returns TASK_VERSION_CHANGED (409).

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "description": "string",
  "examples": [],
  "prompt_template": "string",
  "config": {
    "response_cache": {
      "enabled": false
    },
    "release_policy": {
      "version": 1,
      "mode": "advisory",
      "minimum_samples": 2,
      "confidence": 0.9,
      "max_score_drop": 0
    }
  },
  "skill_version_ids": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "expected_version_id": "11111111-1111-4111-8111-111111111111"
}

Responses

200Task updated

application/json

object

Fields 2

Field	Type	Description
`id`	`string (uuid)`	—
`version`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

409TASK_VERSION_CHANGED: reload the task and review the latest version before saving.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

PATCH/v1/tasks/{id}

Rename a task without creating a version

Required scope: tasks.write.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 1

Field	Type	Description
`name`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "name": "string"
}

Responses

200Successful response

application/json

object

Fields 4

Field	Type	Description
`task`	`object`	—
`task.id`	`string (uuid)`	—
`task.name`	`string`	—
`task.updated_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "task": {
    "id": "11111111-1111-4111-8111-111111111111",
    "name": "string",
    "updated_at": "2026-10-14T12:00:00Z"
  }
}

GET/v1/tasks/{id}/versions

List task versions

Required scope: tasks.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Versions

application/json

object

Fields 5

Field	Type	Description
`versions`	`array<object>`	—
`versions[].id`	`string (uuid)`	—
`versions[].version`	`integer`	—
`versions[].description`	`string`	—
`versions[].created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "versions": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "version": 0,
      "description": "string",
      "created_at": "2026-10-14T12:00:00Z"
    }
  ]
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/tasks/{id}/preview-impact

Recheck recorded answers against proposed schema or validation rules

Does not call models or test new instructions. Required scope: tasks.write.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 5

Field	Type	Description
`expected_version_id`	`string (uuid)`	—
`sample_size`	`integer`	Default: 25. Minimum: 1. Maximum: 200.
`proposed_changes`Required	`object`	—
`proposed_changes.output_schema`	`object`	—
`proposed_changes.validation_config`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "expected_version_id": "11111111-1111-4111-8111-111111111111",
  "sample_size": 25,
  "proposed_changes": {}
}

Responses

200Successful response

application/json

object

Fields 1

Field	Type	Description
`impact`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/tasks/{id}/lifecycle

What a task has and which lifecycle actions apply

Required scope: tasks.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`

Responses

200OK

application/json

object

Fields 14

Field	Type	Description
`archived_at`	`string (date-time) \| null`	—
`archived_by`	`string \| null`	—
`history`	`object`	—
`history.releases`	`boolean`	—
`history.comparisons`	`boolean`	—
`history.answers`	`boolean`	—
`history.agent_runs`	`boolean`	—
`history.adapters`	`boolean`	—
`busy`	`object`	—
`busy.comparisons_running`	`integer`	—
`busy.agent_runs_open`	`integer`	—
`busy.approvals_waiting`	`integer`	—
`can_delete`	`boolean`	—
`can_archive`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "archived_at": "2026-10-14T12:00:00Z",
  "archived_by": "string",
  "history": {
    "releases": false,
    "comparisons": false,
    "answers": false,
    "agent_runs": false,
    "adapters": false
  },
  "busy": {
    "comparisons_running": 0,
    "agent_runs_open": 0,
    "approvals_waiting": 0
  },
  "can_delete": false,
  "can_archive": false
}

GET/v1/tasks/{id}/model-settings

Task model shortlist and judge

Required scope: tasks.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 9

Field	Type	Description
`judge_model_id`	`string (uuid) \| null`	—
`second_judge_model_id`	`string (uuid) \| null`	—
`dual_judge`	`boolean \| null`	—
`compare_models`	`array<string (uuid)>`	—
`effective`	`object`	—
`effective.judge`	`object \| null`	—
`effective.second_judge`	`object \| null`	—
`effective.dual_judge`	`boolean`	—
`effective.source`	`string`	Allowed: "task", "org", "automatic".

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "judge_model_id": "11111111-1111-4111-8111-111111111111",
  "second_judge_model_id": "11111111-1111-4111-8111-111111111111",
  "dual_judge": false,
  "compare_models": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "effective": {
    "dual_judge": false,
    "source": "task"
  }
}

PUT/v1/tasks/{id}/model-settings

Set task model shortlist and judge

Required scope: tasks.write.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 4

Field	Type	Description
`judge_model_id`	`string (uuid) \| null`	—
`second_judge_model_id`	`string (uuid) \| null`	—
`dual_judge`	`boolean \| null`	—
`compare_models`	`array<string (uuid)>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "judge_model_id": "11111111-1111-4111-8111-111111111111",
  "second_judge_model_id": "11111111-1111-4111-8111-111111111111",
  "dual_judge": false,
  "compare_models": [
    "11111111-1111-4111-8111-111111111111"
  ]
}

Responses

200Successful response

application/json

object

Fields 9

Field	Type	Description
`judge_model_id`	`string (uuid) \| null`	—
`second_judge_model_id`	`string (uuid) \| null`	—
`dual_judge`	`boolean \| null`	—
`compare_models`	`array<string (uuid)>`	—
`effective`	`object`	—
`effective.judge`	`object \| null`	—
`effective.second_judge`	`object \| null`	—
`effective.dual_judge`	`boolean`	—
`effective.source`	`string`	Allowed: "task", "org", "automatic".

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "judge_model_id": "11111111-1111-4111-8111-111111111111",
  "second_judge_model_id": "11111111-1111-4111-8111-111111111111",
  "dual_judge": false,
  "compare_models": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "effective": {
    "dual_judge": false,
    "source": "task"
  }
}

GET/v1/tasks/{id}/versions/{versionId}

One task version

Required scope: tasks.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`versionId`*	path	`string`	— Example: `string`

Responses

200OK

application/json

object

Fields 12

Field	Type	Description
`id`	`string (uuid)`	—
`task_id`	`string (uuid)`	—
`version`	`integer`	—
`description`	`string`	—
`prompt_template`	`string`	—
`input_schema`	`object`	—
`output_schema`	`object`	—
`examples`	`array<object>`	—
`validation_config`	`object`	—
`skill_count`	`integer`	—
`skills`	`array<object>`	—
`created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "task_id": "11111111-1111-4111-8111-111111111111",
  "version": 0,
  "description": "string",
  "prompt_template": "string",
  "examples": [],
  "skill_count": 0,
  "skills": [],
  "created_at": "2026-10-14T12:00:00Z"
}

POST/v1/tasks/{taskId}/documents/reembed

Embed the task’s sources again with the current embedding model

Required scope: documents.write.

Parameters

Name	Location	Type	Description
`taskId`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Responses

200OK

application/json

object

Fields 4

Field	Type	Description
`documents`	`integer`	—
`chunks`	`integer`	—
`embedding_model`	`string`	—
`message`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "documents": 0,
  "chunks": 0,
  "embedding_model": "string",
  "message": "string"
}

202Successful response

application/json

object

Fields 4

Field	Type	Description
`documents`	`integer`	—
`chunks`	`integer`	—
`embedding_model`	`string`	—
`message`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "documents": 0,
  "chunks": 0,
  "embedding_model": "string",
  "message": "string"
}

POST/v1/tasks/{id}/suggest-rules

Draft an output schema from saved expected answers

Required scope: tasks.write. Reads at most 200 expected answers from the task-owned dataset. It does not save a version. Review and save the draft explicitly.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 2

Field	Type	Description
`dataset_id`Required	`string (uuid)`	—
`expected_version_id`Required	`string (uuid)`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "dataset_id": "11111111-1111-4111-8111-111111111111",
  "expected_version_id": "22222222-2222-4222-8222-222222222222"
}

Responses

200Successful response

application/json

object

Fields 8

Field	Type	Description
`output_schema`	`object`	—
`dataset_id`	`string (uuid)`	—
`dataset_version`	`integer`	—
`available_count`	`integer`	—
`limited`	`boolean`	—
`message`	`string`	—
`required_fields`	`array<string>`	—
`example_count`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "output_schema": {
    "type": "object",
    "properties": {
      "decision": {
        "type": "string"
      }
    },
    "required": [
      "decision"
    ]
  },
  "required_fields": [
    "decision"
  ],
  "example_count": 20,
  "dataset_id": "11111111-1111-4111-8111-111111111111",
  "dataset_version": 1,
  "available_count": 20,
  "limited": false,
  "message": "Review the proposed fields and types before saving."
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Datasets

GET/v1/datasets

List datasets

Required scope: datasets.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Dataset list

application/json

object

Fields 14

Field	Type	Description
`datasets`	`array<object>`	—
`datasets[].id`	`string (uuid)`	—
`datasets[].version`	`integer`	—
`datasets[].sample_count`	`integer`	—
`datasets[].created_at`	`string (date-time)`	—
`datasets[].task_id`	`string (uuid)`	—
`datasets[].name`	`string`	—
`datasets[].parent_dataset_id`	`string (uuid) \| null`	—
`datasets[].added_count`	`integer`	—
`datasets[].baseline_count`	`integer`	—
`datasets[].change_kind`	`string`	—
`datasets[].change_mode`	`string`	—
`datasets[].redaction_warning`	`string`	Present on a write when credential-like values changed. Inspect saved examples before comparing models.
`datasets[].redacted_sample_count`	`integer`	Number of new or copied samples changed by credential protection during this write.

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "datasets": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "version": 0,
      "sample_count": 0,
      "created_at": "2026-10-14T12:00:00Z",
      "task_id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "parent_dataset_id": "11111111-1111-4111-8111-111111111111",
      "added_count": 0,
      "baseline_count": 0,
      "change_kind": "string",
      "change_mode": "string",
      "redaction_warning": "string",
      "redacted_sample_count": 0
    }
  ]
}

POST/v1/datasets

Create a dataset

Required scope: datasets.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 7

Field	Type	Description
`task_id`Required	`string (uuid)`	—
`name`Required	`string`	—
`samples`Required	`array<object>`	—
`samples[].input`Required	`object`	—
`samples[].expected_output`Required	`object`	—
`mode`	`string`	Allowed: "append", "replace". Default: "append".
`base_dataset_id`	`string (uuid) \| null`	The latest dataset ID, or null when there is no dataset. Required for replace. A changed baseline returns DATASET_BASE_CHANGED (409).

Nested fields marked required are required when their parent object is present.

Example

{
  "task_id": "22222222-2222-4222-8222-222222222222",
  "name": "Support examples",
  "samples": [
    {
      "input": {
        "ticket": "I cannot sign in"
      },
      "expected_output": {
        "category": "account_access"
      }
    }
  ]
}

Responses

201Dataset created

application/json

object

Fields 13

Field	Type	Description
`id`	`string (uuid)`	—
`version`	`integer`	—
`sample_count`	`integer`	—
`created_at`	`string (date-time)`	—
`task_id`	`string (uuid)`	—
`name`	`string`	—
`parent_dataset_id`	`string (uuid) \| null`	—
`added_count`	`integer`	—
`baseline_count`	`integer`	—
`change_kind`	`string`	—
`change_mode`	`string`	—
`redaction_warning`	`string`	Present on a write when credential-like values changed. Inspect saved examples before comparing models.
`redacted_sample_count`	`integer`	Number of new or copied samples changed by credential protection during this write.

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "version": 0,
  "sample_count": 0,
  "created_at": "2026-10-14T12:00:00Z",
  "task_id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "parent_dataset_id": "11111111-1111-4111-8111-111111111111",
  "added_count": 0,
  "baseline_count": 0,
  "change_kind": "string",
  "change_mode": "string",
  "redaction_warning": "string",
  "redacted_sample_count": 0
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

409DATASET_BASE_CHANGED: reload the latest dataset before trying again.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

503EXAMPLE_PROTECTION_UNAVAILABLE: organization credentials could not be checked. No changes were saved.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/datasets/{id}

Get one dataset

Required scope: datasets.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`
`limit`	query	`integer`	Omit to return all samples; use a limit for cursor pagination. Example: `1`
`after`	query	`string (uuid)`	Sample cursor from next_cursor; requires limit. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Successful response

application/json

object & object

Fields 21

Field	Type	Description
`id`	`string (uuid)`	—
`version`	`integer`	—
`sample_count`	`integer`	—
`created_at`	`string (date-time)`	—
`task_id`	`string (uuid)`	—
`name`	`string`	—
`parent_dataset_id`	`string (uuid) \| null`	—
`added_count`	`integer`	—
`baseline_count`	`integer`	—
`change_kind`	`string`	—
`change_mode`	`string`	—
`redaction_warning`	`string`	Present on a write when credential-like values changed. Inspect saved examples before comparing models.
`redacted_sample_count`	`integer`	Number of new or copied samples changed by credential protection during this write.
`samples`	`array<object>`	—
`samples[].id`	`string (uuid)`	—
`samples[].input`	`object`	—
`samples[].expected_output`	`object`	—
`samples[].trace_sample_id`	`string (uuid) \| null`	—
`samples[].provenance`	`object`	—
`samples[].created_at`	`string (date-time)`	—
`next_cursor`	`string (uuid) \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "version": 0,
  "sample_count": 0,
  "created_at": "2026-10-14T12:00:00Z",
  "task_id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "parent_dataset_id": "11111111-1111-4111-8111-111111111111",
  "added_count": 0,
  "baseline_count": 0,
  "change_kind": "string",
  "change_mode": "string",
  "redaction_warning": "string",
  "redacted_sample_count": 0,
  "samples": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "trace_sample_id": "11111111-1111-4111-8111-111111111111",
      "created_at": "2026-10-14T12:00:00Z"
    }
  ],
  "next_cursor": "11111111-1111-4111-8111-111111111111"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Evaluations

GET/v1/evaluations/templates

List evaluation templates

Required scope: evaluations.read.

Responses

200Template list

application/json

object

Fields 4

Field	Type	Description
`templates`	`array<object>`	—
`templates[].key`	`string`	—
`templates[].name`	`string`	—
`templates[].description`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "templates": [
    {
      "key": "string",
      "name": "string",
      "description": "string"
    }
  ]
}

GET/v1/evaluations/templates/{key}

Get one evaluation template

Required scope: evaluations.read.

Parameters

Name	Location	Type	Description
`key`*	path	`string`	— Example: `string`

Responses

200Template detail

application/json

object

Fields 16

Field	Type	Description
`name`	`string`	—
`description`	`string`	—
`budget`	`object`	—
`budget.max_tokens`	`integer`	—
`budget.max_cost_usd`	`number`	—
`budget.max_runtime_minutes`	`number`	—
`scoring`	`object`	—
`scoring.schema_weight`	`number`	—
`scoring.semantic_weight`	`number`	—
`scoring.judge_weight`	`number`	—
`scoring.state_change_weight`	`number`	—
`rubric_criteria`	`array<object>`	—
`rubric_criteria[].name`	`string`	—
`rubric_criteria[].description`	`string`	—
`rubric_criteria[].weight`	`number`	—
`config`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "name": "string",
  "description": "string",
  "budget": {
    "max_tokens": 0,
    "max_cost_usd": 0,
    "max_runtime_minutes": 0
  },
  "scoring": {
    "schema_weight": 0,
    "semantic_weight": 0,
    "judge_weight": 0,
    "state_change_weight": 0
  },
  "rubric_criteria": [
    {
      "name": "string",
      "description": "string",
      "weight": 0
    }
  ]
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/evaluations/run

Queue an evaluation run

Required scope: evaluations.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

any | any

Fields 23

Field	Type	Description
`task_id`Required	`string (uuid)`	—
`dataset_id`Required	`string (uuid)`	—
`rubric_id`	`string (uuid)`	—
`models`	`array<string (uuid)>`	—
`extends`	`string`	—
`budget`	`object`	—
`scoring`	`object`	—
`config`	`object`	—
`config.retrieval_diagnostic`	`boolean`	Requires a release test with two candidates using the same explicit model and task version, one with sources and one without; no deployment overrides. Both judges receive the same references.
`expected_task_version_id`	`string (uuid)`	—
`candidates`	`array<object>`	—
`candidates[].key`Required	`string`	—
`candidates[].model_id`Required	`string (uuid)`	—
`candidates[].task_version_id`	`string (uuid)`	—
`candidates[].deployment_id`	`string (uuid)`	—
`candidates[].include_retrieval_context`	`boolean`	—
`release_test`	`object`	—
`release_test.version`Required	`integer`	Allowed: 1.
`release_test.method`Required	`string`	Allowed: "paired_fixed".
`release_test.baseline_candidate_key`Required	`string`	—
`release_test.sample_count`Required	`integer`	Minimum: 2. Maximum: 100000.
`release_test.confidence`Required	`number`	Minimum: 0.9. Maximum: 0.999.
`release_test.max_score_drop`Required	`number`	Minimum: 0. Maximum: 1.

Nested fields marked required are required when their parent object is present.

Example

{
  "task_id": "22222222-2222-4222-8222-222222222222",
  "dataset_id": "33333333-3333-4333-8333-333333333333",
  "models": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "expected_task_version_id": "33333333-3333-4333-8333-333333333333"
}

Responses

202Evaluation queued

application/json

object

Fields 15

Field	Type	Description
`id`	`string (uuid)`	—
`status`	`string`	—
`template`	`string \| null`	—
`rubric_id`	`string (uuid) \| null`	—
`budget`	`object`	—
`budget.max_tokens`	`integer`	—
`budget.max_cost_usd`	`number`	—
`budget.max_runtime_minutes`	`number`	—
`scoring`	`object`	—
`scoring.schema_weight`	`number`	—
`scoring.semantic_weight`	`number`	—
`scoring.judge_weight`	`number`	—
`scoring.state_change_weight`	`number`	—
`uses_sources`	`boolean`	—
`poll_url`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "template": null,
  "rubric_id": null,
  "budget": {
    "max_tokens": 1000000,
    "max_cost_usd": 100,
    "max_runtime_minutes": 60
  },
  "scoring": {
    "schema_weight": 0.3,
    "semantic_weight": 0.3,
    "judge_weight": 0.4,
    "state_change_weight": 0
  },
  "uses_sources": false,
  "poll_url": "/v1/evaluations/11111111-1111-4111-8111-111111111111"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/evaluations

List evaluations

Required scope: evaluations.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Evaluations

application/json

object

Fields 65

Field	Type	Description
`evaluations`	`array<object>`	—
`evaluations[].id`	`string (uuid)`	—
`evaluations[].task_id`	`string (uuid)`	—
`evaluations[].dataset_id`	`string (uuid)`	—
`evaluations[].task_version_id`	`string (uuid)`	—
`evaluations[].rubric_id`	`string (uuid)`	—
`evaluations[].models`	`array<string (uuid)>`	—
`evaluations[].status`	`string`	—
`evaluations[].error_details`	`object \| null`	—
`evaluations[].uses_sources`	`boolean`	—
`evaluations[].judge`	`object \| null`	—
`evaluations[].budget`	`object`	—
`evaluations[].results`	`array<object>`	—
`evaluations[].results[].model`	`string`	—
`evaluations[].results[].model_id`	`string`	—
`evaluations[].results[].final_score`	`number \| null`	—
`evaluations[].results[].ci_lower`	`number \| null`	—
`evaluations[].results[].ci_upper`	`number \| null`	—
`evaluations[].results[].schema_score`	`number \| null`	—
`evaluations[].results[].semantic_score`	`number \| null`	—
`evaluations[].results[].judge_score`	`number \| null`	—
`evaluations[].results[].latency_p95_ms`	`number \| null`	—
`evaluations[].results[].cost_estimate`	`number \| null`	—
`evaluations[].results[].sample_count`	`integer`	—
`evaluations[].results[].failure_count`	`integer`	—
`evaluations[].results[].eliminated`	`boolean`	—
`evaluations[].results[].grader_scores`	`object`	—
`evaluations[].results[].system_note`	`string \| null`	—
`evaluations[].results[].candidate_id`	`string (uuid)`	—
`evaluations[].results[].candidate_key`	`string`	—
`evaluations[].results[].release_test`	`object`	—
`evaluations[].results[].release_test.verdict`	`string`	Allowed: "passed", "regressed", "inconclusive", "invalid".
`evaluations[].results[].release_test.paired_count`	`integer`	—
`evaluations[].results[].release_test.planned_count`	`integer`	—
`evaluations[].results[].release_test.mean_difference`	`number \| null`	—
`evaluations[].results[].release_test.lower_bound`	`number \| null`	—
`evaluations[].results[].release_test.upper_bound`	`number \| null`	—
`evaluations[].results[].release_test.interval_method`	`string`	—
`evaluations[].results[].release_test.confidence`	`number`	—
`evaluations[].results[].release_test.max_score_drop`	`number`	—
`evaluations[].results[].release_test.version`	`integer`	Allowed: 1.
`evaluations[].results[].release_test.reason`	`string`	—
`evaluations[].results[].release_test.family_size`	`integer`	—
`evaluations[].results[].release_test.standard_failures`	`integer`	—
`evaluations[].recommendation`	`object \| null`	—
`evaluations[].dataset`	`object`	—
`evaluations[].task_version`	`object`	—
`evaluations[].created_at`	`string (date-time)`	—
`evaluations[].created_by`	`string \| null`	—
`evaluations[].completed_at`	`string (date-time) \| null`	—
`evaluations[].release_test`	`object`	—
`evaluations[].release_test.version`Required	`integer`	Allowed: 1.
`evaluations[].release_test.method`Required	`string`	Allowed: "paired_fixed".
`evaluations[].release_test.baseline_candidate_key`Required	`string`	—
`evaluations[].release_test.sample_count`Required	`integer`	Minimum: 2. Maximum: 100000.
`evaluations[].release_test.confidence`Required	`number`	Minimum: 0.9. Maximum: 0.999.
`evaluations[].release_test.max_score_drop`Required	`number`	Minimum: 0. Maximum: 1.
`evaluations[].candidates`	`array<object>`	—
`evaluations[].candidates[].id`	`string (uuid)`	—
`evaluations[].candidates[].candidate_key`	`string`	—
`evaluations[].candidates[].model_id`	`string (uuid)`	—
`evaluations[].candidates[].model`	`string`	—
`evaluations[].candidates[].task_version_id`	`string (uuid)`	—
`evaluations[].candidates[].include_retrieval_context`	`boolean`	—
`evaluations[].candidates[].specification_hash`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "evaluations": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "task_id": "11111111-1111-4111-8111-111111111111",
      "dataset_id": "11111111-1111-4111-8111-111111111111",
      "task_version_id": "11111111-1111-4111-8111-111111111111",
      "rubric_id": "11111111-1111-4111-8111-111111111111",
      "models": [
        "11111111-1111-4111-8111-111111111111"
      ],
      "status": "string",
      "uses_sources": false,
      "results": [
        {
          "model": "string",
          "model_id": "string",
          "final_score": 0,
          "ci_lower": 0,
          "ci_upper": 0,
          "schema_score": 0,
          "semantic_score": 0,
          "judge_score": 0,
          "latency_p95_ms": 0,
          "cost_estimate": 0,
          "sample_count": 0,
          "failure_count": 0,
          "eliminated": false,
          "system_note": "string",
          "candidate_id": "11111111-1111-4111-8111-111111111111",
          "candidate_key": "string",
          "release_test": {
            "verdict": "passed",
            "paired_count": 0,
            "planned_count": 0,
            "mean_difference": 0,
            "lower_bound": 0,
            "upper_bound": 0,
            "interval_method": "string",
            "confidence": 0,
            "max_score_drop": 0,
            "version": 1,
            "reason": "string",
            "family_size": 0,
            "standard_failures": 0
          }
        }
      ],
      "created_at": "2026-10-14T12:00:00Z",
      "created_by": "string",
      "completed_at": "2026-10-14T12:00:00Z",
      "release_test": {
        "version": 1,
        "method": "paired_fixed",
        "baseline_candidate_key": "string",
        "sample_count": 2,
        "confidence": 0.9,
        "max_score_drop": 0
      },
      "candidates": [
        {
          "id": "11111111-1111-4111-8111-111111111111",
          "candidate_key": "string",
          "model_id": "11111111-1111-4111-8111-111111111111",
          "model": "string",
          "task_version_id": "11111111-1111-4111-8111-111111111111",
          "include_retrieval_context": false,
          "specification_hash": "string"
        }
      ]
    }
  ]
}

GET/v1/evaluations/{id}

Get evaluation result

Required scope: evaluations.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Evaluation detail

application/json

object

Fields 64

Field	Type	Description
`id`	`string (uuid)`	—
`task_id`	`string (uuid)`	—
`dataset_id`	`string (uuid)`	—
`task_version_id`	`string (uuid)`	—
`rubric_id`	`string (uuid)`	—
`models`	`array<string (uuid)>`	—
`status`	`string`	—
`error_details`	`object \| null`	—
`uses_sources`	`boolean`	—
`judge`	`object \| null`	—
`budget`	`object`	—
`results`	`array<object>`	—
`results[].model`	`string`	—
`results[].model_id`	`string`	—
`results[].final_score`	`number \| null`	—
`results[].ci_lower`	`number \| null`	—
`results[].ci_upper`	`number \| null`	—
`results[].schema_score`	`number \| null`	—
`results[].semantic_score`	`number \| null`	—
`results[].judge_score`	`number \| null`	—
`results[].latency_p95_ms`	`number \| null`	—
`results[].cost_estimate`	`number \| null`	—
`results[].sample_count`	`integer`	—
`results[].failure_count`	`integer`	—
`results[].eliminated`	`boolean`	—
`results[].grader_scores`	`object`	—
`results[].system_note`	`string \| null`	—
`results[].candidate_id`	`string (uuid)`	—
`results[].candidate_key`	`string`	—
`results[].release_test`	`object`	—
`results[].release_test.verdict`	`string`	Allowed: "passed", "regressed", "inconclusive", "invalid".
`results[].release_test.paired_count`	`integer`	—
`results[].release_test.planned_count`	`integer`	—
`results[].release_test.mean_difference`	`number \| null`	—
`results[].release_test.lower_bound`	`number \| null`	—
`results[].release_test.upper_bound`	`number \| null`	—
`results[].release_test.interval_method`	`string`	—
`results[].release_test.confidence`	`number`	—
`results[].release_test.max_score_drop`	`number`	—
`results[].release_test.version`	`integer`	Allowed: 1.
`results[].release_test.reason`	`string`	—
`results[].release_test.family_size`	`integer`	—
`results[].release_test.standard_failures`	`integer`	—
`recommendation`	`object \| null`	—
`dataset`	`object`	—
`task_version`	`object`	—
`created_at`	`string (date-time)`	—
`created_by`	`string \| null`	—
`completed_at`	`string (date-time) \| null`	—
`release_test`	`object`	—
`release_test.version`Required	`integer`	Allowed: 1.
`release_test.method`Required	`string`	Allowed: "paired_fixed".
`release_test.baseline_candidate_key`Required	`string`	—
`release_test.sample_count`Required	`integer`	Minimum: 2. Maximum: 100000.
`release_test.confidence`Required	`number`	Minimum: 0.9. Maximum: 0.999.
`release_test.max_score_drop`Required	`number`	Minimum: 0. Maximum: 1.
`candidates`	`array<object>`	—
`candidates[].id`	`string (uuid)`	—
`candidates[].candidate_key`	`string`	—
`candidates[].model_id`	`string (uuid)`	—
`candidates[].model`	`string`	—
`candidates[].task_version_id`	`string (uuid)`	—
`candidates[].include_retrieval_context`	`boolean`	—
`candidates[].specification_hash`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "task_id": "11111111-1111-4111-8111-111111111111",
  "dataset_id": "11111111-1111-4111-8111-111111111111",
  "task_version_id": "11111111-1111-4111-8111-111111111111",
  "rubric_id": "11111111-1111-4111-8111-111111111111",
  "models": [
    "11111111-1111-4111-8111-111111111111"
  ],
  "status": "string",
  "uses_sources": false,
  "results": [
    {
      "model": "string",
      "model_id": "string",
      "final_score": 0,
      "ci_lower": 0,
      "ci_upper": 0,
      "schema_score": 0,
      "semantic_score": 0,
      "judge_score": 0,
      "latency_p95_ms": 0,
      "cost_estimate": 0,
      "sample_count": 0,
      "failure_count": 0,
      "eliminated": false,
      "system_note": "string",
      "candidate_id": "11111111-1111-4111-8111-111111111111",
      "candidate_key": "string",
      "release_test": {
        "verdict": "passed",
        "paired_count": 0,
        "planned_count": 0,
        "mean_difference": 0,
        "lower_bound": 0,
        "upper_bound": 0,
        "interval_method": "string",
        "confidence": 0,
        "max_score_drop": 0,
        "version": 1,
        "reason": "string",
        "family_size": 0,
        "standard_failures": 0
      }
    }
  ],
  "created_at": "2026-10-14T12:00:00Z",
  "created_by": "string",
  "completed_at": "2026-10-14T12:00:00Z",
  "release_test": {
    "version": 1,
    "method": "paired_fixed",
    "baseline_candidate_key": "string",
    "sample_count": 2,
    "confidence": 0.9,
    "max_score_drop": 0
  },
  "candidates": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "candidate_key": "string",
      "model_id": "11111111-1111-4111-8111-111111111111",
      "model": "string",
      "task_version_id": "11111111-1111-4111-8111-111111111111",
      "include_retrieval_context": false,
      "specification_hash": "string"
    }
  ]
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/evaluations/check

Check comparison readiness using recorded model and key availability

This preflight uses saved availability and configuration. It does not make fresh provider inference requests or guarantee a later run will succeed.

Required scope: evaluations.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

any | any

Fields 20

Field	Type	Description
`task_id`Required	`string (uuid)`	—
`models`	`array<string (uuid)>`	—
`extends`	`string`	—
`scoring`	`object`	—
`config`	`object`	—
`config.retrieval_diagnostic`	`boolean`	Requires a release test with two candidates using the same explicit model and task version, one with sources and one without; no deployment overrides. Both judges receive the same references.
`expected_task_version_id`	`string (uuid)`	—
`candidates`	`array<object>`	—
`candidates[].key`Required	`string`	—
`candidates[].model_id`Required	`string (uuid)`	—
`candidates[].task_version_id`	`string (uuid)`	—
`candidates[].deployment_id`	`string (uuid)`	—
`candidates[].include_retrieval_context`	`boolean`	—
`release_test`	`object`	—
`release_test.version`Required	`integer`	Allowed: 1.
`release_test.method`Required	`string`	Allowed: "paired_fixed".
`release_test.baseline_candidate_key`Required	`string`	—
`release_test.sample_count`Required	`integer`	Minimum: 2. Maximum: 100000.
`release_test.confidence`Required	`number`	Minimum: 0.9. Maximum: 0.999.
`release_test.max_score_drop`Required	`number`	Minimum: 0. Maximum: 1.

Nested fields marked required are required when their parent object is present.

Responses

200Successful response

application/json

object

Fields 24

Field	Type	Description
`ready`	`boolean`	—
`error`	`string`	—
`candidates`	`array<object>`	—
`candidates[].id`	`string (uuid)`	—
`candidates[].name`	`string`	—
`candidates[].provider`	`string`	—
`candidates[].availability`	`object`	—
`candidates[].availability.status`	`string`	Allowed: "missing_key", "key_rejected", "unverified", "listed", "not_listed", "retired".
`candidates[].availability.label`	`string`	—
`candidates[].availability.message`	`string`	—
`candidates[].availability.selectable`	`boolean`	—
`candidates[].availability.checked_at`	`string (date-time) \| null`	—
`judges`	`array<object>`	—
`judges[].id`	`string (uuid)`	—
`judges[].name`	`string`	—
`judges[].provider`	`string`	—
`judges[].availability`	`object`	—
`judges[].availability.status`	`string`	Allowed: "missing_key", "key_rejected", "unverified", "listed", "not_listed", "retired".
`judges[].availability.label`	`string`	—
`judges[].availability.message`	`string`	—
`judges[].availability.selectable`	`boolean`	—
`judges[].availability.checked_at`	`string (date-time) \| null`	—
`issues`	`array<string>`	—
`config`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "ready": false,
  "error": "string",
  "candidates": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "provider": "string",
      "availability": {
        "status": "missing_key",
        "label": "string",
        "message": "string",
        "selectable": false,
        "checked_at": "2026-10-14T12:00:00Z"
      }
    }
  ],
  "judges": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "provider": "string",
      "availability": {
        "status": "missing_key",
        "label": "string",
        "message": "string",
        "selectable": false,
        "checked_at": "2026-10-14T12:00:00Z"
      }
    }
  ],
  "issues": [
    "string"
  ]
}

GET/v1/evaluations/defaults

Default comparison budget

Required scope: evaluations.read.

Responses

200Successful response

application/json

object

Fields 1

Field	Type	Description
`budget`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{}

GET/v1/evaluations/{id}/status

Progress of a comparison

Required scope: evaluations.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 5

Field	Type	Description
`id`	`string (uuid)`	—
`status`	`string`	—
`budget`	`object`	—
`error_details`	`object \| null`	—
`completed_at`	`string (date-time) \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "string",
  "completed_at": "2026-10-14T12:00:00Z"
}

POST/v1/evaluations/{id}/cancel

Cancel a running comparison

Required scope: evaluations.write.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Responses

200OK

application/json

object

Fields 4

Field	Type	Description
`evaluation`	`object`	—
`evaluation.id`	`string (uuid)`	—
`evaluation.status`	`string`	—
`evaluation.task_id`	`string (uuid)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "evaluation": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "string",
    "task_id": "11111111-1111-4111-8111-111111111111"
  }
}

POST/v1/evaluations/{id}/retry

Retry a failed comparison

Required scope: evaluations.write.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

object

Fields 1

Field	Type	Description
`budget`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{}

Responses

200Successful response

application/json

object

Fields 3

Field	Type	Description
`evaluation`	`object`	—
`evaluation.id`	`string (uuid)`	—
`evaluation.status`	`string`	Allowed: "pending".

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "evaluation": {
    "id": "11111111-1111-4111-8111-111111111111",
    "status": "pending"
  }
}

GET/v1/evaluations/{id}/examples

Per-example answers and scores behind a comparison

Required scope: evaluations.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`sort`	query	`string`	— Example: `disagreement`
`model_ids`	query	`string`	Comma-separated model UUIDs. Example: `string`
`limit`	query	`integer`	— Example: `20`
`offset`	query	`integer`	— Example: `0`
`candidate_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`region_group`	query	`string`	— Example: `string`
`region_metric`	query	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 9

Field	Type	Description
`examples`	`array<object>`	—
`examples[].sample_id`	`string (uuid)`	—
`examples[].input`	`any`	—
`examples[].expected_output`	`any`	—
`examples[].provenance`	`object`	—
`examples[].spread`	`number`	—
`examples[].results`	`array<object>`	—
`total`	`integer`	—
`sort`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "examples": [
    {
      "sample_id": "11111111-1111-4111-8111-111111111111",
      "spread": 0,
      "results": []
    }
  ],
  "total": 0,
  "sort": "string"
}

GET/v1/evaluations/{id}/retrieval

Inspect source retrieval separately from answer quality

Required scope: evaluations.read. Returns up to 10 examples and 6 bounded passage previews each. Matched passages do not establish relevance. Older records may be unavailable.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`candidate_id`*	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`after`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Successful response

application/json

object

Fields 54

Field	Type	Description
`candidate`	`object`	—
`candidate.id`	`string (uuid)`	—
`candidate.candidate_key`	`string`	—
`candidate.include_retrieval_context`	`boolean`	—
`candidate.source_set_id`	`string (uuid) \| null`	—
`candidate.model`	`string`	—
`candidate.summary`	`object \| null`	—
`candidate.summary.planned`	`integer`	—
`candidate.summary.checked`	`integer`	—
`candidate.summary.matched`	`integer`	—
`candidate.summary.no_match`	`integer`	—
`candidate.summary.skipped`	`integer`	—
`candidate.summary.shared_judge_reference`	`boolean`	—
`items`	`array<object>`	—
`items[].sample_id`	`string (uuid)`	—
`items[].state`	`string`	Allowed: "disabled", "unrecorded", "skipped", "no_match", "matched".
`items[].query`	`string \| null`	—
`items[].mode`	`string \| null`	—
`items[].notes`	`array<string>`	—
`items[].passage_count`	`integer`	—
`items[].passages`	`array<object>`	—
`items[].passages[].source_id`	`string \| null`	—
`items[].passages[].chunk_id`	`string \| null`	—
`items[].passages[].name`	`string \| null`	—
`items[].passages[].page`	`integer \| null`	—
`items[].passages[].text`	`string`	—
`items[].passages[].truncated`	`boolean`	—
`items[].passages[].structure`	`object \| null`	Recorded heading_path, page/section ranges, kind, and optional ingestion receipt. A receipt includes document_sha256, chunk_sha256, passage order, parser/chunker identities, and structure_origin. Arbitrary upload metadata is excluded.
`items[].passages[].structure.heading_path`	`array<string>`	—
`items[].passages[].structure.page_start`	`integer \| null`	Minimum: 0.
`items[].passages[].structure.page_end`	`integer \| null`	Minimum: 0.
`items[].passages[].structure.section_line_start`	`integer \| null`	Minimum: 0.
`items[].passages[].structure.section_line_end`	`integer \| null`	Minimum: 0.
`items[].passages[].structure.kind`	`string`	Allowed: "text", "table".
`items[].passages[].structure.ingestion`	`object \| null`	—
`items[].passages[].structure.ingestion.version`	`integer`	Allowed: 1.
`items[].passages[].structure.ingestion.source_kind`	`string \| null`	Allowed: "inline", "pdf", "prechunked".
`items[].passages[].structure.ingestion.document_sha256`	`string \| null`	—
`items[].passages[].structure.ingestion.chunk_sha256`	`string \| null`	—
`items[].passages[].structure.ingestion.chunk_index`	`integer \| null`	Minimum: 0.
`items[].passages[].structure.ingestion.chunk_count`	`integer \| null`	Minimum: 0.
`items[].passages[].structure.ingestion.parser`	`object`	—
`items[].passages[].structure.ingestion.parser.name`	`string`	—
`items[].passages[].structure.ingestion.parser.version`	`string`	—
`items[].passages[].structure.ingestion.chunker`	`object`	—
`items[].passages[].structure.ingestion.chunker.name`	`string`	—
`items[].passages[].structure.ingestion.chunker.version`	`string`	—
`items[].passages[].structure.ingestion.structure_origin`	`string`	Allowed: "parsed", "supplied".
`items[].passages_limited`	`boolean`	—
`items[].answer_failed`	`boolean`	—
`items[].answer_score`	`number \| null`	—
`items[].standard_passed`	`boolean \| null`	—
`next_cursor`	`string (uuid) \| null`	—
`note`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "candidate": {
    "id": "11111111-1111-4111-8111-111111111111",
    "candidate_key": "sources-on",
    "include_retrieval_context": true,
    "source_set_id": "22222222-2222-4222-8222-222222222222",
    "model": "Example model",
    "summary": {
      "planned": 40,
      "checked": 40,
      "matched": 40,
      "no_match": 0,
      "skipped": 0,
      "shared_judge_reference": true
    }
  },
  "items": [
    {
      "sample_id": "33333333-3333-4333-8333-333333333333",
      "state": "matched",
      "query": "Refund policy",
      "mode": "full",
      "notes": [],
      "passage_count": 1,
      "passages": [
        {
          "source_id": "44444444-4444-4444-8444-444444444444",
          "chunk_id": "55555555-5555-4555-8555-555555555555",
          "name": "Policy.md",
          "page": null,
          "text": "Refund requests require review.",
          "truncated": false,
          "structure": {
            "heading_path": [
              "Policy",
              "Refunds"
            ],
            "page_start": null,
            "page_end": null,
            "section_line_start": 2,
            "section_line_end": 3,
            "kind": "text",
            "ingestion": null
          }
        }
      ],
      "passages_limited": false,
      "answer_failed": false,
      "answer_score": 1,
      "standard_passed": true
    }
  ],
  "next_cursor": null,
  "note": "Matched passages show what search supplied, not proof of relevance."
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/evaluations/{id}/regions

Read paired regression regions for a candidate

Required scope: evaluations.read. Descriptive diagnostics do not alter the release verdict.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`candidate_id`*	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Successful response

application/json

object

Fields 23

Field	Type	Description
`version`	`integer`	—
`baseline_candidate_id`	`string (uuid)`	—
`candidate_id`	`string (uuid)`	—
`groups`	`array<object>`	—
`groups[].id`	`string`	—
`groups[].label`	`string`	—
`metrics`	`array<object>`	—
`metrics[].id`	`string`	—
`metrics[].label`	`string`	—
`cells`	`array<object>`	—
`cells[].group`	`string`	—
`cells[].metric`	`string`	—
`cells[].examples`	`integer`	—
`cells[].paired`	`integer`	—
`cells[].missing`	`integer`	—
`cells[].difference`	`number \| null`	—
`cells[].sparse`	`boolean`	—
`cells[].baseline`	`number \| null`	—
`cells[].candidate`	`number \| null`	—
`cells[].worse`	`integer`	—
`cells[].better`	`integer`	—
`cells[].unchanged`	`integer`	—
`sparse_below`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "version": 0,
  "baseline_candidate_id": "11111111-1111-4111-8111-111111111111",
  "candidate_id": "11111111-1111-4111-8111-111111111111",
  "groups": [
    {
      "id": "string",
      "label": "string"
    }
  ],
  "metrics": [
    {
      "id": "string",
      "label": "string"
    }
  ],
  "cells": [
    {
      "group": "string",
      "metric": "string",
      "examples": 0,
      "paired": 0,
      "missing": 0,
      "difference": 0,
      "sparse": false,
      "baseline": 0,
      "candidate": 0,
      "worse": 0,
      "better": 0,
      "unchanged": 0
    }
  ],
  "sparse_below": 0
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Deployments

GET/v1/deployments

List deployments

Required scope: deployments.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Deployment list

application/json

object

Fields 13

Field	Type	Description
`deployments`	`array<object>`	—
`deployments[].id`	`string (uuid)`	—
`deployments[].task_id`	`string (uuid)`	—
`deployments[].task_version_id`	`string (uuid)`	—
`deployments[].model_id`	`string (uuid)`	—
`deployments[].model_name`	`string`	—
`deployments[].strategy`	`string`	—
`deployments[].version`	`integer`	—
`deployments[].active`	`boolean`	—
`deployments[].created_at`	`string (date-time)`	—
`deployments[].created_by`	`string \| null`	—
`deployments[].evaluation_id`	`string (uuid) \| null`	—
`deployments[].config_snapshot`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "deployments": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "task_id": "11111111-1111-4111-8111-111111111111",
      "task_version_id": "11111111-1111-4111-8111-111111111111",
      "model_id": "11111111-1111-4111-8111-111111111111",
      "model_name": "string",
      "strategy": "string",
      "version": 0,
      "active": false,
      "created_at": "2026-10-14T12:00:00Z",
      "created_by": "string",
      "evaluation_id": "11111111-1111-4111-8111-111111111111"
    }
  ]
}

POST/v1/deployments

Create a deployment

Required scope: deployments.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 7

Field	Type	Description
`task_id`Required	`string (uuid)`	—
`task_version_id`Required	`string (uuid)`	—
`model_id`Required	`string (uuid)`	—
`strategy`	`string`	Allowed: "prompt", "rag", "lora".
`adapter_id`	`string (uuid)`	—
`evaluation_id`	`string (uuid)`	Optional comparison evidence. The task version and candidate must match, and the candidate must have produced usable results.
`evaluation_candidate_id`	`string (uuid)`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "task_id": "22222222-2222-4222-8222-222222222222",
  "task_version_id": "33333333-3333-4333-8333-333333333333",
  "model_id": "11111111-1111-4111-8111-111111111111",
  "strategy": "prompt"
}

Responses

201Deployment created

application/json

object

Fields 4

Field	Type	Description
`id`	`string (uuid)`	—
`version`	`integer`	—
`created_at`	`string (date-time)`	—
`created_by`	`string \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "version": 0,
  "created_at": "2026-10-14T12:00:00Z",
  "created_by": "string"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

PUT/v1/deployments/{id}/activate

Activate a deployment

Required scope: deployments.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Deployment activated

application/json

object

Fields 2

Field	Type	Description
`id`	`string (uuid)`	—
`active`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "active": true
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

PUT/v1/deployments/{id}/deactivate

Deactivate a deployment

Required scope: deployments.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Deployment deactivated

application/json

object

Fields 2

Field	Type	Description
`id`	`string (uuid)`	—
`active`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "active": false
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/deployments/{id}

One release

Required scope: deployments.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`

Responses

200OK

application/json

object

Fields 12

Field	Type	Description
`id`	`string (uuid)`	—
`task_id`	`string (uuid)`	—
`task_version_id`	`string (uuid)`	—
`model_id`	`string (uuid)`	—
`model_name`	`string`	—
`strategy`	`string`	—
`version`	`integer`	—
`active`	`boolean`	—
`created_at`	`string (date-time)`	—
`created_by`	`string \| null`	—
`evaluation_id`	`string (uuid) \| null`	—
`config_snapshot`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "task_id": "11111111-1111-4111-8111-111111111111",
  "task_version_id": "11111111-1111-4111-8111-111111111111",
  "model_id": "11111111-1111-4111-8111-111111111111",
  "model_name": "string",
  "strategy": "string",
  "version": 0,
  "active": false,
  "created_at": "2026-10-14T12:00:00Z",
  "created_by": "string",
  "evaluation_id": "11111111-1111-4111-8111-111111111111"
}

Inference

POST/v1/chat/completions

OpenAI-compatible chat completions

Return a complete checked answer using released task instructions and pinned skills. Caller system, developer and tool messages are treated as data. Streaming is not supported.

Required scope: inference.run.

Parameters

Name	Location	Type	Description
`X-Orlo-Task-Id`*	header	`string (uuid)`	Trusted task context used on the OpenAI-compatible chat path. Example: `11111111-1111-4111-8111-111111111111`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 8

Field	Type	Description
`model`	`string`	Accepted for client compatibility. The task release and routing settings select the model.
`messages`Required	`array<object>`	Conversation data. Released task instructions and pinned skills always apply. Caller system, developer and tool messages become JSON-wrapped user data.
`messages[].role`Required	`string`	Allowed: "system", "developer", "user", "assistant", "tool".
`messages[].content`Required	`string`	—
`temperature`	`number`	Overrides the release temperature. When neither specifies one, Orlo requests 0, matching comparisons. Minimum: 0. Maximum: 2.
`max_tokens`	`integer`	Minimum: 1. Maximum: 16384.
`max_completion_tokens`	`integer`	Output-token limit; takes precedence over max_tokens. Minimum: 1. Maximum: 16384.
`stream`	`boolean`	Only complete answers are supported. true returns INVALID_INPUT (400) before a model call. Allowed: false.

Nested fields marked required are required when their parent object is present.

Example

{
  "messages": [
    {
      "role": "user",
      "content": "I cannot sign in"
    }
  ],
  "max_tokens": 256,
  "stream": false
}

Responses

200Chat completion

application/json

Response headers

x-orlo-model · string: Model that answered.

x-orlo-trace-id · string: Request trace ID for feedback.

x-orlo-validation · string: pass, warn, error, escalate, or abstain.

x-orlo-task-version · string: Task version used.

x-orlo-routing-mode · string: live, policy, or active_fallback.

object

Fields 14

Field	Type	Description
`id`	`string`	—
`object`	`string`	Allowed: "chat.completion".
`created`	`integer`	—
`model`	`string`	—
`choices`	`array<object>`	—
`choices[].index`	`integer`	—
`choices[].message`	`object`	—
`choices[].message.role`	`string`	—
`choices[].message.content`	`string`	—
`choices[].finish_reason`	`string`	—
`usage`	`object`	—
`usage.prompt_tokens`	`integer`	—
`usage.completion_tokens`	`integer`	—
`usage.total_tokens`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "object": "chat.completion",
  "created": 1791979200,
  "model": "gpt-4.1-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "{\"category\":\"account_access\"}"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 84,
    "completion_tokens": 12,
    "total_tokens": 96
  }
}

400INVALID_INPUT: correct the named field. Streaming requests are rejected before a model call.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "stream: Streaming is not supported for task inference. Set stream to false or omit it to receive a complete, checked answer."
}

409CONSENSUS_CONFIGURATION_INVALID: Compare eligible candidates on the same task version and source settings, then correct the consensus configuration.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "CONSENSUS_CONFIGURATION_INVALID",
  "message": "Compare eligible candidates on the same task version and source settings, then correct the consensus configuration."
}

422VALIDATION_FAILED: The answer failed its rules or a required check was indeterminate. No answer was returned.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "VALIDATION_FAILED",
  "message": "The answer failed its rules or a required check was indeterminate. No answer was returned."
}

429INFERENCE_BUSY: Too many requests are running. Honor Retry-After and reduce concurrency.

application/json

Response headers

Retry-After · string: Seconds to wait before another attempt.

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INFERENCE_BUSY",
  "message": "Too many requests are running. Honor Retry-After and reduce concurrency."
}

503Provider capacity or availability, or unavailable evidence. Busy and paused responses carry Retry-After. Do not retry automatically when EVIDENCE_UNAVAILABLE includes details.retry_recommended=false; the provider may already have charged for the call.

application/json

Response headers

Retry-After · string: Present for PROVIDER_BUSY or PROVIDER_PAUSED; seconds to wait.

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example: PROVIDER_BUSY

{
  "error": "PROVIDER_BUSY",
  "message": "The provider connection is busy. Try again shortly."
}

Example: PROVIDER_PAUSED

{
  "error": "PROVIDER_PAUSED",
  "message": "The provider connection is temporarily paused after repeated failures."
}

Example: EVIDENCE_UNAVAILABLE

{
  "error": "EVIDENCE_UNAVAILABLE",
  "message": "The provider answered, but its completion could not be recorded. Do not retry automatically; another call may incur a charge.",
  "details": {
    "provider_call_id": "08ef086a-67d0-4d32-8fdc-99a935ed07b8",
    "provider_completed": true,
    "retry_recommended": false
  }
}

Example: RUNTIME_UNAVAILABLE

{
  "error": "RUNTIME_UNAVAILABLE",
  "message": "The model call failed and no fallback answered. Check provider access and availability."
}

504INFERENCE_TIMEOUT: The request was cancelled or exceeded its time limit.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INFERENCE_TIMEOUT",
  "message": "The request was cancelled or exceeded its time limit."
}

POST/v1/tasks/{taskId}/run

Task-native inference

Required scope: inference.run.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`taskId`*	path	`string (uuid)`	taskId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 3

Field	Type	Description
`input`Required	`object`	Task data, supplied separately from released instructions. {{field}} references name fields in this object.
`deployment_id`	`string (uuid)`	Optional live release belonging to this task. Inactive releases return RELEASE_NOT_LIVE (409).
`explain`	`string`	Allowed: "default", "debug", "audit".

Nested fields marked required are required when their parent object is present.

Example

{
  "input": {
    "ticket": "I cannot sign in"
  },
  "explain": "debug"
}

Responses

200Inference result. When explain is debug or audit, the response includes retrieval and routing metadata.

application/json

object

Fields 30

Field	Type	Description
`output`Required	`string`	Complete answer as a string, including when it contains JSON.
`model`Required	`string`	—
`trace_id`Required	`string (uuid)`	—
`validation`Required	`object`	—
`validation.valid`Required	`boolean`	—
`validation.warnings`Required	`array<string>`	—
`validation.score`Required	`number`	—
`validation.abstain`Required	`boolean`	—
`validation.escalate`Required	`boolean`	—
`validation.status`	`string`	An indeterminate required check blocks the answer with abstain true, including under warn behavior. Allowed: "passed", "failed", "indeterminate".
`debug`	`object`	—
`debug.latency_ms`	`number`	—
`debug.tokens`	`object`	—
`debug.tokens.input`	`integer`	—
`debug.tokens.output`	`integer`	—
`debug.deployment_id`	`string (uuid)`	—
`debug.task_version_id`	`string (uuid)`	—
`debug.strategy`	`string`	—
`debug.validation`	`object`	—
`debug.validation.valid`Required	`boolean`	—
`debug.validation.warnings`Required	`array<string>`	—
`debug.validation.score`Required	`number`	—
`debug.validation.abstain`Required	`boolean`	—
`debug.validation.escalate`Required	`boolean`	—
`debug.validation.status`	`string`	An indeterminate required check blocks the answer with abstain true, including under warn behavior. Allowed: "passed", "failed", "indeterminate".
`debug.retrieval`	`object \| null`	—
`debug.routing`	`object`	—
`debug.routing.mode`	`string`	Allowed: "explicit", "policy", "active_fallback", "live".
`debug.routing.selected_deployment_id`	`string (uuid)`	—
`debug.routing.fallback_deployment_id`	`string (uuid) \| null`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "output": "{\"category\":\"account_access\",\"priority\":\"high\",\"escalate\":false}",
  "model": "gpt-4.1-mini",
  "trace_id": "11111111-1111-4111-8111-111111111111",
  "validation": {
    "valid": true,
    "warnings": [],
    "score": 1,
    "abstain": false,
    "escalate": false
  }
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

409CONSENSUS_CONFIGURATION_INVALID: Compare eligible candidates on the same task version and source settings, then correct the consensus configuration.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "CONSENSUS_CONFIGURATION_INVALID",
  "message": "Compare eligible candidates on the same task version and source settings, then correct the consensus configuration."
}

422Answer rejected by the task rules; no answer is returned. VALIDATION_FAILED: The answer failed its rules or a required check was indeterminate. No answer was returned.

application/json

object

Fields 10

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string (uuid)`	—
`validation`	`object`	—
`validation.valid`Required	`boolean`	—
`validation.warnings`Required	`array<string>`	—
`validation.score`Required	`number`	—
`validation.abstain`Required	`boolean`	—
`validation.escalate`Required	`boolean`	—
`validation.status`	`string`	An indeterminate required check blocks the answer with abstain true, including under warn behavior. Allowed: "passed", "failed", "indeterminate".

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "VALIDATION_FAILED",
  "message": "The answer failed the task rules.",
  "trace_id": "11111111-1111-4111-8111-111111111111",
  "validation": {
    "valid": false,
    "warnings": [
      "Missing required field: category"
    ],
    "score": 0,
    "abstain": false,
    "escalate": false
  }
}

429INFERENCE_BUSY: Too many requests are running. Honor Retry-After and reduce concurrency.

application/json

Response headers

Retry-After · string: Seconds to wait before another attempt.

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INFERENCE_BUSY",
  "message": "Too many requests are running. Honor Retry-After and reduce concurrency."
}

application/json

Response headers

Retry-After · string: Present for PROVIDER_BUSY or PROVIDER_PAUSED; seconds to wait.

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example: PROVIDER_BUSY

{
  "error": "PROVIDER_BUSY",
  "message": "The provider connection is busy. Try again shortly."
}

Example: PROVIDER_PAUSED

{
  "error": "PROVIDER_PAUSED",
  "message": "The provider connection is temporarily paused after repeated failures."
}

Example: EVIDENCE_UNAVAILABLE

{
  "error": "EVIDENCE_UNAVAILABLE",
  "message": "The provider answered, but its completion could not be recorded. Do not retry automatically; another call may incur a charge.",
  "details": {
    "provider_call_id": "08ef086a-67d0-4d32-8fdc-99a935ed07b8",
    "provider_completed": true,
    "retry_recommended": false
  }
}

Example: RUNTIME_UNAVAILABLE

{
  "error": "RUNTIME_UNAVAILABLE",
  "message": "The model call failed and no fallback answered. Check provider access and availability."
}

504INFERENCE_TIMEOUT: The request was cancelled or exceeded its time limit.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INFERENCE_TIMEOUT",
  "message": "The request was cancelled or exceeded its time limit."
}

Feedback

GET/v1/feedback

List feedback

Required scope: feedback.read.

Parameters

Name	Location	Type	Description
`status`	query	`string`	— Example: `string`
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Feedback list

application/json

object

Fields 9

Field	Type	Description
`total`	`integer`	—
`revision`	`string`	—
`feedback`	`array<object>`	—
`feedback[].id`	`string (uuid)`	—
`feedback[].inference_log_id`	`string (uuid)`	—
`feedback[].score`	`integer`	Allowed: -1, 0, 1.
`feedback[].correction`	`object \| null`	—
`feedback[].status`	`string`	Allowed: "pending", "staged", "rejected".
`feedback[].created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "total": 0,
  "revision": "string",
  "feedback": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "inference_log_id": "11111111-1111-4111-8111-111111111111",
      "score": -1,
      "status": "pending",
      "created_at": "2026-10-14T12:00:00Z"
    }
  ]
}

POST/v1/feedback

Submit feedback

Required scope: feedback.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 3

Field	Type	Description
`inference_log_id`Required	`string (uuid)`	—
`score`Required	`integer`	Allowed: -1, 0, 1.
`correction`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "inference_log_id": "11111111-1111-4111-8111-111111111111",
  "score": 0,
  "correction": {
    "category": "account_access"
  }
}

Responses

201Feedback submitted

application/json

object

Fields 4

Field	Type	Description
`id`	`string (uuid)`	—
`status`	`string`	Allowed: "pending".
`created_at`	`string (date-time)`	—
`redaction_warning`	`string`	Present on a write when credential-like values changed. Inspect saved examples before comparing models.

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "pending",
  "created_at": "2026-10-14T12:00:00Z",
  "redaction_warning": "string"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

503EXAMPLE_PROTECTION_UNAVAILABLE: organization credentials could not be checked. No changes were saved.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

PUT/v1/feedback/{id}/status

Transition feedback status

Required scope: feedback.write. Requires a signed-in member with review access. Runtime keys, desktop connections, and management tokens cannot make human review decisions.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 1

Field	Type	Description
`status`Required	`string`	Allowed: "staged", "rejected".

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "status": "staged"
}

Responses

200Status changed

application/json

object

Fields 3

Field	Type	Description
`id`	`string (uuid)`	—
`previous_status`	`string`	—
`status`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "previous_status": "string",
  "status": "string"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

403PEOPLE_ONLY: sign in with a member account that has review access.

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/tasks/{taskId}/feedback/promote

Promote staged feedback into a new dataset

Required scope: datasets.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`taskId`*	path	`string (uuid)`	taskId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

object

Fields 2

Field	Type	Description
`base_dataset_id`	`string (uuid) \| null`	—
`expected_feedback_revision`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "base_dataset_id": "11111111-1111-4111-8111-111111111111",
  "expected_feedback_revision": "string"
}

Responses

200Successful response

application/json

object

Fields 19

Field	Type	Description
`dataset_id`	`string (uuid)`	—
`new_version`	`integer`	—
`promoted_count`	`integer`	—
`sample_count`	`integer`	—
`baseline_count`	`integer`	—
`dataset`	`object`	—
`dataset.id`	`string (uuid)`	—
`dataset.version`	`integer`	—
`dataset.sample_count`	`integer`	—
`dataset.created_at`	`string (date-time)`	—
`dataset.task_id`	`string (uuid)`	—
`dataset.name`	`string`	—
`dataset.parent_dataset_id`	`string (uuid) \| null`	—
`dataset.added_count`	`integer`	—
`dataset.baseline_count`	`integer`	—
`dataset.change_kind`	`string`	—
`dataset.change_mode`	`string`	—
`dataset.redaction_warning`	`string`	Present on a write when credential-like values changed. Inspect saved examples before comparing models.
`dataset.redacted_sample_count`	`integer`	Number of new or copied samples changed by credential protection during this write.

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "dataset_id": "11111111-1111-4111-8111-111111111111",
  "new_version": 0,
  "promoted_count": 0,
  "sample_count": 0,
  "baseline_count": 0,
  "dataset": {
    "id": "11111111-1111-4111-8111-111111111111",
    "version": 0,
    "sample_count": 0,
    "created_at": "2026-10-14T12:00:00Z",
    "task_id": "11111111-1111-4111-8111-111111111111",
    "name": "string",
    "parent_dataset_id": "11111111-1111-4111-8111-111111111111",
    "added_count": 0,
    "baseline_count": 0,
    "change_kind": "string",
    "change_mode": "string",
    "redaction_warning": "string",
    "redacted_sample_count": 0
  }
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

409FEEDBACK_CHANGED: staged corrections changed. DATASET_BASE_CHANGED: the dataset baseline changed. Refresh and review before trying again.

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Documents

GET/v1/tasks/{taskId}/documents

List documents for a task

Required scope: documents.read.

Parameters

Name	Location	Type	Description
`taskId`*	path	`string (uuid)`	taskId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Document list

application/json

object

Fields 21

Field	Type	Description
`documents`	`array<object>`	—
`documents[].id`	`string (uuid)`	—
`documents[].task_id`	`string (uuid)`	—
`documents[].name`	`string`	—
`documents[].content_type`	`string`	—
`documents[].source_kind`	`string`	—
`documents[].chunk_count`	`integer`	—
`documents[].page_count`	`integer \| null`	—
`documents[].size_bytes`	`integer \| null`	—
`documents[].status`	`string`	—
`documents[].metadata`	`object`	—
`documents[].error_details`	`object \| null`	—
`documents[].extraction_report`	`object \| null`	—
`documents[].created_at`	`string (date-time)`	—
`documents[].embedded_chunks`	`integer`	—
`documents[].other_model_chunks`	`integer`	—
`documents[].unrecorded_chunks`	`integer`	—
`capabilities`	`object`	—
`capabilities.pdf`	`boolean`	—
`capabilities.meaning_search`	`boolean`	—
`capabilities.embedding_model`	`string \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "documents": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "task_id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "content_type": "string",
      "source_kind": "string",
      "chunk_count": 0,
      "page_count": 0,
      "size_bytes": 0,
      "status": "string",
      "created_at": "2026-10-14T12:00:00Z",
      "embedded_chunks": 0,
      "other_model_chunks": 0,
      "unrecorded_chunks": 0
    }
  ],
  "capabilities": {
    "pdf": false,
    "meaning_search": false,
    "embedding_model": "string"
  }
}

POST/v1/tasks/{taskId}/documents

Create a document from inline text, pre-chunked content, or inline PDF

Required scope: documents.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`taskId`*	path	`string (uuid)`	taskId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 8

Field	Type	Description
`name`Required	`string`	—
`content`	`string`	—
`content_base64`	`string`	—
`content_type`	`string`	—
`chunks`	`array<object>`	—
`chunks[].content`Required	`string`	—
`chunks[].metadata`	`object`	—
`metadata`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "name": "Support handbook.md",
  "content_type": "text/markdown",
  "content": "# Account access\nAsk the customer to reset their password."
}

Responses

202Document accepted for embedding or extraction

application/json

object

Fields 6

Field	Type	Description
`document_id`	`string (uuid)`	—
`chunk_count`	`integer`	—
`status`	`string`	—
`embedding_job_id`	`string`	—
`extraction_job_id`	`string`	—
`size_bytes`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "document_id": "11111111-1111-4111-8111-111111111111",
  "chunk_count": 12,
  "status": "embedding",
  "embedding_job_id": "42"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

413Error response

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

503Error response

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/tasks/{taskId}/documents/uploads

Start a direct PDF upload

Required scope: documents.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`taskId`*	path	`string (uuid)`	taskId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 5

Field	Type	Description
`name`Required	`string`	—
`content_type`	`string`	—
`size_bytes`Required	`integer`	—
`sha256`	`string`	—
`metadata`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "name": "string",
  "content_type": "string",
  "size_bytes": 0,
  "sha256": "string"
}

Responses

201Upload initiated

application/json

object

Fields 12

Field	Type	Description
`document_id`	`string (uuid)`	—
`status`	`string`	—
`content_type`	`string`	—
`storage_key`	`string`	—
`upload`	`object`	—
`upload.method`	`string`	—
`upload.url`	`string`	—
`upload.headers`	`object`	—
`upload.expires_at`	`string (date-time)`	—
`limits`	`object`	—
`limits.max_direct_upload_bytes`	`integer`	—
`limits.born_digital_only`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "document_id": "11111111-1111-4111-8111-111111111111",
  "status": "string",
  "content_type": "string",
  "storage_key": "string",
  "upload": {
    "method": "string",
    "url": "string",
    "expires_at": "2026-10-14T12:00:00Z"
  },
  "limits": {
    "max_direct_upload_bytes": 0,
    "born_digital_only": false
  }
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

413Error response

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

503Error response

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/tasks/{taskId}/documents/{id}/finalize

Finalize a direct PDF upload and enqueue extraction

Required scope: documents.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`taskId`*	path	`string (uuid)`	taskId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

202Extraction queued

application/json

object

Fields 6

Field	Type	Description
`document_id`	`string (uuid)`	—
`chunk_count`	`integer`	—
`status`	`string`	—
`embedding_job_id`	`string`	—
`extraction_job_id`	`string`	—
`size_bytes`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "document_id": "11111111-1111-4111-8111-111111111111",
  "status": "extracting",
  "size_bytes": 4200,
  "extraction_job_id": "42"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

409Error response

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

413Error response

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

503Error response

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/tasks/{taskId}/documents/{id}

Get one document

Required scope: documents.read.

Parameters

Name	Location	Type	Description
`taskId`*	path	`string (uuid)`	taskId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Document detail

application/json

object

Fields 16

Field	Type	Description
`id`	`string (uuid)`	—
`task_id`	`string (uuid)`	—
`name`	`string`	—
`content_type`	`string`	—
`source_kind`	`string`	—
`chunk_count`	`integer`	—
`page_count`	`integer \| null`	—
`size_bytes`	`integer \| null`	—
`status`	`string`	—
`metadata`	`object`	—
`error_details`	`object \| null`	—
`extraction_report`	`object \| null`	—
`created_at`	`string (date-time)`	—
`embedded_chunks`	`integer`	—
`other_model_chunks`	`integer`	—
`unrecorded_chunks`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "task_id": "22222222-2222-4222-8222-222222222222",
  "name": "Support handbook.md",
  "content_type": "text/markdown",
  "source_kind": "inline",
  "chunk_count": 12,
  "page_count": null,
  "size_bytes": 4200,
  "status": "ready",
  "metadata": {},
  "error_details": null,
  "extraction_report": null,
  "created_at": "2026-10-14T12:00:00Z",
  "embedded_chunks": 12
}

DELETE/v1/tasks/{taskId}/documents/{id}

Delete a document

Required scope: documents.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`taskId`*	path	`string (uuid)`	taskId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

204Deleted; no response body

Credentials

GET/v1/credentials

List credentials

Required scope: credentials.read.

Responses

200Credential list

application/json

object

Fields 10

Field	Type	Description
`credentials`	`array<object>`	—
`credentials[].id`	`string (uuid)`	—
`credentials[].provider`	`string`	—
`credentials[].label`	`string`	—
`credentials[].base_url`	`string \| null`	—
`credentials[].created_at`	`string (date-time)`	—
`credentials[].last_check`	`object \| null`	—
`credentials[].last_check.at`	`string (date-time)`	—
`credentials[].last_check.status`	`string`	—
`credentials[].last_check.message`	`string \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "credentials": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "provider": "string",
      "label": "string",
      "base_url": "string",
      "created_at": "2026-10-14T12:00:00Z",
      "last_check": {
        "at": "2026-10-14T12:00:00Z",
        "status": "string",
        "message": "string"
      }
    }
  ]
}

POST/v1/credentials

Store an encrypted provider credential

Required scope: credentials.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 4

Field	Type	Description
`provider`Required	`string`	Allowed: "openai", "anthropic", "vllm", "llama_cpp", "cloudflare", "huggingface", "custom", "object_storage".
`label`Required	`string`	—
`api_key`Required	`string`	Provider secret. Stored encrypted and never returned by credential reads.
`base_url`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "provider": "openai",
  "label": "Production",
  "api_key": "<your-provider-key>"
}

Responses

201Credential stored

application/json

object

Fields 4

Field	Type	Description
`id`	`string (uuid)`	—
`provider`	`string`	—
`label`	`string`	—
`base_url`	`string \| null`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "provider": "openai",
  "label": "Production"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

PATCH/v1/credentials/{id}

Rename a saved credential

Required scope: credentials.write.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 1

Field	Type	Description
`label`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "label": "string"
}

Responses

200Successful response

application/json

object

Fields 5

Field	Type	Description
`credential`	`object`	—
`credential.id`	`string (uuid)`	—
`credential.provider`	`string`	—
`credential.label`	`string`	—
`credential.base_url`	`string \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "credential": {
    "id": "11111111-1111-4111-8111-111111111111",
    "provider": "string",
    "label": "string",
    "base_url": "string"
  }
}

DELETE/v1/credentials/{id}

Deactivate a credential

Required scope: credentials.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

204Deleted; no response body

POST/v1/credentials/{id}/test

Test a provider key and record the models it lists

Required scope: credentials.write.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Responses

200Successful response

application/json

object

Fields 5

Field	Type	Description
`id`	`string (uuid)`	—
`status`	`string`	Allowed: "ok", "rejected", "unreachable", "refused", "unsupported".
`message`	`string`	—
`model_count`	`integer`	—
`models`	`array<string>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "ok",
  "message": "string",
  "model_count": 0,
  "models": [
    "string"
  ]
}

Models

GET/v1/models

List models visible to the org

Active models plus retired models still used by an active organization release. Availability reflects the most recent saved credential check, not a guarantee of a successful request.

Required scope: models.read.

Parameters

Name	Location	Type	Description
`runtime`	query	`string`	— Example: `string`
`provider`	query	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 21

Field	Type	Description
`models`	`array<object>`	—
`models[].id`	`string (uuid)`	—
`models[].name`	`string`	—
`models[].provider`	`string`	—
`models[].runtime`	`string`	—
`models[].active`	`boolean`	—
`models[].has_credentials`	`boolean`	—
`models[].availability`	`object`	—
`models[].availability.status`	`string`	Allowed: "missing_key", "key_rejected", "unverified", "listed", "not_listed", "retired".
`models[].availability.label`	`string`	—
`models[].availability.message`	`string`	—
`models[].availability.selectable`	`boolean`	—
`models[].availability.checked_at`	`string (date-time) \| null`	—
`models[].retired_at`	`string (date-time) \| null`	—
`models[].retired_reason`	`string \| null`	—
`models[].is_embedding`	`boolean`	—
`models[].price_input_per_million`	`number \| null`	—
`models[].price_output_per_million`	`number \| null`	—
`models[].price_source`	`string \| null`	—
`models[].price_checked_at`	`string (date-time) \| null`	—
`total`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "models": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "provider": "string",
      "runtime": "string",
      "active": false,
      "has_credentials": false,
      "availability": {
        "status": "missing_key",
        "label": "string",
        "message": "string",
        "selectable": false,
        "checked_at": "2026-10-14T12:00:00Z"
      },
      "retired_at": "2026-10-14T12:00:00Z",
      "retired_reason": "string",
      "is_embedding": false,
      "price_input_per_million": 0,
      "price_output_per_million": 0,
      "price_source": "string",
      "price_checked_at": "2026-10-14T12:00:00Z"
    }
  ],
  "total": 0
}

GET/v1/models/{id}

Get one model

Returns an active catalog model; inactive or unknown models return 404.

Required scope: models.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Successful response

application/json

object

Fields 19

Field	Type	Description
`id`	`string (uuid)`	—
`name`	`string`	—
`provider`	`string`	—
`runtime`	`string`	—
`active`	`boolean`	—
`has_credentials`	`boolean`	—
`availability`	`object`	—
`availability.status`	`string`	Allowed: "missing_key", "key_rejected", "unverified", "listed", "not_listed", "retired".
`availability.label`	`string`	—
`availability.message`	`string`	—
`availability.selectable`	`boolean`	—
`availability.checked_at`	`string (date-time) \| null`	—
`retired_at`	`string (date-time) \| null`	—
`retired_reason`	`string \| null`	—
`is_embedding`	`boolean`	—
`price_input_per_million`	`number \| null`	—
`price_output_per_million`	`number \| null`	—
`price_source`	`string \| null`	—
`price_checked_at`	`string (date-time) \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "provider": "string",
  "runtime": "string",
  "active": false,
  "has_credentials": false,
  "availability": {
    "status": "missing_key",
    "label": "string",
    "message": "string",
    "selectable": false,
    "checked_at": "2026-10-14T12:00:00Z"
  },
  "retired_at": "2026-10-14T12:00:00Z",
  "retired_reason": "string",
  "is_embedding": false,
  "price_input_per_million": 0,
  "price_output_per_million": 0,
  "price_source": "string",
  "price_checked_at": "2026-10-14T12:00:00Z"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Adapters

GET/v1/adapters

List adapters

Required scope: models.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Adapter list

application/json

object

Fields 18

Field	Type	Description
`adapters`	`array<object>`	—
`adapters[].id`	`string (uuid)`	—
`adapters[].task_id`	`string (uuid)`	—
`adapters[].base_model_id`	`string (uuid)`	—
`adapters[].name`	`string`	—
`adapters[].format`	`string`	—
`adapters[].storage_path`	`string`	—
`adapters[].status`	`string`	—
`adapters[].base_model_name`	`string`	—
`adapters[].base_model_runtime`	`string`	—
`adapters[].size_bytes`	`integer`	—
`adapters[].rank`	`integer`	—
`adapters[].alpha`	`number`	—
`adapters[].target_modules`	`array<string>`	—
`adapters[].metadata`	`object`	—
`adapters[].active`	`boolean`	—
`adapters[].created_at`	`string (date-time)`	—
`adapters[].updated_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "adapters": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "task_id": "11111111-1111-4111-8111-111111111111",
      "base_model_id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "format": "string",
      "storage_path": "string",
      "status": "string",
      "base_model_name": "string",
      "base_model_runtime": "string",
      "size_bytes": 0,
      "rank": 0,
      "alpha": 0,
      "target_modules": [
        "string"
      ],
      "active": false,
      "created_at": "2026-10-14T12:00:00Z",
      "updated_at": "2026-10-14T12:00:00Z"
    }
  ]
}

POST/v1/adapters

Required scope: models.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 10

Field	Type	Description
`task_id`Required	`string (uuid)`	—
`base_model_id`Required	`string`	—
`name`Required	`string`	—
`format`	`string`	Allowed: "safetensors", "gguf_lora", "peft".
`storage_path`Required	`string`	—
`size_bytes`	`integer`	—
`rank`	`integer`	—
`alpha`	`integer`	—
`target_modules`	`array<string>`	—
`metadata`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "task_id": "11111111-1111-4111-8111-111111111111",
  "base_model_id": "string",
  "name": "string",
  "format": "safetensors",
  "storage_path": "string",
  "size_bytes": 0,
  "rank": 0,
  "alpha": 0,
  "target_modules": [
    "string"
  ]
}

Responses

201Adapter registered

application/json

object

Fields 11

Field	Type	Description
`id`	`string (uuid)`	—
`name`	`string`	—
`format`	`string`	—
`storage_path`	`string`	—
`size_bytes`	`integer`	—
`rank`	`integer`	—
`alpha`	`number`	—
`target_modules`	`array<string>`	—
`status`	`string`	—
`created_at`	`string (date-time)`	—
`base_model`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "format": "string",
  "storage_path": "string",
  "size_bytes": 0,
  "rank": 0,
  "alpha": 0,
  "target_modules": [
    "string"
  ],
  "status": "string",
  "created_at": "2026-10-14T12:00:00Z",
  "base_model": "string"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/adapters/{id}

Get one adapter

Required scope: models.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Adapter detail

application/json

object

Fields 17

Field	Type	Description
`id`	`string (uuid)`	—
`task_id`	`string (uuid)`	—
`base_model_id`	`string (uuid)`	—
`name`	`string`	—
`format`	`string`	—
`storage_path`	`string`	—
`status`	`string`	—
`base_model_name`	`string`	—
`base_model_runtime`	`string`	—
`size_bytes`	`integer`	—
`rank`	`integer`	—
`alpha`	`number`	—
`target_modules`	`array<string>`	—
`metadata`	`object`	—
`active`	`boolean`	—
`created_at`	`string (date-time)`	—
`updated_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "task_id": "11111111-1111-4111-8111-111111111111",
  "base_model_id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "format": "string",
  "storage_path": "string",
  "status": "string",
  "base_model_name": "string",
  "base_model_runtime": "string",
  "size_bytes": 0,
  "rank": 0,
  "alpha": 0,
  "target_modules": [
    "string"
  ],
  "active": false,
  "created_at": "2026-10-14T12:00:00Z",
  "updated_at": "2026-10-14T12:00:00Z"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

PUT/v1/adapters/{id}

Update an adapter

Required scope: models.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 4

Field	Type	Description
`name`	`string`	—
`storage_path`	`string`	—
`metadata`	`object`	—
`active`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "name": "string",
  "storage_path": "string",
  "active": false
}

Responses

200Adapter updated

application/json

object

Fields 4

Field	Type	Description
`id`	`string (uuid)`	—
`name`	`string`	—
`active`	`boolean`	—
`updated_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "active": false,
  "updated_at": "2026-10-14T12:00:00Z"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

DELETE/v1/adapters/{id}

Archive an adapter

Required scope: models.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Adapter archived

application/json

object

Fields 3

Field	Type	Description
`id`	`string (uuid)`	—
`active`	`boolean`	—
`status`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "id": "11111111-1111-4111-8111-111111111111",
  "active": false,
  "status": "archived"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Org-config

GET/v1/orgs/config

Get org config

Required scope: org_config.read.

Responses

200Org config

application/json

object

Fields 1

Field	Type	Description
`config`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{}

PUT/v1/orgs/config

Update org config

Required scope: org_config.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 1

Field	Type	Description
`config`Required	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{}

Responses

200Org config updated

application/json

object

Fields 1

Field	Type	Description
`status`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "status": "updated"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Routing

GET/v1/routing-policies

List routing policies

Required scope: routing.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Routing policy list

application/json

object

Fields 17

Field	Type	Description
`policies`	`array<object>`	—
`policies[].task_id`	`string (uuid)`	—
`policies[].weight_accuracy`	`number`	—
`policies[].weight_latency`	`number`	—
`policies[].weight_cost`	`number`	—
`policies[].weight_validation`	`number`	—
`policies[].min_accuracy`	`number \| null`	—
`policies[].max_latency_ms`	`number \| null`	—
`policies[].min_validation_rate`	`number \| null`	—
`policies[].max_cost_per_1k`	`number \| null`	—
`policies[].sla_latency_p95_ms`	`number`	—
`policies[].sla_availability`	`number`	—
`policies[].sla_max_error_rate`	`number`	—
`policies[].fallback_model_id`	`string (uuid) \| null`	—
`policies[].id`	`string (uuid)`	—
`policies[].org_id`	`string (uuid)`	—
`policies[].created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "policies": [
    {
      "task_id": "11111111-1111-4111-8111-111111111111",
      "weight_accuracy": 0,
      "weight_latency": 0,
      "weight_cost": 0,
      "weight_validation": 0,
      "min_accuracy": 0,
      "max_latency_ms": 0,
      "min_validation_rate": 0,
      "max_cost_per_1k": 0,
      "sla_latency_p95_ms": 0,
      "sla_availability": 0,
      "sla_max_error_rate": 0,
      "fallback_model_id": "11111111-1111-4111-8111-111111111111",
      "id": "11111111-1111-4111-8111-111111111111",
      "org_id": "11111111-1111-4111-8111-111111111111",
      "created_at": "2026-10-14T12:00:00Z"
    }
  ]
}

POST/v1/routing-policies

Create a routing policy

Required scope: routing.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 13

Field	Type	Description
`task_id`Required	`string (uuid)`	—
`weight_accuracy`	`number`	—
`weight_latency`	`number`	—
`weight_cost`	`number`	—
`weight_validation`	`number`	—
`min_accuracy`	`number`	—
`max_latency_ms`	`number`	—
`min_validation_rate`	`number`	—
`max_cost_per_1k`	`number`	—
`sla_latency_p95_ms`	`number`	—
`sla_availability`	`number`	—
`sla_max_error_rate`	`number`	—
`fallback_model_id`	`string (uuid)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "task_id": "11111111-1111-4111-8111-111111111111",
  "weight_accuracy": 0,
  "weight_latency": 0,
  "weight_cost": 0,
  "weight_validation": 0,
  "min_accuracy": 0,
  "max_latency_ms": 0,
  "min_validation_rate": 0,
  "max_cost_per_1k": 0,
  "sla_latency_p95_ms": 0,
  "sla_availability": 0,
  "sla_max_error_rate": 0,
  "fallback_model_id": "11111111-1111-4111-8111-111111111111"
}

Responses

201Routing policy created

application/json

object

Fields 2

Field	Type	Description
`id`	`string (uuid)`	—
`created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "created_at": "2026-10-14T12:00:00Z"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Rubrics

GET/v1/rubrics

List rubrics

Required scope: rubrics.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Rubric list

application/json

object

Fields 14

Field	Type	Description
`rubrics`	`array<object>`	—
`rubrics[].id`	`string (uuid)`	—
`rubrics[].task_id`	`string (uuid)`	—
`rubrics[].version`	`integer`	—
`rubrics[].name`	`string`	—
`rubrics[].created_at`	`string (date-time)`	—
`rubrics[].criteria_count`	`integer`	—
`rubrics[].criteria`	`array<object>`	—
`rubrics[].criteria[].id`	`string (uuid)`	—
`rubrics[].criteria[].name`	`string`	—
`rubrics[].criteria[].description`	`string`	—
`rubrics[].criteria[].weight`	`number`	—
`rubrics[].criteria[].order`	`integer`	—
`rubrics[].criteria[].score_levels`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "rubrics": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "task_id": "11111111-1111-4111-8111-111111111111",
      "version": 0,
      "name": "string",
      "created_at": "2026-10-14T12:00:00Z",
      "criteria_count": 0,
      "criteria": [
        {
          "id": "11111111-1111-4111-8111-111111111111",
          "name": "string",
          "description": "string",
          "weight": 0,
          "order": 0
        }
      ]
    }
  ]
}

POST/v1/rubrics

Create a rubric

Required scope: rubrics.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 6

Field	Type	Description
`task_id`Required	`string (uuid)`	—
`name`Required	`string`	—
`criteria`Required	`array<object>`	—
`criteria[].name`Required	`string`	—
`criteria[].description`Required	`string`	—
`criteria[].weight`	`number`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "task_id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "criteria": [
    {
      "name": "string",
      "description": "string",
      "weight": 0
    }
  ]
}

Responses

201Rubric created

application/json

object

Fields 4

Field	Type	Description
`id`	`string (uuid)`	—
`version`	`integer`	—
`created_at`	`string (date-time)`	—
`name`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "version": 0,
  "created_at": "2026-10-14T12:00:00Z",
  "name": "string"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/rubrics/{id}

Get one rubric

Required scope: rubrics.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Rubric detail

application/json

object

Fields 13

Field	Type	Description
`id`	`string (uuid)`	—
`task_id`	`string (uuid)`	—
`version`	`integer`	—
`name`	`string`	—
`created_at`	`string (date-time)`	—
`criteria_count`	`integer`	—
`criteria`	`array<object>`	—
`criteria[].id`	`string (uuid)`	—
`criteria[].name`	`string`	—
`criteria[].description`	`string`	—
`criteria[].weight`	`number`	—
`criteria[].order`	`integer`	—
`criteria[].score_levels`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "task_id": "11111111-1111-4111-8111-111111111111",
  "version": 0,
  "name": "string",
  "created_at": "2026-10-14T12:00:00Z",
  "criteria_count": 0,
  "criteria": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "description": "string",
      "weight": 0,
      "order": 0
    }
  ]
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

Agent-governance

GET/v1/agent-sessions

List agent sessions

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`status`	query	`string`	— Example: `string`
`limit`	query	`integer`	— Example: `0`

Responses

200Agent sessions

application/json

object

Fields 21

Field	Type	Description
`sessions`	`array<object>`	—
`sessions[].skill_versions`	`array<any>`	—
`sessions[].id`Required	`string`	—
`sessions[].task_id`Required	`string`	—
`sessions[].external_run_id`Required	`string \| null`	—
`sessions[].goal`Required	`string \| null`	—
`sessions[].expected_outcome`Required	`object \| null`	—
`sessions[].framework`Required	`string \| null`	—
`sessions[].risk_tier`Required	`string`	Allowed: "low", "medium", "high", "critical".
`sessions[].autonomy_level`Required	`string`	Allowed: "manual", "assisted", "semi_autonomous", "autonomous".
`sessions[].status`Required	`string`	Allowed: "active", "paused", "completed", "failed", "cancelled", "timed_out".
`sessions[].containment_state`Required	`string \| null`	—
`sessions[].step_count`Required	`number`	—
`sessions[].tool_call_count`Required	`number`	—
`sessions[].write_action_count`Required	`number`	—
`sessions[].external_side_effect_count`Required	`number`	—
`sessions[].started_at`Required	`string`	—
`sessions[].completed_at`Required	`string \| null`	—
`sessions[].last_activity_at`Required	`string`	—
`sessions[].created_at`Required	`string`	—
`sessions[].updated_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "sessions": [
    {
      "skill_versions": [],
      "id": "string",
      "task_id": "string",
      "external_run_id": "string",
      "goal": "string",
      "framework": "string",
      "risk_tier": "low",
      "autonomy_level": "manual",
      "status": "active",
      "step_count": 0,
      "tool_call_count": 0,
      "write_action_count": 0,
      "external_side_effect_count": 0,
      "started_at": "string",
      "completed_at": "string",
      "last_activity_at": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}

POST/v1/agent-sessions

Create an agent session

Required scope: agent_governance.run.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 12

Field	Type	Description
`task_id`Required	`string (uuid)`	—
`external_run_id`	`string`	—
`goal`	`string`	—
`expected_outcome`	`object`	—
`framework`	`string`	—
`risk_tier`	`string`	Allowed: "low", "medium", "high", "critical".
`autonomy_level`	`string`	Allowed: "manual", "assisted", "semi_autonomous", "autonomous".
`metadata`	`object`	—
`skill_versions`	`array<object>`	Exact published skill versions the agent loaded; verified by Orlo and recorded on the run.
`skill_versions[].skill_id`Required	`string (uuid)`	—
`skill_versions[].version_id`Required	`string (uuid)`	—
`skill_versions[].content_hash`Required	`string`	SHA-256 of the version content

Nested fields marked required are required when their parent object is present.

Example

{
  "task_id": "22222222-2222-4222-8222-222222222222",
  "external_run_id": "support-1042",
  "framework": "custom-js-runtime",
  "goal": "Resolve an account access issue"
}

Responses

201Agent session created

application/json

object

Fields 23

Field	Type	Description
`session`	`object`	—
`session.skill_versions`	`array<any>`	—
`session.id`Required	`string`	—
`session.task_id`Required	`string`	—
`session.external_run_id`Required	`string \| null`	—
`session.goal`Required	`string \| null`	—
`session.expected_outcome`Required	`object \| null`	—
`session.framework`Required	`string \| null`	—
`session.risk_tier`Required	`string`	Allowed: "low", "medium", "high", "critical".
`session.autonomy_level`Required	`string`	Allowed: "manual", "assisted", "semi_autonomous", "autonomous".
`session.status`Required	`string`	Allowed: "active", "paused", "completed", "failed", "cancelled", "timed_out".
`session.containment_state`Required	`string \| null`	—
`session.step_count`Required	`number`	—
`session.tool_call_count`Required	`number`	—
`session.write_action_count`Required	`number`	—
`session.external_side_effect_count`Required	`number`	—
`session.started_at`Required	`string`	—
`session.completed_at`Required	`string \| null`	—
`session.last_activity_at`Required	`string`	—
`session.created_at`Required	`string`	—
`session.updated_at`Required	`string`	—
`policy_cache_ttl_s`	`integer`	—
`blocking_step_types`	`array<string>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "session": {
    "skill_versions": [],
    "id": "string",
    "task_id": "string",
    "external_run_id": "string",
    "goal": "string",
    "framework": "string",
    "risk_tier": "low",
    "autonomy_level": "manual",
    "status": "active",
    "step_count": 0,
    "tool_call_count": 0,
    "write_action_count": 0,
    "external_side_effect_count": 0,
    "started_at": "string",
    "completed_at": "string",
    "last_activity_at": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "policy_cache_ttl_s": 0,
  "blocking_step_types": [
    "model_call"
  ]
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/agent-sessions/{sessionId}

Get one agent session

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Session detail including steps, events, trajectory_result, and trajectory_step_results

application/json

object

Fields 149

Field	Type	Description
`session`	`object`	—
`session.skill_versions`	`array<any>`	—
`session.id`Required	`string`	—
`session.task_id`Required	`string`	—
`session.external_run_id`Required	`string \| null`	—
`session.goal`Required	`string \| null`	—
`session.expected_outcome`Required	`object \| null`	—
`session.framework`Required	`string \| null`	—
`session.risk_tier`Required	`string`	Allowed: "low", "medium", "high", "critical".
`session.autonomy_level`Required	`string`	Allowed: "manual", "assisted", "semi_autonomous", "autonomous".
`session.status`Required	`string`	Allowed: "active", "paused", "completed", "failed", "cancelled", "timed_out".
`session.containment_state`Required	`string \| null`	—
`session.step_count`Required	`number`	—
`session.tool_call_count`Required	`number`	—
`session.write_action_count`Required	`number`	—
`session.external_side_effect_count`Required	`number`	—
`session.started_at`Required	`string`	—
`session.completed_at`Required	`string \| null`	—
`session.last_activity_at`Required	`string`	—
`session.created_at`Required	`string`	—
`session.updated_at`Required	`string`	—
`steps`	`array<object>`	—
`steps[].id`Required	`string`	—
`steps[].session_id`Required	`string`	—
`steps[].step_id`Required	`string`	—
`steps[].parent_step_id`Required	`string \| null`	—
`steps[].step_type`Required	`string`	Allowed: "model_call", "model_output", "tool_request", "tool_result", "retrieval", "decision", "approval_request", "approval_result", "state_transition".
`steps[].phase`Required	`string \| null`	—
`steps[].actor`Required	`string \| null`	—
`steps[].tool_name`Required	`string \| null`	—
`steps[].model_name`Required	`string \| null`	—
`steps[].request`Required	`object \| null`	—
`steps[].response`Required	`object \| null`	—
`steps[].decision`Required	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval", "contain".
`steps[].validation_result`Required	`object \| null`	—
`steps[].retrieval_attribution`Required	`object \| null`	—
`steps[].citations`Required	`array<object>`	—
`steps[].citations[].source_type`Required	`string`	Allowed: "document_chunk", "tool_result", "memory_reference", "external_service".
`steps[].citations[].source_id`Required	`string`	—
`steps[].citations[].label`	`string \| null`	—
`steps[].citations[].preview`	`string \| null`	—
`steps[].citations[].score`	`number \| null`	—
`steps[].citations[].metadata`	`object \| null`	—
`steps[].policy_decision`Required	`object \| null`	—
`steps[].policy_decision.decision`Required	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval", "contain".
`steps[].policy_decision.reason_code`Required	`string \| null`	—
`steps[].policy_decision.reason_summary`Required	`string \| null`	—
`steps[].policy_decision.matched_policies`Required	`array<string>`	—
`steps[].policy_decision.decision_latency_ms`Required	`number \| null`	—
`steps[].policy_decision.degraded_mode`Required	`boolean`	—
`steps[].policy_decision.approval_id`	`string \| null`	—
`steps[].policy_decision.approval_timeout_seconds`	`number \| null`	—
`steps[].policy_decision.timeout_action`	`string \| null`	—
`steps[].state_change`Required	`object \| null`	—
`steps[].state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`steps[].state_change.resource_type`Required	`string \| null`	—
`steps[].state_change.resource_id`Required	`string \| null`	—
`steps[].state_change.operation`Required	`string \| null`	—
`steps[].state_change.before`Required	`object \| null`	—
`steps[].state_change.after`Required	`object \| null`	—
`steps[].state_change.evidence`Required	`object \| null`	—
`steps[].timing`Required	`object \| null`	—
`steps[].timing.started_at`	`string \| null`	—
`steps[].timing.completed_at`	`string \| null`	—
`steps[].timing.latency_ms`	`number \| null`	—
`steps[].idempotency_key`Required	`string \| null`	—
`steps[].envelope`Required	`object \| null`	—
`steps[].envelope.version`Required	`string`	Allowed: "governed_step_envelope_v1".
`steps[].envelope.session_id`Required	`string`	—
`steps[].envelope.step_id`Required	`string`	—
`steps[].envelope.parent_step_id`Required	`string \| null`	—
`steps[].envelope.step_type`Required	`string`	Allowed: "model_call", "model_output", "tool_request", "tool_result", "retrieval", "decision", "approval_request", "approval_result", "state_transition".
`steps[].envelope.phase`Required	`string`	Allowed: "pre", "post".
`steps[].envelope.actor`Required	`string`	Allowed: "runtime", "model", "tool", "human", "orlo_policy".
`steps[].envelope.request`Required	`object \| null`	—
`steps[].envelope.result`Required	`object \| null`	—
`steps[].envelope.citations`Required	`array<object>`	—
`steps[].envelope.citations[].source_type`Required	`string`	Allowed: "document_chunk", "tool_result", "memory_reference", "external_service".
`steps[].envelope.citations[].source_id`Required	`string`	—
`steps[].envelope.citations[].label`	`string \| null`	—
`steps[].envelope.citations[].preview`	`string \| null`	—
`steps[].envelope.citations[].score`	`number \| null`	—
`steps[].envelope.citations[].metadata`	`object \| null`	—
`steps[].envelope.policy_decision`Required	`object`	—
`steps[].envelope.policy_decision.decision`Required	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval", "contain".
`steps[].envelope.policy_decision.reason_code`Required	`string \| null`	—
`steps[].envelope.policy_decision.reason_summary`Required	`string \| null`	—
`steps[].envelope.policy_decision.matched_policies`Required	`array<string>`	—
`steps[].envelope.policy_decision.decision_latency_ms`Required	`number \| null`	—
`steps[].envelope.policy_decision.degraded_mode`Required	`boolean`	—
`steps[].envelope.policy_decision.approval_id`	`string \| null`	—
`steps[].envelope.policy_decision.approval_timeout_seconds`	`number \| null`	—
`steps[].envelope.policy_decision.timeout_action`	`string \| null`	—
`steps[].envelope.approval_id`	`string \| null`	—
`steps[].envelope.risk_tier`Required	`string`	Allowed: "low", "medium", "high", "critical".
`steps[].envelope.state_change`Required	`object \| null`	—
`steps[].envelope.state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`steps[].envelope.state_change.resource_type`Required	`string \| null`	—
`steps[].envelope.state_change.resource_id`Required	`string \| null`	—
`steps[].envelope.state_change.operation`Required	`string \| null`	—
`steps[].envelope.state_change.before`Required	`object \| null`	—
`steps[].envelope.state_change.after`Required	`object \| null`	—
`steps[].envelope.state_change.evidence`Required	`object \| null`	—
`steps[].envelope.timing`Required	`object \| null`	—
`steps[].envelope.timing.started_at`	`string \| null`	—
`steps[].envelope.timing.completed_at`	`string \| null`	—
`steps[].envelope.timing.latency_ms`	`number \| null`	—
`steps[].envelope.idempotency_key`Required	`string \| null`	—
`steps[].envelope.trace_id`Required	`string \| null`	—
`steps[].envelope.span_id`Required	`string \| null`	—
`steps[].envelope.parent_span_id`Required	`string \| null`	—
`steps[].cost_estimate`Required	`number \| null`	—
`steps[].latency_ms`Required	`number \| null`	—
`steps[].trace_id`Required	`string \| null`	—
`steps[].span_id`Required	`string \| null`	—
`steps[].parent_span_id`Required	`string \| null`	—
`steps[].created_at`Required	`string`	—
`events`	`array<object>`	—
`events[].id`Required	`string`	—
`events[].session_id`Required	`string`	—
`events[].step_id`Required	`string \| null`	—
`events[].event_type`Required	`string`	—
`events[].event_source`Required	`string`	—
`events[].payload`Required	`object`	—
`events[].created_at`Required	`string`	—
`trajectory_result`	`object \| null`	—
`trajectory_result.id`Required	`string`	—
`trajectory_result.task_id`Required	`string`	—
`trajectory_result.session_id`Required	`string \| null`	—
`trajectory_result.trace_sample_id`Required	`string \| null`	—
`trajectory_result.overall_score`Required	`number`	—
`trajectory_result.metrics`Required	`object`	—
`trajectory_result.summary`Required	`object`	—
`trajectory_result.created_at`Required	`string`	—
`trajectory_result.updated_at`Required	`string`	—
`trajectory_step_results`	`array<object>`	—
`trajectory_step_results[].id`Required	`string`	—
`trajectory_step_results[].trajectory_result_id`Required	`string`	—
`trajectory_step_results[].session_id`Required	`string \| null`	—
`trajectory_step_results[].trace_sample_id`Required	`string \| null`	—
`trajectory_step_results[].step_uuid`Required	`string \| null`	—
`trajectory_step_results[].step_id`Required	`string \| null`	—
`trajectory_step_results[].step_type`Required	`string`	—
`trajectory_step_results[].metric_type`Required	`string`	—
`trajectory_step_results[].score`Required	`number \| null`	—
`trajectory_step_results[].binary_pass`Required	`boolean \| null`	—
`trajectory_step_results[].reason`Required	`string \| null`	—
`trajectory_step_results[].evidence`Required	`object \| null`	—
`trajectory_step_results[].created_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "session": {
    "skill_versions": [],
    "id": "string",
    "task_id": "string",
    "external_run_id": "string",
    "goal": "string",
    "framework": "string",
    "risk_tier": "low",
    "autonomy_level": "manual",
    "status": "active",
    "step_count": 0,
    "tool_call_count": 0,
    "write_action_count": 0,
    "external_side_effect_count": 0,
    "started_at": "string",
    "completed_at": "string",
    "last_activity_at": "string",
    "created_at": "string",
    "updated_at": "string"
  },
  "steps": [
    {
      "id": "string",
      "session_id": "string",
      "step_id": "string",
      "parent_step_id": "string",
      "step_type": "model_call",
      "tool_name": "string",
      "model_name": "string",
      "decision": "allow",
      "citations": [
        {
          "source_type": "document_chunk",
          "source_id": "string",
          "label": "string",
          "preview": "string",
          "score": 0
        }
      ],
      "policy_decision": {
        "decision": "allow",
        "reason_code": "string",
        "reason_summary": "string",
        "matched_policies": [
          "string"
        ],
        "decision_latency_ms": 0,
        "degraded_mode": false,
        "approval_id": "string",
        "approval_timeout_seconds": 0
      },
      "state_change": {
        "kind": "none",
        "resource_type": "string",
        "resource_id": "string",
        "operation": "string"
      },
      "timing": {
        "started_at": "string",
        "completed_at": "string",
        "latency_ms": 0
      },
      "idempotency_key": "string",
      "envelope": {
        "version": "governed_step_envelope_v1",
        "session_id": "string",
        "step_id": "string",
        "parent_step_id": "string",
        "step_type": "model_call",
        "phase": "pre",
        "actor": "runtime",
        "citations": [
          {
            "source_type": "document_chunk",
            "source_id": "string",
            "label": "string",
            "preview": "string",
            "score": 0
          }
        ],
        "policy_decision": {
          "decision": "allow",
          "reason_code": "string",
          "reason_summary": "string",
          "matched_policies": [
            "string"
          ],
          "decision_latency_ms": 0,
          "degraded_mode": false,
          "approval_id": "string",
          "approval_timeout_seconds": 0
        },
        "approval_id": "string",
        "risk_tier": "low",
        "state_change": {
          "kind": "none",
          "resource_type": "string",
          "resource_id": "string",
          "operation": "string"
        },
        "timing": {
          "started_at": "string",
          "completed_at": "string",
          "latency_ms": 0
        },
        "idempotency_key": "string",
        "trace_id": "string",
        "span_id": "string",
        "parent_span_id": "string"
      },
      "cost_estimate": 0,
      "latency_ms": 0,
      "trace_id": "string",
      "span_id": "string",
      "parent_span_id": "string",
      "created_at": "string"
    }
  ],
  "events": [
    {
      "id": "string",
      "session_id": "string",
      "step_id": "string",
      "event_type": "string",
      "event_source": "string",
      "created_at": "string"
    }
  ],
  "trajectory_result": {
    "id": "string",
    "task_id": "string",
    "session_id": "string",
    "trace_sample_id": "string",
    "overall_score": 0,
    "created_at": "string",
    "updated_at": "string"
  },
  "trajectory_step_results": [
    {
      "id": "string",
      "trajectory_result_id": "string",
      "session_id": "string",
      "trace_sample_id": "string",
      "step_uuid": "string",
      "step_id": "string",
      "step_type": "string",
      "metric_type": "string",
      "score": 0,
      "binary_pass": false,
      "reason": "string",
      "created_at": "string"
    }
  ]
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

PATCH/v1/agent-sessions/{sessionId}

Update session status

Required scope: agent_governance.run.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 1

Field	Type	Description
`status`Required	`string`	Allowed: "active", "paused", "completed", "failed", "cancelled", "timed_out".

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "status": "active"
}

Responses

200Session updated

application/json

object

Fields 20

Field	Type	Description
`skill_versions`	`array<any>`	—
`id`Required	`string`	—
`task_id`Required	`string`	—
`external_run_id`Required	`string \| null`	—
`goal`Required	`string \| null`	—
`expected_outcome`Required	`object \| null`	—
`framework`Required	`string \| null`	—
`risk_tier`Required	`string`	Allowed: "low", "medium", "high", "critical".
`autonomy_level`Required	`string`	Allowed: "manual", "assisted", "semi_autonomous", "autonomous".
`status`Required	`string`	Allowed: "active", "paused", "completed", "failed", "cancelled", "timed_out".
`containment_state`Required	`string \| null`	—
`step_count`Required	`number`	—
`tool_call_count`Required	`number`	—
`write_action_count`Required	`number`	—
`external_side_effect_count`Required	`number`	—
`started_at`Required	`string`	—
`completed_at`Required	`string \| null`	—
`last_activity_at`Required	`string`	—
`created_at`Required	`string`	—
`updated_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "skill_versions": [],
  "id": "string",
  "task_id": "string",
  "external_run_id": "string",
  "goal": "string",
  "framework": "string",
  "risk_tier": "low",
  "autonomy_level": "manual",
  "status": "active",
  "step_count": 0,
  "tool_call_count": 0,
  "write_action_count": 0,
  "external_side_effect_count": 0,
  "started_at": "string",
  "completed_at": "string",
  "last_activity_at": "string",
  "created_at": "string",
  "updated_at": "string"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/agent-sessions/{sessionId}/steps/govern

Govern one agent step

Required scope: agent_governance.run.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 53

Field	Type	Description
`step_id`Required	`string`	—
`parent_step_id`	`string`	—
`step_type`Required	`string`	Allowed: "model_call", "model_output", "tool_request", "tool_result", "retrieval", "decision", "approval_request", "approval_result", "state_transition".
`phase`	`string`	Allowed: "pre", "post".
`actor`	`string`	Allowed: "runtime", "model", "tool", "human", "orlo_policy".
`tool_name`	`string`	—
`model_name`	`string`	—
`action_class`	`string`	Allowed: "read", "write", "delete", "network", "control".
`environment`	`string`	—
`request`	`object`	—
`input`	`object`	—
`result`	`object`	—
`result.content`	`any`	—
`result.model`	`string`	—
`result.tokens_used`	`object`	—
`result.tokens_used.input`	`number`	—
`result.tokens_used.output`	`number`	—
`result.latency_ms`	`number`	—
`output`	`object`	—
`output.content`	`any`	—
`output.model`	`string`	—
`output.tokens_used`	`object`	—
`output.tokens_used.input`	`number`	—
`output.tokens_used.output`	`number`	—
`output.latency_ms`	`number`	—
`retrieval`	`object`	—
`retrieval.task_id`	`string`	—
`retrieval.query`	`string`	—
`retrieval.token_budget`	`number`	—
`citations`	`array<object>`	—
`citations[].source_type`Required	`string`	Allowed: "document_chunk", "tool_result", "memory_reference", "external_service".
`citations[].source_id`Required	`string`	—
`citations[].label`	`string \| null`	—
`citations[].preview`	`string \| null`	—
`citations[].score`	`number \| null`	—
`citations[].metadata`	`object \| null`	—
`state_change`	`object`	—
`state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`state_change.resource_type`Required	`string \| null`	—
`state_change.resource_id`Required	`string \| null`	—
`state_change.operation`Required	`string \| null`	—
`state_change.before`Required	`object \| null`	—
`state_change.after`Required	`object \| null`	—
`state_change.evidence`Required	`object \| null`	—
`timing`	`object`	—
`timing.started_at`	`string \| null`	—
`timing.completed_at`	`string \| null`	—
`timing.latency_ms`	`number \| null`	—
`idempotency_key`	`string`	—
`metadata`	`object`	—
`trace_id`	`string`	—
`span_id`	`string`	—
`parent_span_id`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "step_id": "lookup-order-1",
  "step_type": "tool_request",
  "tool_name": "lookup_order",
  "action_class": "read",
  "input": {
    "order_id": "order-1042"
  }
}

Responses

200Governance result

application/json

object

Fields 85

Field	Type	Description
`decision`Required	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval", "contain".
`reason`Required	`string \| null`	—
`trace_id`Required	`string`	—
`risk_tier`Required	`string`	Allowed: "low", "medium", "high", "critical".
`containment`Required	`string \| null`	—
`validation`Required	`object \| null`	—
`validation.valid`Required	`boolean`	—
`validation.warnings`Required	`array<string>`	—
`validation.score`Required	`number`	—
`validation.abstain`Required	`boolean`	—
`validation.escalate`Required	`boolean`	—
`policy_decision`Required	`object`	—
`policy_decision.decision`Required	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval", "contain".
`policy_decision.reason_code`Required	`string \| null`	—
`policy_decision.reason_summary`Required	`string \| null`	—
`policy_decision.matched_policies`Required	`array<string>`	—
`policy_decision.decision_latency_ms`Required	`number \| null`	—
`policy_decision.degraded_mode`Required	`boolean`	—
`policy_decision.approval_id`	`string \| null`	—
`policy_decision.approval_timeout_seconds`	`number \| null`	—
`policy_decision.timeout_action`	`string \| null`	—
`citations`Required	`array<object>`	—
`citations[].source_type`Required	`string`	Allowed: "document_chunk", "tool_result", "memory_reference", "external_service".
`citations[].source_id`Required	`string`	—
`citations[].label`	`string \| null`	—
`citations[].preview`	`string \| null`	—
`citations[].score`	`number \| null`	—
`citations[].metadata`	`object \| null`	—
`state_change`Required	`object \| null`	—
`state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`state_change.resource_type`Required	`string \| null`	—
`state_change.resource_id`Required	`string \| null`	—
`state_change.operation`Required	`string \| null`	—
`state_change.before`Required	`object \| null`	—
`state_change.after`Required	`object \| null`	—
`state_change.evidence`Required	`object \| null`	—
`envelope`Required	`object`	—
`envelope.version`Required	`string`	Allowed: "governed_step_envelope_v1".
`envelope.session_id`Required	`string`	—
`envelope.step_id`Required	`string`	—
`envelope.parent_step_id`Required	`string \| null`	—
`envelope.step_type`Required	`string`	Allowed: "model_call", "model_output", "tool_request", "tool_result", "retrieval", "decision", "approval_request", "approval_result", "state_transition".
`envelope.phase`Required	`string`	Allowed: "pre", "post".
`envelope.actor`Required	`string`	Allowed: "runtime", "model", "tool", "human", "orlo_policy".
`envelope.request`Required	`object \| null`	—
`envelope.result`Required	`object \| null`	—
`envelope.citations`Required	`array<object>`	—
`envelope.citations[].source_type`Required	`string`	Allowed: "document_chunk", "tool_result", "memory_reference", "external_service".
`envelope.citations[].source_id`Required	`string`	—
`envelope.citations[].label`	`string \| null`	—
`envelope.citations[].preview`	`string \| null`	—
`envelope.citations[].score`	`number \| null`	—
`envelope.citations[].metadata`	`object \| null`	—
`envelope.policy_decision`Required	`object`	—
`envelope.policy_decision.decision`Required	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval", "contain".
`envelope.policy_decision.reason_code`Required	`string \| null`	—
`envelope.policy_decision.reason_summary`Required	`string \| null`	—
`envelope.policy_decision.matched_policies`Required	`array<string>`	—
`envelope.policy_decision.decision_latency_ms`Required	`number \| null`	—
`envelope.policy_decision.degraded_mode`Required	`boolean`	—
`envelope.policy_decision.approval_id`	`string \| null`	—
`envelope.policy_decision.approval_timeout_seconds`	`number \| null`	—
`envelope.policy_decision.timeout_action`	`string \| null`	—
`envelope.approval_id`	`string \| null`	—
`envelope.risk_tier`Required	`string`	Allowed: "low", "medium", "high", "critical".
`envelope.state_change`Required	`object \| null`	—
`envelope.state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`envelope.state_change.resource_type`Required	`string \| null`	—
`envelope.state_change.resource_id`Required	`string \| null`	—
`envelope.state_change.operation`Required	`string \| null`	—
`envelope.state_change.before`Required	`object \| null`	—
`envelope.state_change.after`Required	`object \| null`	—
`envelope.state_change.evidence`Required	`object \| null`	—
`envelope.timing`Required	`object \| null`	—
`envelope.timing.started_at`	`string \| null`	—
`envelope.timing.completed_at`	`string \| null`	—
`envelope.timing.latency_ms`	`number \| null`	—
`envelope.idempotency_key`Required	`string \| null`	—
`envelope.trace_id`Required	`string \| null`	—
`envelope.span_id`Required	`string \| null`	—
`envelope.parent_span_id`Required	`string \| null`	—
`retrieval`Required	`object \| null`	—
`retrieval.chunks`Required	`array<object>`	—
`retrieval.attribution`Required	`object`	—
`action_id`	`string (uuid)`	Use this governed tool action ID for execution and business reports.

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "decision": "allow",
  "reason": "string",
  "trace_id": "string",
  "risk_tier": "low",
  "validation": {
    "valid": false,
    "warnings": [
      "string"
    ],
    "score": 0,
    "abstain": false,
    "escalate": false
  },
  "policy_decision": {
    "decision": "allow",
    "reason_code": "string",
    "reason_summary": "string",
    "matched_policies": [
      "string"
    ],
    "decision_latency_ms": 0,
    "degraded_mode": false,
    "approval_id": "string",
    "approval_timeout_seconds": 0
  },
  "citations": [
    {
      "source_type": "document_chunk",
      "source_id": "string",
      "label": "string",
      "preview": "string",
      "score": 0
    }
  ],
  "state_change": {
    "kind": "none",
    "resource_type": "string",
    "resource_id": "string",
    "operation": "string"
  },
  "envelope": {
    "version": "governed_step_envelope_v1",
    "session_id": "string",
    "step_id": "string",
    "parent_step_id": "string",
    "step_type": "model_call",
    "phase": "pre",
    "actor": "runtime",
    "citations": [
      {
        "source_type": "document_chunk",
        "source_id": "string",
        "label": "string",
        "preview": "string",
        "score": 0
      }
    ],
    "policy_decision": {
      "decision": "allow",
      "reason_code": "string",
      "reason_summary": "string",
      "matched_policies": [
        "string"
      ],
      "decision_latency_ms": 0,
      "degraded_mode": false,
      "approval_id": "string",
      "approval_timeout_seconds": 0
    },
    "approval_id": "string",
    "risk_tier": "low",
    "state_change": {
      "kind": "none",
      "resource_type": "string",
      "resource_id": "string",
      "operation": "string"
    },
    "timing": {
      "started_at": "string",
      "completed_at": "string",
      "latency_ms": 0
    },
    "idempotency_key": "string",
    "trace_id": "string",
    "span_id": "string",
    "parent_span_id": "string"
  },
  "retrieval": {
    "chunks": []
  },
  "action_id": "11111111-1111-4111-8111-111111111111"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/agent-sessions/{sessionId}/traces/import

Import trace steps and events

Required scope: agent_governance.run.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 2

Field	Type	Description
`steps`	`array<object>`	—
`events`	`array<object>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "steps": [],
  "events": []
}

Responses

200Trace imported

application/json

object

Fields 2

Field	Type	Description
`inserted_steps`	`integer`	—
`inserted_events`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "inserted_steps": 1,
  "inserted_events": 0
}

POST/v1/agent-sessions/{sessionId}/steps

Import a single step

Required scope: agent_governance.run.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 15

Field	Type	Description
`step_id`Required	`string`	—
`parent_step_id`	`string`	—
`step_type`Required	`string`	Allowed: "model_call", "model_output", "tool_request", "tool_result", "retrieval", "decision", "approval_request", "approval_result", "state_transition".
`tool_name`	`string`	—
`model_name`	`string`	—
`input`	`object`	—
`output`	`object`	—
`output.content`	`any`	—
`output.model`	`string`	—
`output.tokens_used`	`object`	—
`output.tokens_used.input`	`number`	—
`output.tokens_used.output`	`number`	—
`output.latency_ms`	`number`	—
`decision`	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval", "contain".
`created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "step_id": "string",
  "parent_step_id": "string",
  "step_type": "model_call",
  "tool_name": "string",
  "model_name": "string",
  "output": {
    "model": "string",
    "tokens_used": {
      "input": 0,
      "output": 0
    },
    "latency_ms": 0
  },
  "decision": "allow",
  "created_at": "2026-10-14T12:00:00Z"
}

Responses

200Step imported

application/json

object

Fields 2

Field	Type	Description
`inserted_steps`	`integer`	—
`inserted_events`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "inserted_steps": 1,
  "inserted_events": 0
}

GET/v1/agent-sessions/{sessionId}/events

List session events

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Event list

application/json

object

Fields 8

Field	Type	Description
`events`	`array<object>`	—
`events[].id`Required	`string`	—
`events[].session_id`Required	`string`	—
`events[].step_id`Required	`string \| null`	—
`events[].event_type`Required	`string`	—
`events[].event_source`Required	`string`	—
`events[].payload`Required	`object`	—
`events[].created_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "events": [
    {
      "id": "string",
      "session_id": "string",
      "step_id": "string",
      "event_type": "string",
      "event_source": "string",
      "created_at": "string"
    }
  ]
}

POST/v1/agent-sessions/{sessionId}/tools/check

Check a tool call against policy

Required scope: agent_governance.run.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 6

Field	Type	Description
`step_id`Required	`string`	—
`tool_name`Required	`string`	—
`arguments`	`object`	—
`action_class`	`string`	Allowed: "read", "write", "delete", "network", "control".
`environment`	`string`	—
`risk_tier`	`string`	Allowed: "low", "medium", "high", "critical".

Nested fields marked required are required when their parent object is present.

Example

{
  "step_id": "lookup-order-1",
  "tool_name": "lookup_order",
  "arguments": {
    "order_id": "order-1042"
  },
  "action_class": "read"
}

Responses

200Tool policy result

application/json

object

Fields 4

Field	Type	Description
`decision`Required	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval", "contain".
`reason`Required	`string \| null`	—
`containment`Required	`string \| null`	—
`matched_policies`Required	`array<string>`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "decision": "allow",
  "reason": "The read action is permitted.",
  "containment": null,
  "matched_policies": [
    "11111111-1111-4111-8111-111111111111"
  ]
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/tool-policies

List tool policies

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`deployment_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Tool policies

application/json

object

Fields 28

Field	Type	Description
`policies`	`array<object>`	—
`policies[].id`Required	`string`	—
`policies[].task_id`Required	`string \| null`	—
`policies[].deployment_id`Required	`string \| null`	—
`policies[].tool_name`Required	`string`	—
`policies[].environment`Required	`string \| null`	—
`policies[].action_class`Required	`string \| null`	—
`policies[].decision`Required	`string`	Allowed: "allow", "allow_with_warning", "reject", "require_approval".
`policies[].risk_tier`Required	`string \| null`	—
`policies[].approval_timeout_seconds`Required	`number \| null`	—
`policies[].timeout_action`Required	`string \| null`	—
`policies[].created_at`Required	`string`	—
`policies[].updated_at`Required	`string`	—
`policies[].argument_conditions`	`array<object \| object \| object>`	—
`policies[].argument_conditions[] (option 1).path`Required	`string`	—
`policies[].argument_conditions[] (option 1).operator`Required	`string`	Allowed: "eq", "ne".
`policies[].argument_conditions[] (option 1).value`Required	`string \| number \| boolean \| null`	—
`policies[].argument_conditions[] (option 2).path`Required	`string`	—
`policies[].argument_conditions[] (option 2).operator`Required	`string`	Allowed: "gt", "gte", "lt", "lte".
`policies[].argument_conditions[] (option 2).value`Required	`number`	—
`policies[].argument_conditions[] (option 3).path`Required	`string`	—
`policies[].argument_conditions[] (option 3).operator`Required	`string`	Allowed: "in".
`policies[].argument_conditions[] (option 3).value`Required	`array<string \| number \| boolean \| null>`	—
`policies[].policy_version`	`integer`	—
`policies[].band_state`	`string \| null`	Allowed: "shadow", "earning", "enabled", "suspended", "retired".
`policies[].band_epoch`	`integer`	—
`policies[].band_scope_hash`	`string \| null`	—
`policies[].band_reason`	`string \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "policies": [
    {
      "id": "string",
      "task_id": "string",
      "deployment_id": "string",
      "tool_name": "string",
      "environment": "string",
      "decision": "allow",
      "approval_timeout_seconds": 0,
      "created_at": "string",
      "updated_at": "string",
      "argument_conditions": [
        {
          "path": "string",
          "operator": "eq",
          "value": "string"
        }
      ],
      "policy_version": 0,
      "band_state": "shadow",
      "band_epoch": 0,
      "band_scope_hash": "string",
      "band_reason": "string"
    }
  ]
}

GET/v1/runtime-limits

List runtime limits

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`deployment_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Runtime limits

application/json

object

Fields 18

Field	Type	Description
`limits`	`array<object>`	—
`limits[].id`Required	`string`	—
`limits[].task_id`Required	`string \| null`	—
`limits[].deployment_id`Required	`string \| null`	—
`limits[].risk_tier`Required	`string \| null`	—
`limits[].max_steps`Required	`number \| null`	—
`limits[].max_tool_calls`Required	`number \| null`	—
`limits[].max_write_actions`Required	`number \| null`	—
`limits[].max_external_side_effects`Required	`number \| null`	—
`limits[].inactivity_timeout_seconds`Required	`number \| null`	—
`limits[].created_at`Required	`string`	—
`limits[].updated_at`Required	`string`	—
`base_effective`	`object`	—
`base_effective.max_steps`	`integer \| null`	—
`base_effective.max_tool_calls`	`integer \| null`	—
`base_effective.max_write_actions`	`integer \| null`	—
`base_effective.max_external_side_effects`	`integer \| null`	—
`base_effective.inactivity_timeout_seconds`	`integer \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "limits": [
    {
      "id": "string",
      "task_id": "string",
      "deployment_id": "string",
      "max_steps": 0,
      "max_tool_calls": 0,
      "max_write_actions": 0,
      "max_external_side_effects": 0,
      "inactivity_timeout_seconds": 0,
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "base_effective": {
    "max_steps": 0,
    "max_tool_calls": 0,
    "max_write_actions": 0,
    "max_external_side_effects": 0,
    "inactivity_timeout_seconds": 0
  }
}

GET/v1/agent-approvals

List approvals

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`status`	query	`string`	— Example: `string`
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`limit`	query	`integer`	— Example: `0`

Responses

200Approval list

application/json

object

Fields 18

Field	Type	Description
`approvals`	`array<object>`	—
`approvals[].id`Required	`string`	—
`approvals[].session_id`Required	`string`	—
`approvals[].step_id`Required	`string`	—
`approvals[].task_id`Required	`string`	—
`approvals[].policy_reason`Required	`string`	—
`approvals[].status`Required	`string`	Allowed: "pending", "approved", "rejected", "expired".
`approvals[].request_payload`Required	`object \| null`	—
`approvals[].timeout_action`Required	`string \| null`	—
`approvals[].timeout_at`Required	`string \| null`	—
`approvals[].escalated_at`Required	`string \| null`	—
`approvals[].decided_at`Required	`string \| null`	—
`approvals[].decided_by`Required	`string \| null`	—
`approvals[].decision_payload`Required	`object \| null`	—
`approvals[].consumed_at`Required	`string \| null`	—
`approvals[].consumed_by_step_uuid`Required	`string \| null`	—
`approvals[].created_at`Required	`string`	—
`approvals[].updated_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "approvals": [
    {
      "id": "string",
      "session_id": "string",
      "step_id": "string",
      "task_id": "string",
      "policy_reason": "string",
      "status": "pending",
      "timeout_at": "string",
      "escalated_at": "string",
      "decided_at": "string",
      "decided_by": "string",
      "consumed_at": "string",
      "consumed_by_step_uuid": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}

POST/v1/agent-sessions/{sessionId}/steps/{stepId}/request-approval

Request approval for a step

Required scope: agent_governance.run.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`
`stepId`*	path	`string`	stepId identifies the resource in this request. Example: `lookup-order-1`

Request Body

Content-Type: application/json

Body required

object

Fields 4

Field	Type	Description
`policy_reason`Required	`string`	—
`request_payload`	`object`	—
`approval_timeout_seconds`	`integer`	—
`timeout_action`	`string`	Allowed: "reject", "escalate", "contain".

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "policy_reason": "string",
  "approval_timeout_seconds": 0,
  "timeout_action": "reject"
}

Responses

201Approval requested

application/json

object

Fields 17

Field	Type	Description
`id`Required	`string`	—
`session_id`Required	`string`	—
`step_id`Required	`string`	—
`task_id`Required	`string`	—
`policy_reason`Required	`string`	—
`status`Required	`string`	Allowed: "pending", "approved", "rejected", "expired".
`request_payload`Required	`object \| null`	—
`timeout_action`Required	`string \| null`	—
`timeout_at`Required	`string \| null`	—
`escalated_at`Required	`string \| null`	—
`decided_at`Required	`string \| null`	—
`decided_by`Required	`string \| null`	—
`decision_payload`Required	`object \| null`	—
`consumed_at`Required	`string \| null`	—
`consumed_by_step_uuid`Required	`string \| null`	—
`created_at`Required	`string`	—
`updated_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "string",
  "session_id": "string",
  "step_id": "string",
  "task_id": "string",
  "policy_reason": "string",
  "status": "pending",
  "timeout_at": "string",
  "escalated_at": "string",
  "decided_at": "string",
  "decided_by": "string",
  "consumed_at": "string",
  "consumed_by_step_uuid": "string",
  "created_at": "string",
  "updated_at": "string"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/agent-sessions/{sessionId}/events/stream

Stream session events over SSE

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`sessionId`*	path	`string (uuid)`	sessionId identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`
`after`	query	`string (date-time)`	Optional cursor. Only newer events are streamed. Example: `2026-10-14T12:00:00Z`

Responses

200Server-sent event stream

text/event-stream

string

Example

event: connected\ndata: {"session_id":"..."}\n\nevent: step.governed\ndata: {...}\n\n

GET/v1/trace-samples

List trace samples

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`status`	query	`string`	— Example: `candidate`
`limit`	query	`integer`	— Example: `0`

Responses

200Trace sample list

application/json

object

Fields 21

Field	Type	Description
`trace_samples`	`array<object>`	—
`trace_samples[].id`Required	`string`	—
`trace_samples[].task_id`Required	`string`	—
`trace_samples[].dataset_id`Required	`string \| null`	—
`trace_samples[].session_id`Required	`string`	—
`trace_samples[].step_uuid`Required	`string \| null`	—
`trace_samples[].source`Required	`string`	Allowed: "manual", "policy", "drift", "import".
`trace_samples[].status`Required	`string`	Allowed: "candidate", "approved", "rejected", "promoted".
`trace_samples[].trace_snapshot`Required	`object`	—
`trace_samples[].expected_output`Required	`object \| null`	—
`trace_samples[].expected_state_change`Required	`object \| null`	—
`trace_samples[].expected_state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`trace_samples[].expected_state_change.resource_type`Required	`string \| null`	—
`trace_samples[].expected_state_change.resource_id`Required	`string \| null`	—
`trace_samples[].expected_state_change.operation`Required	`string \| null`	—
`trace_samples[].expected_state_change.before`Required	`object \| null`	—
`trace_samples[].expected_state_change.after`Required	`object \| null`	—
`trace_samples[].expected_state_change.evidence`Required	`object \| null`	—
`trace_samples[].metadata`Required	`object`	—
`trace_samples[].created_at`Required	`string`	—
`trace_samples[].updated_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "trace_samples": [
    {
      "id": "string",
      "task_id": "string",
      "dataset_id": "string",
      "session_id": "string",
      "step_uuid": "string",
      "source": "manual",
      "status": "candidate",
      "expected_state_change": {
        "kind": "none",
        "resource_type": "string",
        "resource_id": "string",
        "operation": "string"
      },
      "created_at": "string",
      "updated_at": "string"
    }
  ]
}

GET/v1/trace-samples/{id}

Get one trace sample

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Responses

200Trace sample detail including annotations, trajectory_result, and trajectory_step_results

application/json

object

Fields 53

Field	Type	Description
`trace_sample`	`object`	—
`trace_sample.id`Required	`string`	—
`trace_sample.task_id`Required	`string`	—
`trace_sample.dataset_id`Required	`string \| null`	—
`trace_sample.session_id`Required	`string`	—
`trace_sample.step_uuid`Required	`string \| null`	—
`trace_sample.source`Required	`string`	Allowed: "manual", "policy", "drift", "import".
`trace_sample.status`Required	`string`	Allowed: "candidate", "approved", "rejected", "promoted".
`trace_sample.trace_snapshot`Required	`object`	—
`trace_sample.expected_output`Required	`object \| null`	—
`trace_sample.expected_state_change`Required	`object \| null`	—
`trace_sample.expected_state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`trace_sample.expected_state_change.resource_type`Required	`string \| null`	—
`trace_sample.expected_state_change.resource_id`Required	`string \| null`	—
`trace_sample.expected_state_change.operation`Required	`string \| null`	—
`trace_sample.expected_state_change.before`Required	`object \| null`	—
`trace_sample.expected_state_change.after`Required	`object \| null`	—
`trace_sample.expected_state_change.evidence`Required	`object \| null`	—
`trace_sample.metadata`Required	`object`	—
`trace_sample.created_at`Required	`string`	—
`trace_sample.updated_at`Required	`string`	—
`annotations`	`array<object>`	—
`annotations[].id`Required	`string`	—
`annotations[].trace_sample_id`Required	`string`	—
`annotations[].annotation_type`Required	`string`	—
`annotations[].label`Required	`string`	—
`annotations[].payload`Required	`object`	—
`annotations[].created_by`Required	`string \| null`	—
`annotations[].created_at`Required	`string`	—
`trajectory_result`	`object \| null`	—
`trajectory_result.id`Required	`string`	—
`trajectory_result.task_id`Required	`string`	—
`trajectory_result.session_id`Required	`string \| null`	—
`trajectory_result.trace_sample_id`Required	`string \| null`	—
`trajectory_result.overall_score`Required	`number`	—
`trajectory_result.metrics`Required	`object`	—
`trajectory_result.summary`Required	`object`	—
`trajectory_result.created_at`Required	`string`	—
`trajectory_result.updated_at`Required	`string`	—
`trajectory_step_results`	`array<object>`	—
`trajectory_step_results[].id`Required	`string`	—
`trajectory_step_results[].trajectory_result_id`Required	`string`	—
`trajectory_step_results[].session_id`Required	`string \| null`	—
`trajectory_step_results[].trace_sample_id`Required	`string \| null`	—
`trajectory_step_results[].step_uuid`Required	`string \| null`	—
`trajectory_step_results[].step_id`Required	`string \| null`	—
`trajectory_step_results[].step_type`Required	`string`	—
`trajectory_step_results[].metric_type`Required	`string`	—
`trajectory_step_results[].score`Required	`number \| null`	—
`trajectory_step_results[].binary_pass`Required	`boolean \| null`	—
`trajectory_step_results[].reason`Required	`string \| null`	—
`trajectory_step_results[].evidence`Required	`object \| null`	—
`trajectory_step_results[].created_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "trace_sample": {
    "id": "string",
    "task_id": "string",
    "dataset_id": "string",
    "session_id": "string",
    "step_uuid": "string",
    "source": "manual",
    "status": "candidate",
    "expected_state_change": {
      "kind": "none",
      "resource_type": "string",
      "resource_id": "string",
      "operation": "string"
    },
    "created_at": "string",
    "updated_at": "string"
  },
  "annotations": [
    {
      "id": "string",
      "trace_sample_id": "string",
      "annotation_type": "string",
      "label": "string",
      "created_by": "string",
      "created_at": "string"
    }
  ],
  "trajectory_result": {
    "id": "string",
    "task_id": "string",
    "session_id": "string",
    "trace_sample_id": "string",
    "overall_score": 0,
    "created_at": "string",
    "updated_at": "string"
  },
  "trajectory_step_results": [
    {
      "id": "string",
      "trajectory_result_id": "string",
      "session_id": "string",
      "trace_sample_id": "string",
      "step_uuid": "string",
      "step_id": "string",
      "step_type": "string",
      "metric_type": "string",
      "score": 0,
      "binary_pass": false,
      "reason": "string",
      "created_at": "string"
    }
  ]
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/trace-samples/{id}/annotations

Annotate a trace sample

Required scope: agent_governance.run. Requires a signed-in member with review access. Runtime keys, desktop connections, and management tokens cannot make human review decisions.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 4

Field	Type	Description
`annotation_type`Required	`string`	—
`label`Required	`string`	—
`payload`	`object`	—
`created_by`	`string`	Orlo uses the signed-in member identity as the author.

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "annotation_type": "string",
  "label": "string",
  "created_by": "string"
}

Responses

201Trace sample annotation created

application/json

object

Fields 7

Field	Type	Description
`id`Required	`string`	—
`trace_sample_id`Required	`string`	—
`annotation_type`Required	`string`	—
`label`Required	`string`	—
`payload`Required	`object`	—
`created_by`Required	`string \| null`	—
`created_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "string",
  "trace_sample_id": "string",
  "annotation_type": "string",
  "label": "string",
  "created_by": "string",
  "created_at": "string"
}

403PEOPLE_ONLY: sign in with a member account that has review access.

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/trace-samples/{id}/promote-to-dataset

Promote a trace sample to a dataset sample

Required scope: datasets.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`
`id`*	path	`string (uuid)`	id identifies the resource in this request. Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 1

Field	Type	Description
`dataset_id`Required	`string (uuid)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "dataset_id": "11111111-1111-4111-8111-111111111111"
}

Responses

200Trace sample promoted

application/json

object

Fields 37

Field	Type	Description
`trace_sample`	`object`	—
`trace_sample.id`Required	`string`	—
`trace_sample.task_id`Required	`string`	—
`trace_sample.dataset_id`Required	`string \| null`	—
`trace_sample.session_id`Required	`string`	—
`trace_sample.step_uuid`Required	`string \| null`	—
`trace_sample.source`Required	`string`	Allowed: "manual", "policy", "drift", "import".
`trace_sample.status`Required	`string`	Allowed: "candidate", "approved", "rejected", "promoted".
`trace_sample.trace_snapshot`Required	`object`	—
`trace_sample.expected_output`Required	`object \| null`	—
`trace_sample.expected_state_change`Required	`object \| null`	—
`trace_sample.expected_state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`trace_sample.expected_state_change.resource_type`Required	`string \| null`	—
`trace_sample.expected_state_change.resource_id`Required	`string \| null`	—
`trace_sample.expected_state_change.operation`Required	`string \| null`	—
`trace_sample.expected_state_change.before`Required	`object \| null`	—
`trace_sample.expected_state_change.after`Required	`object \| null`	—
`trace_sample.expected_state_change.evidence`Required	`object \| null`	—
`trace_sample.metadata`Required	`object`	—
`trace_sample.created_at`Required	`string`	—
`trace_sample.updated_at`Required	`string`	—
`dataset`	`object`	—
`dataset.id`	`string (uuid)`	—
`dataset.version`	`integer`	—
`dataset.sample_count`	`integer`	—
`dataset.created_at`	`string (date-time)`	—
`dataset.task_id`	`string (uuid)`	—
`dataset.name`	`string`	—
`dataset.parent_dataset_id`	`string (uuid) \| null`	—
`dataset.added_count`	`integer`	—
`dataset.baseline_count`	`integer`	—
`dataset.change_kind`	`string`	—
`dataset.change_mode`	`string`	—
`dataset.redaction_warning`	`string`	Present on a write when credential-like values changed. Inspect saved examples before comparing models.
`dataset.redacted_sample_count`	`integer`	Number of new or copied samples changed by credential protection during this write.
`dataset_sample_id`	`string (uuid) \| null`	—
`already_added`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "trace_sample": {
    "id": "string",
    "task_id": "string",
    "dataset_id": "string",
    "session_id": "string",
    "step_uuid": "string",
    "source": "manual",
    "status": "candidate",
    "expected_state_change": {
      "kind": "none",
      "resource_type": "string",
      "resource_id": "string",
      "operation": "string"
    },
    "created_at": "string",
    "updated_at": "string"
  },
  "dataset": {
    "id": "11111111-1111-4111-8111-111111111111",
    "version": 0,
    "sample_count": 0,
    "created_at": "2026-10-14T12:00:00Z",
    "task_id": "11111111-1111-4111-8111-111111111111",
    "name": "string",
    "parent_dataset_id": "11111111-1111-4111-8111-111111111111",
    "added_count": 0,
    "baseline_count": 0,
    "change_kind": "string",
    "change_mode": "string",
    "redaction_warning": "string",
    "redacted_sample_count": 0
  },
  "dataset_sample_id": "11111111-1111-4111-8111-111111111111",
  "already_added": false
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

GET/v1/agent-approvals/{id}

Read current approval status

Applies elapsed deadlines before returning the approval. Requires agent_governance.read. Does not execute or authorize a tool by itself.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Current approval; Cache-Control: no-store

application/json

object

Fields 17

Field	Type	Description
`id`Required	`string`	—
`session_id`Required	`string`	—
`step_id`Required	`string`	—
`task_id`Required	`string`	—
`policy_reason`Required	`string`	—
`status`Required	`string`	Allowed: "pending", "approved", "rejected", "expired".
`request_payload`Required	`object \| null`	—
`timeout_action`Required	`string \| null`	—
`timeout_at`Required	`string \| null`	—
`escalated_at`Required	`string \| null`	—
`decided_at`Required	`string \| null`	—
`decided_by`Required	`string \| null`	—
`decision_payload`Required	`object \| null`	—
`consumed_at`Required	`string \| null`	—
`consumed_by_step_uuid`Required	`string \| null`	—
`created_at`Required	`string`	—
`updated_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "string",
  "session_id": "string",
  "step_id": "string",
  "task_id": "string",
  "policy_reason": "string",
  "status": "pending",
  "timeout_at": "string",
  "escalated_at": "string",
  "decided_at": "string",
  "decided_by": "string",
  "consumed_at": "string",
  "consumed_by_step_uuid": "string",
  "created_at": "string",
  "updated_at": "string"
}

404APPROVAL_NOT_FOUND in this organization

GET/v1/agent-sessions/{sessionId}/actions/{actionId}/reports

Read outcomes and paginated report history

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`sessionId`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`actionId`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`after`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Successful response

application/json

object

Fields 35

Field	Type	Description
`latest`	`object`	—
`latest.execution`	`object \| null`	—
`latest.execution.report_id`	`string (uuid)`	—
`latest.execution.detail`	`string`	—
`latest.execution.occurred_at`	`string (date-time)`	—
`latest.execution.kind`	`string`	Allowed: "execution", "business".
`latest.execution.outcome`	`string`	—
`latest.execution.criterion`	`string \| null`	—
`latest.execution.duration_ms`	`number \| null`	—
`latest.execution.recorded_at`	`string (date-time)`	—
`latest.execution.reported_by`	`string \| null`	—
`latest.execution.source`	`string`	Allowed: "application_report".
`latest.business`	`object \| null`	—
`latest.business.report_id`	`string (uuid)`	—
`latest.business.detail`	`string`	—
`latest.business.occurred_at`	`string (date-time)`	—
`latest.business.kind`	`string`	Allowed: "execution", "business".
`latest.business.outcome`	`string`	—
`latest.business.criterion`	`string \| null`	—
`latest.business.duration_ms`	`number \| null`	—
`latest.business.recorded_at`	`string (date-time)`	—
`latest.business.reported_by`	`string \| null`	—
`latest.business.source`	`string`	Allowed: "application_report".
`items`	`array<object>`	—
`items[].report_id`	`string (uuid)`	—
`items[].detail`	`string`	—
`items[].occurred_at`	`string (date-time)`	—
`items[].kind`	`string`	Allowed: "execution", "business".
`items[].outcome`	`string`	—
`items[].criterion`	`string \| null`	—
`items[].duration_ms`	`number \| null`	—
`items[].recorded_at`	`string (date-time)`	—
`items[].reported_by`	`string \| null`	—
`items[].source`	`string`	Allowed: "application_report".
`next_cursor`	`string (uuid) \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "latest": {
    "execution": {
      "report_id": "11111111-1111-4111-8111-111111111111",
      "detail": "string",
      "occurred_at": "2026-10-14T12:00:00Z",
      "kind": "execution",
      "outcome": "string",
      "criterion": "string",
      "duration_ms": 0,
      "recorded_at": "2026-10-14T12:00:00Z",
      "reported_by": "string",
      "source": "application_report"
    },
    "business": {
      "report_id": "11111111-1111-4111-8111-111111111111",
      "detail": "string",
      "occurred_at": "2026-10-14T12:00:00Z",
      "kind": "execution",
      "outcome": "string",
      "criterion": "string",
      "duration_ms": 0,
      "recorded_at": "2026-10-14T12:00:00Z",
      "reported_by": "string",
      "source": "application_report"
    }
  },
  "items": [
    {
      "report_id": "11111111-1111-4111-8111-111111111111",
      "detail": "string",
      "occurred_at": "2026-10-14T12:00:00Z",
      "kind": "execution",
      "outcome": "string",
      "criterion": "string",
      "duration_ms": 0,
      "recorded_at": "2026-10-14T12:00:00Z",
      "reported_by": "string",
      "source": "application_report"
    }
  ],
  "next_cursor": "11111111-1111-4111-8111-111111111111"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

POST/v1/agent-sessions/{sessionId}/actions/{actionId}/reports

Append an execution or business outcome

Required scope: agent_governance.run. Reuse reportid and identical content for idempotent retries; changed content returns 409 ACTIONREPORT_CHANGED. Reports may arrive after a run ends and never change permission. Imported traces cannot supply governed action reports.

Parameters

Name	Location	Type	Description
`sessionId`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`
`actionId`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object | object

Fields 12

Field	Type	Description
`(option 1).report_id`Required	`string (uuid)`	—
`(option 1).detail`	`string`	—
`(option 1).occurred_at`	`string (date-time)`	—
`(option 1).kind`Required	`string`	Allowed: "execution".
`(option 1).outcome`Required	`string`	Allowed: "succeeded", "failed", "not_executed", "unknown".
`(option 1).duration_ms`	`number`	Minimum: 0. Maximum: 604800000.
`(option 2).report_id`Required	`string (uuid)`	—
`(option 2).detail`	`string`	—
`(option 2).occurred_at`	`string (date-time)`	—
`(option 2).kind`Required	`string`	Allowed: "business".
`(option 2).outcome`Required	`string`	Allowed: "met", "not_met", "unknown".
`(option 2).criterion`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

{
  "report_id": "11111111-1111-4111-8111-111111111111",
  "kind": "execution",
  "outcome": "succeeded",
  "duration_ms": 135
}

Responses

200Successful response

application/json

object

Fields 3

Field	Type	Description
`report_id`	`string (uuid)`	—
`recorded_at`	`string (date-time)`	—
`source`	`string`	Allowed: "application_report".

Nested fields marked required are required when their parent object is present.

Example

{
  "report_id": "11111111-1111-4111-8111-111111111111",
  "recorded_at": "2026-10-15T12:00:00Z",
  "source": "application_report"
}

400Bad request

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

404Not found

application/json

object

Fields 4

Field	Type	Description
`error`	`string`	—
`message`	`string`	—
`trace_id`	`string`	Request identifier when available; keep it for troubleshooting.
`details`	`object`	Error-specific context. VALIDATION_FAILED returns validation fields here, including status and entries. If a failed attempt also could not be recorded, evidence_recorded is false.

Nested fields marked required are required when their parent object is present.

Example

{
  "error": "INVALID_INPUT",
  "message": "input is required"
}

409ACTION_REPORT_CHANGED: this ID identifies different report content.

Orgs

GET/v1/orgs/judge

Organization judge choice

Required scope: org_config.read.

Responses

200Successful response

application/json

object

Fields 3

Field	Type	Description
`judge_model_id`	`string (uuid) \| null`	—
`second_judge_model_id`	`string (uuid) \| null`	—
`dual_judge`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "judge_model_id": "11111111-1111-4111-8111-111111111111",
  "second_judge_model_id": "11111111-1111-4111-8111-111111111111",
  "dual_judge": false
}

PUT/v1/orgs/judge

Set organization judge

Required scope: org_config.write.

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 3

Field	Type	Description
`judge_model_id`	`string (uuid) \| null`	—
`second_judge_model_id`	`string (uuid) \| null`	—
`dual_judge`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "judge_model_id": "11111111-1111-4111-8111-111111111111",
  "second_judge_model_id": "11111111-1111-4111-8111-111111111111",
  "dual_judge": false
}

Responses

200Successful response

application/json

object

Fields 3

Field	Type	Description
`judge_model_id`	`string (uuid) \| null`	—
`second_judge_model_id`	`string (uuid) \| null`	—
`dual_judge`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "judge_model_id": "11111111-1111-4111-8111-111111111111",
  "second_judge_model_id": "11111111-1111-4111-8111-111111111111",
  "dual_judge": false
}

Skills

GET/v1/skills

List the skills library

Runtime keys can read published, non-retired versions only. Manage drafts, publication, and retirement in the console.

Required scope: skills.read.

Parameters

Name	Location	Type	Description
`before`	query	`string (uuid)`	Use next_cursor from the preceding page. Example: `11111111-1111-4111-8111-111111111111`
`limit`	query	`integer`	— Example: `100`
`q`	query	`string`	Search name, owner, or description. Example: `string`

Responses

200Successful response

application/json

object

Fields 9

Field	Type	Description
`skills`	`array<object>`	—
`skills[].id`	`string (uuid)`	—
`skills[].name`	`string`	—
`skills[].owner`	`string`	—
`skills[].current_version_id`	`string (uuid)`	—
`skills[].published_version_id`	`string (uuid) \| null`	—
`skills[].version`	`integer`	—
`skills[].description`	`string`	—
`next_cursor`	`string (uuid) \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "skills": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "name": "string",
      "owner": "string",
      "current_version_id": "11111111-1111-4111-8111-111111111111",
      "published_version_id": "11111111-1111-4111-8111-111111111111",
      "version": 0,
      "description": "string"
    }
  ],
  "next_cursor": "11111111-1111-4111-8111-111111111111"
}

GET/v1/skills/{id}

A skill with its versions

Runtime keys can read published, non-retired versions only. Manage drafts, publication, and retirement in the console.

Required scope: skills.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 23

Field	Type	Description
`id`	`string (uuid)`	—
`name`	`string`	—
`owner`	`string`	—
`current_version_id`	`string (uuid)`	—
`published_version_id`	`string (uuid) \| null`	—
`version`	`integer`	—
`description`	`string`	—
`current_version`	`object`	—
`current_version.id`	`string (uuid)`	—
`current_version.skill_id`	`string (uuid)`	—
`current_version.name`	`string`	—
`current_version.version`	`integer`	—
`current_version.description`	`string`	—
`current_version.instructions`	`string`	—
`current_version.compatibility`	`string`	—
`current_version.files`	`array<object>`	—
`current_version.files[].path`Required	`string`	—
`current_version.files[].content`Required	`string`	—
`current_version.content_hash`	`string`	—
`current_version.created_at`	`string (date-time)`	—
`current_version.published_at`	`string (date-time) \| null`	—
`current_version.retired_at`	`string (date-time) \| null`	—
`versions`	`array<object>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "owner": "string",
  "current_version_id": "11111111-1111-4111-8111-111111111111",
  "published_version_id": "11111111-1111-4111-8111-111111111111",
  "version": 0,
  "description": "string",
  "current_version": {
    "id": "11111111-1111-4111-8111-111111111111",
    "skill_id": "11111111-1111-4111-8111-111111111111",
    "name": "string",
    "version": 0,
    "description": "string",
    "instructions": "string",
    "compatibility": "string",
    "files": [
      {
        "path": "string",
        "content": "string"
      }
    ],
    "content_hash": "string",
    "created_at": "2026-10-14T12:00:00Z",
    "published_at": "2026-10-14T12:00:00Z",
    "retired_at": "2026-10-14T12:00:00Z"
  },
  "versions": []
}

GET/v1/skills/{id}/versions/{versionId}

One skill version

Runtime keys can read published, non-retired versions only. Manage drafts, publication, and retirement in the console.

Required scope: skills.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`versionId`*	path	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 14

Field	Type	Description
`id`	`string (uuid)`	—
`skill_id`	`string (uuid)`	—
`name`	`string`	—
`version`	`integer`	—
`description`	`string`	—
`instructions`	`string`	—
`compatibility`	`string`	—
`files`	`array<object>`	—
`files[].path`Required	`string`	—
`files[].content`Required	`string`	—
`content_hash`	`string`	—
`created_at`	`string (date-time)`	—
`published_at`	`string (date-time) \| null`	—
`retired_at`	`string (date-time) \| null`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "skill_id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "version": 0,
  "description": "string",
  "instructions": "string",
  "compatibility": "string",
  "files": [
    {
      "path": "string",
      "content": "string"
    }
  ],
  "content_hash": "string",
  "created_at": "2026-10-14T12:00:00Z",
  "published_at": "2026-10-14T12:00:00Z",
  "retired_at": "2026-10-14T12:00:00Z"
}

GET/v1/skills/{id}/versions/{versionId}/package

Published version as SKILL.md plus files

Runtime keys can read published, non-retired versions only. Manage drafts, publication, and retirement in the console.

Required scope: skills.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`versionId`*	path	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 8

Field	Type	Description
`skill_id`	`string (uuid)`	—
`version_id`	`string (uuid)`	—
`name`	`string`	—
`version`	`integer`	—
`content_hash`	`string`	—
`files`	`array<object>`	—
`files[].path`Required	`string`	—
`files[].content`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "skill_id": "11111111-1111-4111-8111-111111111111",
  "version_id": "11111111-1111-4111-8111-111111111111",
  "name": "string",
  "version": 0,
  "content_hash": "string",
  "files": [
    {
      "path": "string",
      "content": "string"
    }
  ]
}

GET/v1/skills/{id}/versions/{versionId}/usage

Tasks, comparisons, and runs that use the version

Runtime keys can read published, non-retired versions only. Manage drafts, publication, and retirement in the console.

Required scope: skills.read.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`versionId`*	path	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 3

Field	Type	Description
`tasks`	`array<object>`	—
`comparisons`	`array<object>`	—
`agent_runs`	`array<object>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "tasks": [],
  "comparisons": [],
  "agent_runs": []
}

Quality-signals

GET/v1/quality-signals

List quality signals

Required scope: monitoring.read.

Parameters

Name	Location	Type	Description
`status`	query	`string`	— Example: `string`

Responses

200Successful response

application/json

object

Fields 1

Field	Type	Description
`signals`	`array<object>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "signals": []
}

POST/v1/quality-signals/{id}/dismiss

Dismiss a signal

Requires an all-scopes runtime key. Prefer dismissing signals in the console.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Responses

200Successful response

application/json

object

Fields 1

Field	Type	Description
`signal`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{}

Notification-endpoints

GET/v1/notification-endpoints

List notification endpoints

Required scope: org_config.read.

Responses

200Successful response

application/json

object

Fields 8

Field	Type	Description
`endpoints`	`array<object>`	—
`endpoints[].id`	`string (uuid)`	—
`endpoints[].url_hint`	`string`	Masked receiver address; the full URL and signing secret are not returned on reads.
`endpoints[].events`	`array<string>`	—
`endpoints[].active`	`boolean`	—
`endpoints[].created_by`	`string \| null`	—
`endpoints[].created_at`	`string (date-time)`	—
`email_notifier`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "endpoints": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "url_hint": "string",
      "events": [
        "string"
      ],
      "active": false,
      "created_by": "string",
      "created_at": "2026-10-14T12:00:00Z"
    }
  ],
  "email_notifier": false
}

POST/v1/notification-endpoints

Add a webhook; returns its secret once

Parameters

Name	Location	Type	Description
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

Body required

object

Fields 2

Field	Type	Description
`url`Required	`string (uri)`	—
`events`	`array<string>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "url": "string",
  "events": [
    "approval.requested"
  ]
}

Responses

201Created; keep the signing secret securely. It is returned only here.

application/json

object

Fields 8

Field	Type	Description
`endpoint`	`object`	—
`endpoint.id`	`string (uuid)`	—
`endpoint.events`	`array<string>`	—
`endpoint.active`	`boolean`	—
`endpoint.created_by`	`string \| null`	—
`endpoint.created_at`	`string (date-time)`	—
`endpoint.url`	`string (uri)`	—
`secret`	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "endpoint": {
    "id": "11111111-1111-4111-8111-111111111111",
    "events": [
      "string"
    ],
    "active": false,
    "created_by": "string",
    "created_at": "2026-10-14T12:00:00Z",
    "url": "string"
  },
  "secret": "string"
}

DELETE/v1/notification-endpoints/{id}

Remove a notification endpoint

Required scope: org_config.write.

Parameters

Name	Location	Type	Description
`id`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Responses

204Deleted; no response body

Notifications

PATCH/v1/notification-endpoints/{id}

Update webhook event subscriptions

Replaces selected events without changing the address or signing secret.

Parameters

Name	Location	Type	Description
`id`*	path	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Request Body

Content-Type: application/json

Body required

object

Fields 1

Field	Type	Description
`events`Required	`array<string>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "events": [
    "approval.requested"
  ]
}

Responses

200Updated endpoint with masked address and no secret

application/json

object

Fields 6

Field	Type	Description
`id`	`string (uuid)`	—
`url_hint`	`string`	Masked receiver address; the full URL and signing secret are not returned on reads.
`events`	`array<string>`	—
`active`	`boolean`	—
`created_by`	`string \| null`	—
`created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "id": "11111111-1111-4111-8111-111111111111",
  "url_hint": "string",
  "events": [
    "string"
  ],
  "active": false,
  "created_by": "string",
  "created_at": "2026-10-14T12:00:00Z"
}

400INVALID_WEBHOOK_EVENTS

404Endpoint not found in this organization

Audit-events

GET/v1/audit-events

List audit events

Required scope: audit.read.

Parameters

Name	Location	Type	Description
`limit`	query	`integer`	— Example: `0`
`before`	query	`string (date-time)`	— Example: `2026-10-14T12:00:00Z`
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Successful response

application/json

object

Fields 1

Field	Type	Description
`events`	`array<object>`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "events": []
}

Agent-steps

GET/v1/agent-steps

Steps across runs since a time

Required scope: agent_governance.read.

Parameters

Name	Location	Type	Description
`since`	query	`string (date-time)`	— Example: `2026-10-14T12:00:00Z`
`limit`	query	`integer`	— Example: `2000`
`task_id`	query	`string (uuid)`	— Example: `11111111-1111-4111-8111-111111111111`

Responses

200Successful response

application/json

object

Fields 2

Field	Type	Description
`steps`	`array<object>`	—
`limit`	`integer`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "steps": [],
  "limit": 0
}

Agent-sessions

POST/v1/agent-sessions/{sessionId}/steps/{stepId}/add-to-standard

Add a step to the task’s examples

Required scope: datasets.write.

Parameters

Name	Location	Type	Description
`sessionId`*	path	`string`	— Example: `string`
`stepId`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Responses

200This step was already added

application/json

object

Fields 37

Field	Type	Description
`trace_sample`	`object`	—
`trace_sample.id`Required	`string`	—
`trace_sample.task_id`Required	`string`	—
`trace_sample.dataset_id`Required	`string \| null`	—
`trace_sample.session_id`Required	`string`	—
`trace_sample.step_uuid`Required	`string \| null`	—
`trace_sample.source`Required	`string`	Allowed: "manual", "policy", "drift", "import".
`trace_sample.status`Required	`string`	Allowed: "candidate", "approved", "rejected", "promoted".
`trace_sample.trace_snapshot`Required	`object`	—
`trace_sample.expected_output`Required	`object \| null`	—
`trace_sample.expected_state_change`Required	`object \| null`	—
`trace_sample.expected_state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`trace_sample.expected_state_change.resource_type`Required	`string \| null`	—
`trace_sample.expected_state_change.resource_id`Required	`string \| null`	—
`trace_sample.expected_state_change.operation`Required	`string \| null`	—
`trace_sample.expected_state_change.before`Required	`object \| null`	—
`trace_sample.expected_state_change.after`Required	`object \| null`	—
`trace_sample.expected_state_change.evidence`Required	`object \| null`	—
`trace_sample.metadata`Required	`object`	—
`trace_sample.created_at`Required	`string`	—
`trace_sample.updated_at`Required	`string`	—
`dataset`	`object`	—
`dataset.id`	`string (uuid)`	—
`dataset.version`	`integer`	—
`dataset.sample_count`	`integer`	—
`dataset.created_at`	`string (date-time)`	—
`dataset.task_id`	`string (uuid)`	—
`dataset.name`	`string`	—
`dataset.parent_dataset_id`	`string (uuid) \| null`	—
`dataset.added_count`	`integer`	—
`dataset.baseline_count`	`integer`	—
`dataset.change_kind`	`string`	—
`dataset.change_mode`	`string`	—
`dataset.redaction_warning`	`string`	Present on a write when credential-like values changed. Inspect saved examples before comparing models.
`dataset.redacted_sample_count`	`integer`	Number of new or copied samples changed by credential protection during this write.
`dataset_sample_id`	`string (uuid) \| null`	—
`already_added`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "trace_sample": {
    "id": "string",
    "task_id": "string",
    "dataset_id": "string",
    "session_id": "string",
    "step_uuid": "string",
    "source": "manual",
    "status": "candidate",
    "expected_state_change": {
      "kind": "none",
      "resource_type": "string",
      "resource_id": "string",
      "operation": "string"
    },
    "created_at": "string",
    "updated_at": "string"
  },
  "dataset": {
    "id": "11111111-1111-4111-8111-111111111111",
    "version": 0,
    "sample_count": 0,
    "created_at": "2026-10-14T12:00:00Z",
    "task_id": "11111111-1111-4111-8111-111111111111",
    "name": "string",
    "parent_dataset_id": "11111111-1111-4111-8111-111111111111",
    "added_count": 0,
    "baseline_count": 0,
    "change_kind": "string",
    "change_mode": "string",
    "redaction_warning": "string",
    "redacted_sample_count": 0
  },
  "dataset_sample_id": "11111111-1111-4111-8111-111111111111",
  "already_added": false
}

201Added to a new dataset version

application/json

object

Fields 37

Field	Type	Description
`trace_sample`	`object`	—
`trace_sample.id`Required	`string`	—
`trace_sample.task_id`Required	`string`	—
`trace_sample.dataset_id`Required	`string \| null`	—
`trace_sample.session_id`Required	`string`	—
`trace_sample.step_uuid`Required	`string \| null`	—
`trace_sample.source`Required	`string`	Allowed: "manual", "policy", "drift", "import".
`trace_sample.status`Required	`string`	Allowed: "candidate", "approved", "rejected", "promoted".
`trace_sample.trace_snapshot`Required	`object`	—
`trace_sample.expected_output`Required	`object \| null`	—
`trace_sample.expected_state_change`Required	`object \| null`	—
`trace_sample.expected_state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`trace_sample.expected_state_change.resource_type`Required	`string \| null`	—
`trace_sample.expected_state_change.resource_id`Required	`string \| null`	—
`trace_sample.expected_state_change.operation`Required	`string \| null`	—
`trace_sample.expected_state_change.before`Required	`object \| null`	—
`trace_sample.expected_state_change.after`Required	`object \| null`	—
`trace_sample.expected_state_change.evidence`Required	`object \| null`	—
`trace_sample.metadata`Required	`object`	—
`trace_sample.created_at`Required	`string`	—
`trace_sample.updated_at`Required	`string`	—
`dataset`	`object`	—
`dataset.id`	`string (uuid)`	—
`dataset.version`	`integer`	—
`dataset.sample_count`	`integer`	—
`dataset.created_at`	`string (date-time)`	—
`dataset.task_id`	`string (uuid)`	—
`dataset.name`	`string`	—
`dataset.parent_dataset_id`	`string (uuid) \| null`	—
`dataset.added_count`	`integer`	—
`dataset.baseline_count`	`integer`	—
`dataset.change_kind`	`string`	—
`dataset.change_mode`	`string`	—
`dataset.redaction_warning`	`string`	Present on a write when credential-like values changed. Inspect saved examples before comparing models.
`dataset.redacted_sample_count`	`integer`	Number of new or copied samples changed by credential protection during this write.
`dataset_sample_id`	`string (uuid) \| null`	—
`already_added`	`boolean`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "trace_sample": {
    "id": "string",
    "task_id": "string",
    "dataset_id": "string",
    "session_id": "string",
    "step_uuid": "string",
    "source": "manual",
    "status": "candidate",
    "expected_state_change": {
      "kind": "none",
      "resource_type": "string",
      "resource_id": "string",
      "operation": "string"
    },
    "created_at": "string",
    "updated_at": "string"
  },
  "dataset": {
    "id": "11111111-1111-4111-8111-111111111111",
    "version": 0,
    "sample_count": 0,
    "created_at": "2026-10-14T12:00:00Z",
    "task_id": "11111111-1111-4111-8111-111111111111",
    "name": "string",
    "parent_dataset_id": "11111111-1111-4111-8111-111111111111",
    "added_count": 0,
    "baseline_count": 0,
    "change_kind": "string",
    "change_mode": "string",
    "redaction_warning": "string",
    "redacted_sample_count": 0
  },
  "dataset_sample_id": "11111111-1111-4111-8111-111111111111",
  "already_added": false
}

POST/v1/agent-sessions/{sessionId}/steps/{stepId}/promote-to-trace-sample

Save a step as a trace sample

Required scope: agent_governance.run.

Parameters

Name	Location	Type	Description
`sessionId`*	path	`string`	— Example: `string`
`stepId`*	path	`string`	— Example: `string`
`Idempotency-Key`	header	`string`	Optional key for retry-safe mutation replay. Example: `request-2026-10-14-001`

Request Body

Content-Type: application/json

object

Fields 6

Field	Type	Description
`source`	`string`	—
`title`	`string`	—
`notes`	`string`	—
`expected_output`	`object \| null`	—
`expected_state_change`	`object \| null`	—
`metadata`	`object`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "source": "string",
  "title": "string",
  "notes": "string"
}

Responses

200Successful response

application/json

object

Fields 21

Field	Type	Description
`trace_sample`	`object`	—
`trace_sample.id`Required	`string`	—
`trace_sample.task_id`Required	`string`	—
`trace_sample.dataset_id`Required	`string \| null`	—
`trace_sample.session_id`Required	`string`	—
`trace_sample.step_uuid`Required	`string \| null`	—
`trace_sample.source`Required	`string`	Allowed: "manual", "policy", "drift", "import".
`trace_sample.status`Required	`string`	Allowed: "candidate", "approved", "rejected", "promoted".
`trace_sample.trace_snapshot`Required	`object`	—
`trace_sample.expected_output`Required	`object \| null`	—
`trace_sample.expected_state_change`Required	`object \| null`	—
`trace_sample.expected_state_change.kind`Required	`string`	Allowed: "none", "proposed", "observed", "confirmed".
`trace_sample.expected_state_change.resource_type`Required	`string \| null`	—
`trace_sample.expected_state_change.resource_id`Required	`string \| null`	—
`trace_sample.expected_state_change.operation`Required	`string \| null`	—
`trace_sample.expected_state_change.before`Required	`object \| null`	—
`trace_sample.expected_state_change.after`Required	`object \| null`	—
`trace_sample.expected_state_change.evidence`Required	`object \| null`	—
`trace_sample.metadata`Required	`object`	—
`trace_sample.created_at`Required	`string`	—
`trace_sample.updated_at`Required	`string`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "trace_sample": {
    "id": "string",
    "task_id": "string",
    "dataset_id": "string",
    "session_id": "string",
    "step_uuid": "string",
    "source": "manual",
    "status": "candidate",
    "expected_state_change": {
      "kind": "none",
      "resource_type": "string",
      "resource_id": "string",
      "operation": "string"
    },
    "created_at": "string",
    "updated_at": "string"
  }
}

Inference-logs

GET/v1/inference-logs

List answers (task_id, deployment_id, trace_id, limit)

Required scope: inference_logs.read.

Parameters

Name	Location	Type	Description
`task_id`	query	`string (uuid)`	Filter by task_id. Example: `11111111-1111-4111-8111-111111111111`
`deployment_id`	query	`string (uuid)`	Filter by deployment_id. Example: `11111111-1111-4111-8111-111111111111`
`trace_id`	query	`string (uuid)`	Filter by trace_id. Example: `11111111-1111-4111-8111-111111111111`
`limit`	query	`integer`	— Example: `50`

Responses

200OK

application/json

object

Fields 25

Field	Type	Description
`inference_logs`	`array<object>`	—
`inference_logs[].id`	`string (uuid)`	—
`inference_logs[].trace_id`	`string (uuid)`	—
`inference_logs[].task_id`	`string (uuid)`	—
`inference_logs[].deployment_id`	`string (uuid)`	—
`inference_logs[].task_version_id`	`string (uuid)`	—
`inference_logs[].model_id`	`string (uuid)`	—
`inference_logs[].task_name`	`string`	—
`inference_logs[].model_name`	`string`	—
`inference_logs[].release_model_name`	`string`	—
`inference_logs[].deployment_version`	`integer`	—
`inference_logs[].task_version_number`	`integer`	—
`inference_logs[].latency_ms`	`integer`	—
`inference_logs[].token_count_input`	`integer`	—
`inference_logs[].token_count_output`	`integer`	—
`inference_logs[].release_live`	`boolean`	—
`inference_logs[].validation_result`	`object`	—
`inference_logs[].validation_result.valid`Required	`boolean`	—
`inference_logs[].validation_result.warnings`Required	`array<string>`	—
`inference_logs[].validation_result.score`Required	`number`	—
`inference_logs[].validation_result.abstain`Required	`boolean`	—
`inference_logs[].validation_result.escalate`Required	`boolean`	—
`inference_logs[].validation_result.status`	`string`	An indeterminate required check blocks the answer with abstain true, including under warn behavior. Allowed: "passed", "failed", "indeterminate".
`inference_logs[].retrieval_attribution`	`object \| null`	—
`inference_logs[].created_at`	`string (date-time)`	—

Nested fields marked required are required when their parent object is present.

Example

Illustrative values generated from the schema.

{
  "inference_logs": [
    {
      "id": "11111111-1111-4111-8111-111111111111",
      "trace_id": "11111111-1111-4111-8111-111111111111",
      "task_id": "11111111-1111-4111-8111-111111111111",
      "deployment_id": "11111111-1111-4111-8111-111111111111",
      "task_version_id": "11111111-1111-4111-8111-111111111111",
      "model_id": "11111111-1111-4111-8111-111111111111",
      "task_name": "string",
      "model_name": "string",
      "release_model_name": "string",
      "deployment_version": 0,
      "task_version_number": 0,
      "latency_ms": 0,
      "token_count_input": 0,
      "token_count_output": 0,
      "release_live": false,
      "validation_result": {
        "valid": false,
        "warnings": [
          "string"
        ],
        "score": 0,
        "abstain": false,
        "escalate": false,
        "status": "passed"
      },
      "created_at": "2026-10-14T12:00:00Z"
    }
  ]
}