API reference

Runner

Agent task execution: catalogs, jobs and execution permissions.

Operations: 7
Base path: https://os.one.ml/api/v1/runner
Scopes: runner:read runner:write
API keys: 7 not yet tested
SDK: genesis.call('runner_getCatalog', …) · helpers under genesis.runner
CLI: genesis runner
MCP: 7 tools

Operations

Operation	Endpoint	API key
Get authorized Runner workspaces and execution routes	GET`/catalog`	—
List the newest 100 Runner jobs for the verified principal	GET`/jobs`	—
Start a bounded Runner task with an idempotency key	POST`/jobs`	—
Read an authoritative Runner job snapshot	GET`/jobs/{jobId}`	—
Request cancellation of a Runner job	POST`/jobs/{jobId}/cancel`	—
Read an ordered page of Runner job events	GET`/jobs/{jobId}/events`	—
Retrieve the verified provider result for a completed Runner task	GET`/jobs/{jobId}/result`	—

Catalog

Get authorized Runner workspaces and execution routes

GET/v1/runner/catalog

runner:readrunner_getCatalog

Responses

200Authorized catalog; unbound routes cannot execute
Response fields
- workspacesobject[]required
- workspaces[].[].keyobjectrequired
- workspaces[].[].labelstringrequired
  min length 1 · max length 160
- routesobject[]required
- routes[].[].routeIdobjectrequired
- routes[].[].kind"external-harness" | "internal-model"required
- routes[].[].namestringrequired
  min length 1 · max length 160
- routes[].[].viastringrequired
  max length 160
- routes[].[].state"synthetic" | "bound" | "unbound"required
- routes[].[].defaultbooleanrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/runner/catalog" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('runner_getCatalog')

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "runner_getCatalog",
    "arguments": {}
  }
}

Jobs

List the newest 100 Runner jobs for the verified principal

GET/v1/runner/jobs

runner:readrunner_listJobs

Responses

200Newest jobs first
Response fields
- jobsobject[]required
- jobs[].[].jobIdobjectrequired
- jobs[].[].sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- jobs[].[].attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- jobs[].[].executionobject | nullrequired
- jobs[].[].cleanupPendingbooleanrequired
- jobs[].[].taskobjectrequired
- jobs[].[].task.idstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- jobs[].[].task.textstringrequired
  min length 1 · max length 32768 · pattern \S
- jobs[].[].task.metaobject
  Optional bounded JSON. The entire start input has depth <= 6, <= 256 nodes, <= 65536 total string/key characters, <= 64 items per array and <= 32 keys per object; functions, accessors, cycles and non-plain values are rejected.
- jobs[].[].workspaceRefstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- jobs[].[].executionRefobjectrequired
- jobs[].[].executionRef.kind"external-harness" | "internal-model"required
- jobs[].[].executionRef.routeIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- jobs[].[].limitsobjectrequired
- jobs[].[].limits.maxDurationMsintegerrequired
  min 1 · max 86400000
- jobs[].[].limits.maxOutputBytesintegerrequired
  min 1 · max 67108864
- jobs[].[].limits.maxEventsinteger
  min 1 · max 1000 · default 200
- jobs[].[].status"queued" | "running" | "cancel_requested" | "completed" | "failed" | "cancelled"required
- jobs[].[].availabilityobjectrequired
- jobs[].[].availability.state"synthetic" | "bound" | "unbound"required
- jobs[].[].availability.kind"external-harness" | "internal-model"required
- jobs[].[].availability.routeIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- jobs[].[].availability.reasonstring | nullrequired
  max length 200
- jobs[].[].lastSeqintegerrequired
  min 0
- jobs[].[].eventsobject[]required
- jobs[].[].events[].[].jobIdobjectrequired
- jobs[].[].events[].[].sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- jobs[].[].events[].[].attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- jobs[].[].events[].[].seqintegerrequired
  min 1
- jobs[].[].events[].[].type"status" | "output" | "chat" | "artifact" | "error" | "result" | "execution"required
- jobs[].[].events[].[].timestampintegerrequired
- jobs[].[].events[].[].payloadobjectrequired
  Bounded event data; see runner/task-client/v0
- jobs[].[].resultobject | nullrequired
- jobs[].[].errorobject | nullrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/runner/jobs" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('runner_listJobs')

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "runner_listJobs",
    "arguments": {}
  }
}

Start a bounded Runner task with an idempotency key

POST/v1/runner/jobs

runner:writerunner_startJob

Use workspace and route references from the authorized catalog. Reusing a key with the same input returns the existing job; changed input returns 409. A bound route is required for real execution.

Request body application/json

taskobjectrequired
task.idstringrequired
min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
task.textstringrequired
min length 1 · max length 32768 · pattern \S
task.metaobject
Optional bounded JSON. The entire start input has depth <= 6, <= 256 nodes, <= 65536 total string/key characters, <= 64 items per array and <= 32 keys per object; functions, accessors, cycles and non-plain values are rejected.
workspaceRefobjectrequired
Authorized catalog workspace key; never a filesystem path
executionRefobjectrequired
executionRef.kind"external-harness" | "internal-model"required
executionRef.routeIdstringrequired
min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
limitsobjectrequired
limits.maxDurationMsintegerrequired
min 1 · max 86400000
limits.maxOutputBytesintegerrequired
min 1 · max 67108864
limits.maxEventsinteger
min 1 · max 1000 · default 200
idempotencyKeystringrequired
min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$

Responses

201Durable job accepted; acceptance is not task completion
Response fields
- jobIdobjectrequired
- snapshotobjectrequired
- snapshot.jobIdobjectrequired
- snapshot.sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.executionobject | nullrequired
- snapshot.cleanupPendingbooleanrequired
- snapshot.taskobjectrequired
- snapshot.task.idstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.task.textstringrequired
  min length 1 · max length 32768 · pattern \S
- snapshot.task.metaobject
  Optional bounded JSON. The entire start input has depth <= 6, <= 256 nodes, <= 65536 total string/key characters, <= 64 items per array and <= 32 keys per object; functions, accessors, cycles and non-plain values are rejected.
- snapshot.workspaceRefstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.executionRefobjectrequired
- snapshot.executionRef.kind"external-harness" | "internal-model"required
- snapshot.executionRef.routeIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.limitsobjectrequired
- snapshot.limits.maxDurationMsintegerrequired
  min 1 · max 86400000
- snapshot.limits.maxOutputBytesintegerrequired
  min 1 · max 67108864
- snapshot.limits.maxEventsinteger
  min 1 · max 1000 · default 200
- snapshot.status"queued" | "running" | "cancel_requested" | "completed" | "failed" | "cancelled"required
- snapshot.availabilityobjectrequired
- snapshot.availability.state"synthetic" | "bound" | "unbound"required
- snapshot.availability.kind"external-harness" | "internal-model"required
- snapshot.availability.routeIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.availability.reasonstring | nullrequired
  max length 200
- snapshot.lastSeqintegerrequired
  min 0
- snapshot.eventsobject[]required
- snapshot.events[].[].jobIdobjectrequired
- snapshot.events[].[].sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.events[].[].attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.events[].[].seqintegerrequired
  min 1
- snapshot.events[].[].type"status" | "output" | "chat" | "artifact" | "error" | "result" | "execution"required
- snapshot.events[].[].timestampintegerrequired
- snapshot.events[].[].payloadobjectrequired
  Bounded event data; see runner/task-client/v0
- snapshot.resultobject | nullrequired
- snapshot.errorobject | nullrequired
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/runner/jobs" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": {
      "id": "string",
      "text": "string"
    },
    "workspaceRef": {},
    "executionRef": {
      "kind": "external-harness",
      "routeId": "string"
    },
    "limits": {
      "maxDurationMs": 1,
      "maxOutputBytes": 1
    },
    "idempotencyKey": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('runner_startJob', {
  body: {
    task: {
      id: 'string',
      text: 'string',
    },
    workspaceRef: {},
    executionRef: {
      kind: 'external-harness',
      routeId: 'string',
    },
    limits: {
      maxDurationMs: 1,
      maxOutputBytes: 1,
    },
    idempotencyKey: 'string',
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "runner_startJob",
    "arguments": {
      "body": {
        "task": {
          "id": "string",
          "text": "string"
        },
        "workspaceRef": {},
        "executionRef": {
          "kind": "external-harness",
          "routeId": "string"
        },
        "limits": {
          "maxDurationMs": 1,
          "maxOutputBytes": 1
        },
        "idempotencyKey": "string"
      }
    }
  }
}

Read an authoritative Runner job snapshot

GET/v1/runner/jobs/{jobId}

runner:readrunner_getJob

A job outside the verified org and subject is 404, including a valid ID belonging to another principal.

Parameters

jobIdpath · stringrequired

Responses

200Current authoritative snapshot
Response fields
- snapshotobjectrequired
- snapshot.jobIdobjectrequired
- snapshot.sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.executionobject | nullrequired
- snapshot.cleanupPendingbooleanrequired
- snapshot.taskobjectrequired
- snapshot.task.idstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.task.textstringrequired
  min length 1 · max length 32768 · pattern \S
- snapshot.task.metaobject
  Optional bounded JSON. The entire start input has depth <= 6, <= 256 nodes, <= 65536 total string/key characters, <= 64 items per array and <= 32 keys per object; functions, accessors, cycles and non-plain values are rejected.
- snapshot.workspaceRefstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.executionRefobjectrequired
- snapshot.executionRef.kind"external-harness" | "internal-model"required
- snapshot.executionRef.routeIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.limitsobjectrequired
- snapshot.limits.maxDurationMsintegerrequired
  min 1 · max 86400000
- snapshot.limits.maxOutputBytesintegerrequired
  min 1 · max 67108864
- snapshot.limits.maxEventsinteger
  min 1 · max 1000 · default 200
- snapshot.status"queued" | "running" | "cancel_requested" | "completed" | "failed" | "cancelled"required
- snapshot.availabilityobjectrequired
- snapshot.availability.state"synthetic" | "bound" | "unbound"required
- snapshot.availability.kind"external-harness" | "internal-model"required
- snapshot.availability.routeIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.availability.reasonstring | nullrequired
  max length 200
- snapshot.lastSeqintegerrequired
  min 0
- snapshot.eventsobject[]required
- snapshot.events[].[].jobIdobjectrequired
- snapshot.events[].[].sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.events[].[].attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.events[].[].seqintegerrequired
  min 1
- snapshot.events[].[].type"status" | "output" | "chat" | "artifact" | "error" | "result" | "execution"required
- snapshot.events[].[].timestampintegerrequired
- snapshot.events[].[].payloadobjectrequired
  Bounded event data; see runner/task-client/v0
- snapshot.resultobject | nullrequired
- snapshot.errorobject | nullrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/runner/jobs/$JOB_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('runner_getJob', {
  jobId: '<jobId>',
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "runner_getJob",
    "arguments": {
      "jobId": "<jobId>"
    }
  }
}

Cancel

Request cancellation of a Runner job

POST/v1/runner/jobs/{jobId}/cancel

runner:writerunner_cancelJob

Send an empty request body. Cancellation is a request; read status and cleanupPending until the authoritative outcome settles. Repeated cancellation returns the current snapshot.

Parameters

jobIdpath · stringrequired

Responses

200Current authoritative snapshot
Response fields
- snapshotobjectrequired
- snapshot.jobIdobjectrequired
- snapshot.sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.executionobject | nullrequired
- snapshot.cleanupPendingbooleanrequired
- snapshot.taskobjectrequired
- snapshot.task.idstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.task.textstringrequired
  min length 1 · max length 32768 · pattern \S
- snapshot.task.metaobject
  Optional bounded JSON. The entire start input has depth <= 6, <= 256 nodes, <= 65536 total string/key characters, <= 64 items per array and <= 32 keys per object; functions, accessors, cycles and non-plain values are rejected.
- snapshot.workspaceRefstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.executionRefobjectrequired
- snapshot.executionRef.kind"external-harness" | "internal-model"required
- snapshot.executionRef.routeIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.limitsobjectrequired
- snapshot.limits.maxDurationMsintegerrequired
  min 1 · max 86400000
- snapshot.limits.maxOutputBytesintegerrequired
  min 1 · max 67108864
- snapshot.limits.maxEventsinteger
  min 1 · max 1000 · default 200
- snapshot.status"queued" | "running" | "cancel_requested" | "completed" | "failed" | "cancelled"required
- snapshot.availabilityobjectrequired
- snapshot.availability.state"synthetic" | "bound" | "unbound"required
- snapshot.availability.kind"external-harness" | "internal-model"required
- snapshot.availability.routeIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.availability.reasonstring | nullrequired
  max length 200
- snapshot.lastSeqintegerrequired
  min 0
- snapshot.eventsobject[]required
- snapshot.events[].[].jobIdobjectrequired
- snapshot.events[].[].sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.events[].[].attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- snapshot.events[].[].seqintegerrequired
  min 1
- snapshot.events[].[].type"status" | "output" | "chat" | "artifact" | "error" | "result" | "execution"required
- snapshot.events[].[].timestampintegerrequired
- snapshot.events[].[].payloadobjectrequired
  Bounded event data; see runner/task-client/v0
- snapshot.resultobject | nullrequired
- snapshot.errorobject | nullrequired
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/runner/jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('runner_cancelJob', {
  jobId: '<jobId>',
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "runner_cancelJob",
    "arguments": {
      "jobId": "<jobId>"
    }
  }
}

Events

Read an ordered page of Runner job events

GET/v1/runner/jobs/{jobId}/events

runner:readrunner_getJobEvents

Parameters

jobIdpath · stringrequired
afterSeqquery · integer
Exclusive event cursor. Use nextAfterSeq for the next page.

Responses

200At most 200 events; drain pages while hasMore is true
Response fields
- eventsobject[]required
- events[].[].jobIdobjectrequired
- events[].[].sessionIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- events[].[].attemptIdstringrequired
  min length 1 · max length 128 · pattern ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$
- events[].[].seqintegerrequired
  min 1
- events[].[].type"status" | "output" | "chat" | "artifact" | "error" | "result" | "execution"required
- events[].[].timestampintegerrequired
- events[].[].payloadobjectrequired
  Bounded event data; see runner/task-client/v0
- nextAfterSeqintegerrequired
  min 0 · max 9007199254740991
- hasMorebooleanrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/runner/jobs/$JOB_ID/events" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('runner_getJobEvents', {
  jobId: '<jobId>',
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "runner_getJobEvents",
    "arguments": {
      "jobId": "<jobId>"
    }
  }
}

Result

Retrieve the verified provider result for a completed Runner task

GET/v1/runner/jobs/{jobId}/result

runner:readrunner_getJobResult

Returns 409 E_RESULT_NOT_READY until authoritative Fleets success, a confirmed cleanup receipt and a resolvable result reference exist. The server verifies the digest and rejects secret-bearing result content.

Parameters

jobIdpath · stringrequired

Responses

200Bounded provider deliverable
Response fields
- resultobjectrequired
- result.schema"runner/provider-result/v1"required
- result.provider"flocks" | "fleets"required
- result.providerExecutionIdobjectrequired
- result.resultRefobjectrequired
- result.resultRef.refobjectrequired
- result.resultRef.kind"diff" | "test_report" | "artifact" | "result"required
- result.digeststringrequired
  pattern ^sha256:[0-9a-f]{64}$
- result.contentType"application/vnd.life.henry-deliverable+json"required
- result.encoding"utf8"required
- result.contentstringrequired
  <= 8192 UTF-8 bytes of digest-verified JSON; no credentials max length 8192
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/runner/jobs/$JOB_ID/result" \
  -H "Authorization: Bearer $GENESIS_API_KEY"

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('runner_getJobResult', {
  jobId: '<jobId>',
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "runner_getJobResult",
    "arguments": {
      "jobId": "<jobId>"
    }
  }
}

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support