Internal Runs · Oblive Docs

Claim a run request and create its next attempt

POST/internal/run-requests/{runRequestId}/start

Revalidates task readiness and serializes organization/profile capacity before creating the immutable attempt. A capacity conflict returns 409 without incrementing attempt or task run counters.

Authorization

agentServiceToken

AuthorizationBearer <token>

Token used by trusted agent runtimes.

In: header

Path Parameters

runRequestId*string

Run request identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/internal/run-requests/497f6eca-6276-4993-bfeb-53cbbbba6f08/start" \  -H "Content-Type: application/json" \  -d '{    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "runId": "5874578b-65c7-4d72-b3de-2bc24a8b421e",    "workerId": "worker-local-1",    "leaseToken": "fence-1",    "leaseExpiresAt": "2026-07-13T12:02:10.000Z"  }'

{  "success": true,  "statusCode": 200,  "message": "Run attempt started.",  "data": {    "kind": "run",    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "agentProfileId": "8abf91f2-5785-44c7-bfb2-508fa85a8f8d",    "taskId": "b12e12e7-68df-4ba8-a72a-32eb80d60b64",    "runRequestId": "99e02964-075c-4427-9a94-d6a12dde1ac6",    "runId": "5874578b-65c7-4d72-b3de-2bc24a8b421e",    "attempt": 1,    "executionToken": "<execution-capability>"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed"  }}

{  "success": false,  "statusCode": 401,  "message": "Invalid agent service token.",  "error": {    "code": "agent_unauthorized"  }}

{  "success": false,  "statusCode": 409,  "message": "Run lease is missing, stale, or expired.",  "error": {    "code": "run_lease_expired"  }}

Mark a hydrated run as running

POST/internal/runs/{runId}/running

Authorization

agentServiceToken

AuthorizationBearer <token>

Token used by trusted agent runtimes.

In: header

Path Parameters

runId*string

Run attempt identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/internal/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/running" \  -H "Content-Type: application/json" \  -d '{    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "leaseToken": "fence-1",    "harness": "codex",    "model": "gpt-5.3-codex",    "workspaceUri": "s3://oblive/runs/5874578b/workspace"  }'

{  "success": true,  "statusCode": 200,  "message": "Run marked running.",  "data": {    "status": "running"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed"  }}

{  "success": false,  "statusCode": 401,  "message": "Invalid agent service token.",  "error": {    "code": "agent_unauthorized"  }}

{  "success": false,  "statusCode": 409,  "message": "Run lease is missing, stale, or expired.",  "error": {    "code": "run_lease_expired"  }}

Renew an active run heartbeat and lease

POST/internal/runs/{runId}/heartbeat

Authorization

agentServiceToken

AuthorizationBearer <token>

Token used by trusted agent runtimes.

In: header

Path Parameters

runId*string

Run attempt identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/internal/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/heartbeat" \  -H "Content-Type: application/json" \  -d '{    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "leaseToken": "fence-1",    "leaseExpiresAt": "2026-07-13T12:03:10.000Z"  }'

{  "success": true,  "statusCode": 200,  "message": "Run heartbeat recorded.",  "data": {    "status": "running"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed"  }}

{  "success": false,  "statusCode": 401,  "message": "Invalid agent service token.",  "error": {    "code": "agent_unauthorized"  }}

{  "success": false,  "statusCode": 409,  "message": "Run lease is missing, stale, or expired.",  "error": {    "code": "run_lease_expired"  }}

Finalize a run, task, dependencies, and recovery

POST/internal/runs/{runId}/complete

Finalization applies the typed outcome atomically. An exhausted replan budget opens one human override; one final amendment may consume it, and any further amendment fails the task.

Authorization

agentServiceToken

AuthorizationBearer <token>

Token used by trusted agent runtimes.

In: header

Path Parameters

runId*string

Run attempt identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/internal/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/complete" \  -H "Content-Type: application/json" \  -d '{    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "leaseToken": "fence-1",    "output": {      "kind": "task_result",      "result": {        "kind": "completed",        "summary": "Review completed.",        "artifacts": []      }    },    "usage": {      "inputTokens": 1200,      "outputTokens": 300,      "toolCalls": 2,      "costMinorUnits": 0    },    "harness": "codex",    "workspaceUri": "s3://oblive/runs/5874578b/workspace"  }'

{  "success": true,  "statusCode": 200,  "message": "Run completed and dependent work reconciled.",  "data": {    "status": "running"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed"  }}

{  "success": false,  "statusCode": 401,  "message": "Invalid agent service token.",  "error": {    "code": "agent_unauthorized"  }}

{  "success": false,  "statusCode": 409,  "message": "Run lease is missing, stale, or expired.",  "error": {    "code": "run_lease_expired"  }}

Record a fenced run failure

POST/internal/runs/{runId}/fail

Authorization

agentServiceToken

AuthorizationBearer <token>

Token used by trusted agent runtimes.

In: header

Path Parameters

runId*string

Run attempt identifier.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

`application/json`

curl -X POST "https://example.com/internal/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/fail" \  -H "Content-Type: application/json" \  -d '{    "organizationId": "7d4a6f1d-ff64-4a4f-9e8d-937bfaa0d2f1",    "leaseToken": "fence-1",    "error": {      "code": "object_sync_failed",      "message": "Output sync failed.",      "retryable": true    },    "usage": {      "inputTokens": 1200,      "outputTokens": 300,      "toolCalls": 2,      "costMinorUnits": 0    },    "harness": "codex"  }'

{  "success": true,  "statusCode": 200,  "message": "Run failure recorded.",  "data": {    "status": "running"  }}

{  "success": false,  "statusCode": 400,  "message": "Validation failed.",  "error": {    "code": "validation_failed"  }}

{  "success": false,  "statusCode": 401,  "message": "Invalid agent service token.",  "error": {    "code": "agent_unauthorized"  }}

{  "success": false,  "statusCode": 409,  "message": "Run lease is missing, stale, or expired.",  "error": {    "code": "run_lease_expired"  }}

200application/json

400application/json

401application/json

409application/json

200application/json

400application/json

401application/json

409application/json

200application/json

400application/json

401application/json

409application/json

200application/json

400application/json

401application/json

409application/json

200application/json

400application/json

401application/json

409application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`