projectOperator

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

projectOperator.listThreads

List persistent project operator threads, newest first.

GET /v1/orgs/{orgId}/projects/{projectId}/operator/threads

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

Example

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.

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

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.

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

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.

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

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.

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

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.

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

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.

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

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

​projectOperator.listThreads

​Example

​Responses

​Response body (200)

​projectOperator.createThread

​Request body

​Example

​Responses

​Response body (201)

​projectOperator.getThread

​Example

​Responses

​Response body (200)

​projectOperator.createRun

​Request body

​Example

​Responses

​Response body (201)

​projectOperator.getRun

​Example

​Responses

​Response body (200)

​projectOperator.listEvents

​Query parameters

​Example

​Responses

​Response body (200)

​projectOperator.decideAction

​Request body

​Example

​Responses

​Response body (200)

projectOperator.listThreads

Example

Responses

Response body (200)

projectOperator.createThread

Request body

Example

Responses

Response body (201)

projectOperator.getThread

Example

Responses

Response body (200)

projectOperator.createRun

Request body

Example

Responses

Response body (201)

projectOperator.getRun

Example

Responses

Response body (200)

projectOperator.listEvents

Query parameters

Example

Responses

Response body (200)

projectOperator.decideAction

Request body

Example

Responses

Response body (200)