> ## Documentation Index
> Fetch the complete documentation index at: https://docs.korve.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# projectOperator

> Durable project operations with typed Korve tools, persistent evidence, resumable events, and human approval.

Durable project operations with typed Korve tools, persistent evidence, resumable events, and human approval.

## projectOperator.listThreads

List persistent project operator threads, newest first.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/operator/threads
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/operator/threads" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description               |
| ------ | ------------------------- |
| `200`  | Project operator threads. |

### Response body (200)

An array of objects with these fields:

| Field                           | Type           | Description                                                                 |
| ------------------------------- | -------------- | --------------------------------------------------------------------------- |
| `id`                            | string         | Format: `uuid`.                                                             |
| `projectId`                     | string         | Format: `uuid`.                                                             |
| `title`                         | string         | —                                                                           |
| `deploymentId`                  | string or null | Format: `uuid`.                                                             |
| `createdAt`                     | string         | Format: `date-time`.                                                        |
| `updatedAt`                     | string         | Format: `date-time`.                                                        |
| `runs`                          | object\[]      | —                                                                           |
| `runs[].id`                     | string         | Format: `uuid`.                                                             |
| `runs[].threadId`               | string         | Format: `uuid`.                                                             |
| `runs[].status`                 | string         | One of: `queued`, `running`, `waiting_for_approval`, `succeeded`, `failed`. |
| `runs[].input`                  | string         | —                                                                           |
| `runs[].output`                 | string or null | —                                                                           |
| `runs[].error`                  | string or null | —                                                                           |
| `runs[].startedAt`              | string or null | Format: `date-time`.                                                        |
| `runs[].finishedAt`             | string or null | Format: `date-time`.                                                        |
| `runs[].createdAt`              | string         | Format: `date-time`.                                                        |
| `runs[].actions`                | object\[]      | —                                                                           |
| `runs[].actions[].id`           | string         | Format: `uuid`.                                                             |
| `runs[].actions[].runId`        | string         | Format: `uuid`.                                                             |
| `runs[].actions[].operationId`  | string         | —                                                                           |
| `runs[].actions[].risk`         | string         | One of: `write`, `dangerous`, `destructive`.                                |
| `runs[].actions[].status`       | string         | One of: `pending`, `rejected`, `running`, `succeeded`, `failed`.            |
| `runs[].actions[].version`      | integer        | —                                                                           |
| `runs[].actions[].preview`      | object         | —                                                                           |
| `runs[].actions[].result`       | object         | —                                                                           |
| `runs[].actions[].error`        | string or null | —                                                                           |
| `runs[].actions[].decidedAt`    | string or null | Format: `date-time`.                                                        |
| `runs[].actions[].executedAt`   | string or null | Format: `date-time`.                                                        |
| `runs[].actions[].createdAt`    | string         | Format: `date-time`.                                                        |
| `runs[].evidence`               | object\[]      | —                                                                           |
| `runs[].evidence[].id`          | string         | Format: `uuid`.                                                             |
| `runs[].evidence[].runId`       | string         | Format: `uuid`.                                                             |
| `runs[].evidence[].actionId`    | string or null | Format: `uuid`.                                                             |
| `runs[].evidence[].kind`        | string         | One of: `observation`, `verification`, `rollback`.                          |
| `runs[].evidence[].operationId` | string or null | —                                                                           |
| `runs[].evidence[].summary`     | string         | —                                                                           |
| `runs[].evidence[].data`        | object         | —                                                                           |
| `runs[].evidence[].createdAt`   | string         | Format: `date-time`.                                                        |

## projectOperator.createThread

Create a persistent project operator thread, optionally seeded from one deployment.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/operator/threads
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `write`

### Request body

| Field          | Type   | Required | Description     |
| -------------- | ------ | -------- | --------------- |
| `title`        | string | Yes      | —               |
| `deploymentId` | string | No       | Format: `uuid`. |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/operator/threads" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "title": "example"
}'
```

### Responses

| Status | Description                         |
| ------ | ----------------------------------- |
| `201`  | Created thread.                     |
| `404`  | No such project or seed deployment. |

### Response body (201)

| Field                           | Type           | Description                                                                 |
| ------------------------------- | -------------- | --------------------------------------------------------------------------- |
| `id`                            | string         | Format: `uuid`.                                                             |
| `projectId`                     | string         | Format: `uuid`.                                                             |
| `title`                         | string         | —                                                                           |
| `deploymentId`                  | string or null | Format: `uuid`.                                                             |
| `createdAt`                     | string         | Format: `date-time`.                                                        |
| `updatedAt`                     | string         | Format: `date-time`.                                                        |
| `runs`                          | object\[]      | —                                                                           |
| `runs[].id`                     | string         | Format: `uuid`.                                                             |
| `runs[].threadId`               | string         | Format: `uuid`.                                                             |
| `runs[].status`                 | string         | One of: `queued`, `running`, `waiting_for_approval`, `succeeded`, `failed`. |
| `runs[].input`                  | string         | —                                                                           |
| `runs[].output`                 | string or null | —                                                                           |
| `runs[].error`                  | string or null | —                                                                           |
| `runs[].startedAt`              | string or null | Format: `date-time`.                                                        |
| `runs[].finishedAt`             | string or null | Format: `date-time`.                                                        |
| `runs[].createdAt`              | string         | Format: `date-time`.                                                        |
| `runs[].actions`                | object\[]      | —                                                                           |
| `runs[].actions[].id`           | string         | Format: `uuid`.                                                             |
| `runs[].actions[].runId`        | string         | Format: `uuid`.                                                             |
| `runs[].actions[].operationId`  | string         | —                                                                           |
| `runs[].actions[].risk`         | string         | One of: `write`, `dangerous`, `destructive`.                                |
| `runs[].actions[].status`       | string         | One of: `pending`, `rejected`, `running`, `succeeded`, `failed`.            |
| `runs[].actions[].version`      | integer        | —                                                                           |
| `runs[].actions[].preview`      | object         | —                                                                           |
| `runs[].actions[].result`       | object         | —                                                                           |
| `runs[].actions[].error`        | string or null | —                                                                           |
| `runs[].actions[].decidedAt`    | string or null | Format: `date-time`.                                                        |
| `runs[].actions[].executedAt`   | string or null | Format: `date-time`.                                                        |
| `runs[].actions[].createdAt`    | string         | Format: `date-time`.                                                        |
| `runs[].evidence`               | object\[]      | —                                                                           |
| `runs[].evidence[].id`          | string         | Format: `uuid`.                                                             |
| `runs[].evidence[].runId`       | string         | Format: `uuid`.                                                             |
| `runs[].evidence[].actionId`    | string or null | Format: `uuid`.                                                             |
| `runs[].evidence[].kind`        | string         | One of: `observation`, `verification`, `rollback`.                          |
| `runs[].evidence[].operationId` | string or null | —                                                                           |
| `runs[].evidence[].summary`     | string         | —                                                                           |
| `runs[].evidence[].data`        | object         | —                                                                           |
| `runs[].evidence[].createdAt`   | string         | Format: `date-time`.                                                        |

## projectOperator.getThread

Get a persistent thread with its runs, evidence, and actions.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/operator/threads/{threadId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/operator/threads/$THREAD_ID" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                     |
| ------ | ------------------------------- |
| `200`  | Operator thread.                |
| `404`  | No such thread in this project. |

### Response body (200)

| Field                           | Type           | Description                                                                 |
| ------------------------------- | -------------- | --------------------------------------------------------------------------- |
| `id`                            | string         | Format: `uuid`.                                                             |
| `projectId`                     | string         | Format: `uuid`.                                                             |
| `title`                         | string         | —                                                                           |
| `deploymentId`                  | string or null | Format: `uuid`.                                                             |
| `createdAt`                     | string         | Format: `date-time`.                                                        |
| `updatedAt`                     | string         | Format: `date-time`.                                                        |
| `runs`                          | object\[]      | —                                                                           |
| `runs[].id`                     | string         | Format: `uuid`.                                                             |
| `runs[].threadId`               | string         | Format: `uuid`.                                                             |
| `runs[].status`                 | string         | One of: `queued`, `running`, `waiting_for_approval`, `succeeded`, `failed`. |
| `runs[].input`                  | string         | —                                                                           |
| `runs[].output`                 | string or null | —                                                                           |
| `runs[].error`                  | string or null | —                                                                           |
| `runs[].startedAt`              | string or null | Format: `date-time`.                                                        |
| `runs[].finishedAt`             | string or null | Format: `date-time`.                                                        |
| `runs[].createdAt`              | string         | Format: `date-time`.                                                        |
| `runs[].actions`                | object\[]      | —                                                                           |
| `runs[].actions[].id`           | string         | Format: `uuid`.                                                             |
| `runs[].actions[].runId`        | string         | Format: `uuid`.                                                             |
| `runs[].actions[].operationId`  | string         | —                                                                           |
| `runs[].actions[].risk`         | string         | One of: `write`, `dangerous`, `destructive`.                                |
| `runs[].actions[].status`       | string         | One of: `pending`, `rejected`, `running`, `succeeded`, `failed`.            |
| `runs[].actions[].version`      | integer        | —                                                                           |
| `runs[].actions[].preview`      | object         | —                                                                           |
| `runs[].actions[].result`       | object         | —                                                                           |
| `runs[].actions[].error`        | string or null | —                                                                           |
| `runs[].actions[].decidedAt`    | string or null | Format: `date-time`.                                                        |
| `runs[].actions[].executedAt`   | string or null | Format: `date-time`.                                                        |
| `runs[].actions[].createdAt`    | string         | Format: `date-time`.                                                        |
| `runs[].evidence`               | object\[]      | —                                                                           |
| `runs[].evidence[].id`          | string         | Format: `uuid`.                                                             |
| `runs[].evidence[].runId`       | string         | Format: `uuid`.                                                             |
| `runs[].evidence[].actionId`    | string or null | Format: `uuid`.                                                             |
| `runs[].evidence[].kind`        | string         | One of: `observation`, `verification`, `rollback`.                          |
| `runs[].evidence[].operationId` | string or null | —                                                                           |
| `runs[].evidence[].summary`     | string         | —                                                                           |
| `runs[].evidence[].data`        | object         | —                                                                           |
| `runs[].evidence[].createdAt`   | string         | Format: `date-time`.                                                        |

## projectOperator.createRun

Run a follow-up through the deterministic project orchestrator using only the curated typed Korve operation catalog. JSON waits for persistence; text/event-stream emits events that are also resumable from the events endpoint.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/operator/threads/{threadId}/runs
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `write`

### Request body

| Field     | Type   | Required | Description |
| --------- | ------ | -------- | ----------- |
| `message` | string | Yes      | —           |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/operator/threads/$THREAD_ID/runs" \
  -H "Authorization: Bearer korve_..." \
  -H "Content-Type: application/json" \
  -d '{
  "message": "example"
}'
```

### Responses

| Status | Description                                              |
| ------ | -------------------------------------------------------- |
| `201`  | Persisted run.                                           |
| `404`  | No such thread in this project.                          |
| `422`  | Invalid follow-up.                                       |
| `502`  | The configured model runtime could not complete the run. |

### Response body (201)

| Field                    | Type           | Description                                                                 |
| ------------------------ | -------------- | --------------------------------------------------------------------------- |
| `id`                     | string         | Format: `uuid`.                                                             |
| `threadId`               | string         | Format: `uuid`.                                                             |
| `status`                 | string         | One of: `queued`, `running`, `waiting_for_approval`, `succeeded`, `failed`. |
| `input`                  | string         | —                                                                           |
| `output`                 | string or null | —                                                                           |
| `error`                  | string or null | —                                                                           |
| `startedAt`              | string or null | Format: `date-time`.                                                        |
| `finishedAt`             | string or null | Format: `date-time`.                                                        |
| `createdAt`              | string         | Format: `date-time`.                                                        |
| `actions`                | object\[]      | —                                                                           |
| `actions[].id`           | string         | Format: `uuid`.                                                             |
| `actions[].runId`        | string         | Format: `uuid`.                                                             |
| `actions[].operationId`  | string         | —                                                                           |
| `actions[].risk`         | string         | One of: `write`, `dangerous`, `destructive`.                                |
| `actions[].status`       | string         | One of: `pending`, `rejected`, `running`, `succeeded`, `failed`.            |
| `actions[].version`      | integer        | —                                                                           |
| `actions[].preview`      | object         | —                                                                           |
| `actions[].result`       | object         | —                                                                           |
| `actions[].error`        | string or null | —                                                                           |
| `actions[].decidedAt`    | string or null | Format: `date-time`.                                                        |
| `actions[].executedAt`   | string or null | Format: `date-time`.                                                        |
| `actions[].createdAt`    | string         | Format: `date-time`.                                                        |
| `evidence`               | object\[]      | —                                                                           |
| `evidence[].id`          | string         | Format: `uuid`.                                                             |
| `evidence[].runId`       | string         | Format: `uuid`.                                                             |
| `evidence[].actionId`    | string or null | Format: `uuid`.                                                             |
| `evidence[].kind`        | string         | One of: `observation`, `verification`, `rollback`.                          |
| `evidence[].operationId` | string or null | —                                                                           |
| `evidence[].summary`     | string         | —                                                                           |
| `evidence[].data`        | object         | —                                                                           |
| `evidence[].createdAt`   | string         | Format: `date-time`.                                                        |

## projectOperator.getRun

Get one durable run with actions and evidence.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/operator/threads/{threadId}/runs/{runId}
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/operator/threads/$THREAD_ID/runs/$RUN_ID" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                 |
| ------ | --------------------------- |
| `200`  | Operator run.               |
| `404`  | No such run in this thread. |

### Response body (200)

| Field                    | Type           | Description                                                                 |
| ------------------------ | -------------- | --------------------------------------------------------------------------- |
| `id`                     | string         | Format: `uuid`.                                                             |
| `threadId`               | string         | Format: `uuid`.                                                             |
| `status`                 | string         | One of: `queued`, `running`, `waiting_for_approval`, `succeeded`, `failed`. |
| `input`                  | string         | —                                                                           |
| `output`                 | string or null | —                                                                           |
| `error`                  | string or null | —                                                                           |
| `startedAt`              | string or null | Format: `date-time`.                                                        |
| `finishedAt`             | string or null | Format: `date-time`.                                                        |
| `createdAt`              | string         | Format: `date-time`.                                                        |
| `actions`                | object\[]      | —                                                                           |
| `actions[].id`           | string         | Format: `uuid`.                                                             |
| `actions[].runId`        | string         | Format: `uuid`.                                                             |
| `actions[].operationId`  | string         | —                                                                           |
| `actions[].risk`         | string         | One of: `write`, `dangerous`, `destructive`.                                |
| `actions[].status`       | string         | One of: `pending`, `rejected`, `running`, `succeeded`, `failed`.            |
| `actions[].version`      | integer        | —                                                                           |
| `actions[].preview`      | object         | —                                                                           |
| `actions[].result`       | object         | —                                                                           |
| `actions[].error`        | string or null | —                                                                           |
| `actions[].decidedAt`    | string or null | Format: `date-time`.                                                        |
| `actions[].executedAt`   | string or null | Format: `date-time`.                                                        |
| `actions[].createdAt`    | string         | Format: `date-time`.                                                        |
| `evidence`               | object\[]      | —                                                                           |
| `evidence[].id`          | string         | Format: `uuid`.                                                             |
| `evidence[].runId`       | string         | Format: `uuid`.                                                             |
| `evidence[].actionId`    | string or null | Format: `uuid`.                                                             |
| `evidence[].kind`        | string         | One of: `observation`, `verification`, `rollback`.                          |
| `evidence[].operationId` | string or null | —                                                                           |
| `evidence[].summary`     | string         | —                                                                           |
| `evidence[].data`        | object         | —                                                                           |
| `evidence[].createdAt`   | string         | Format: `date-time`.                                                        |

## projectOperator.listEvents

Resume a run event feed by requesting events after the last durable cursor. Clients may poll without losing deltas.

```text theme={null}
GET /v1/orgs/{orgId}/projects/{projectId}/operator/threads/{threadId}/events
```

* **Auth:** Organization API key (`Authorization: Bearer korve_...`) or dashboard session.
* **Minimum role:** `member`
* **Risk:** `read`

### Query parameters

| Name    | Type    | Required | Description |
| ------- | ------- | -------- | ----------- |
| `after` | integer | No       | —           |
| `limit` | integer | No       | —           |

### Example

```bash theme={null}
curl "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/operator/threads/$THREAD_ID/events?after=0" \
  -H "Authorization: Bearer korve_..."
```

### Responses

| Status | Description                                 |
| ------ | ------------------------------------------- |
| `200`  | Ordered durable events and the next cursor. |

### Response body (200)

| Field                | Type           | Description                                                                                                     |
| -------------------- | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `events`             | object\[]      | —                                                                                                               |
| `events[].cursor`    | integer        | —                                                                                                               |
| `events[].id`        | string         | Format: `uuid`.                                                                                                 |
| `events[].runId`     | string or null | Format: `uuid`.                                                                                                 |
| `events[].kind`      | string         | One of: `run_started`, `status`, `text_delta`, `tool_result`, `action_required`, `run_completed`, `run_failed`. |
| `events[].payload`   | object         | —                                                                                                               |
| `events[].createdAt` | string         | Format: `date-time`.                                                                                            |
| `nextCursor`         | integer        | —                                                                                                               |

## projectOperator.decideAction

Approve or reject one version-bound, one-use action. Session-only approval rechecks current RBAC and billing; accepted asynchronous work remains running until observed terminal verification succeeds or fails.

```text theme={null}
POST /v1/orgs/{orgId}/projects/{projectId}/operator/threads/{threadId}/actions/{actionId}
```

* **Auth:** Dashboard session only — organization API keys are rejected.
* **Minimum role:** `member`
* **Billing:** requires active organization billing — returns `402` otherwise.
* **Risk:** `dangerous` · sensitive (elevated blast radius)

### Request body

| Field           | Type    | Required | Description                  |
| --------------- | ------- | -------- | ---------------------------- |
| `decision`      | string  | Yes      | One of: `approve`, `reject`. |
| `actionVersion` | integer | Yes      | —                            |

### Example

```bash theme={null}
curl -X POST "https://api.korve.dev/v1/orgs/$ORG_ID/projects/$PROJECT_ID/operator/threads/$THREAD_ID/actions/$ACTION_ID" \
  -b "$SESSION" \
  -H "Content-Type: application/json" \
  -d '{
  "decision": "approve",
  "actionVersion": 1
}'
```

### Responses

| Status | Description                                        |
| ------ | -------------------------------------------------- |
| `200`  | Updated run with audited result.                   |
| `403`  | Current role cannot execute the target operation.  |
| `404`  | No such action in this project thread.             |
| `409`  | Action was already decided or its version changed. |

### Response body (200)

| Field                    | Type           | Description                                                                 |
| ------------------------ | -------------- | --------------------------------------------------------------------------- |
| `id`                     | string         | Format: `uuid`.                                                             |
| `threadId`               | string         | Format: `uuid`.                                                             |
| `status`                 | string         | One of: `queued`, `running`, `waiting_for_approval`, `succeeded`, `failed`. |
| `input`                  | string         | —                                                                           |
| `output`                 | string or null | —                                                                           |
| `error`                  | string or null | —                                                                           |
| `startedAt`              | string or null | Format: `date-time`.                                                        |
| `finishedAt`             | string or null | Format: `date-time`.                                                        |
| `createdAt`              | string         | Format: `date-time`.                                                        |
| `actions`                | object\[]      | —                                                                           |
| `actions[].id`           | string         | Format: `uuid`.                                                             |
| `actions[].runId`        | string         | Format: `uuid`.                                                             |
| `actions[].operationId`  | string         | —                                                                           |
| `actions[].risk`         | string         | One of: `write`, `dangerous`, `destructive`.                                |
| `actions[].status`       | string         | One of: `pending`, `rejected`, `running`, `succeeded`, `failed`.            |
| `actions[].version`      | integer        | —                                                                           |
| `actions[].preview`      | object         | —                                                                           |
| `actions[].result`       | object         | —                                                                           |
| `actions[].error`        | string or null | —                                                                           |
| `actions[].decidedAt`    | string or null | Format: `date-time`.                                                        |
| `actions[].executedAt`   | string or null | Format: `date-time`.                                                        |
| `actions[].createdAt`    | string         | Format: `date-time`.                                                        |
| `evidence`               | object\[]      | —                                                                           |
| `evidence[].id`          | string         | Format: `uuid`.                                                             |
| `evidence[].runId`       | string         | Format: `uuid`.                                                             |
| `evidence[].actionId`    | string or null | Format: `uuid`.                                                             |
| `evidence[].kind`        | string         | One of: `observation`, `verification`, `rollback`.                          |
| `evidence[].operationId` | string or null | —                                                                           |
| `evidence[].summary`     | string         | —                                                                           |
| `evidence[].data`        | object         | —                                                                           |
| `evidence[].createdAt`   | string         | Format: `date-time`.                                                        |