API reference

Gears

Durable workflows: register workflows, start runs, signal them and read their history.

Operations: 9
Base path: https://os.one.ml/api/v1/gears
Scopes: gears.operations.read gears.runs.read gears.runs.write gears.signals.write gears.workflows.read gears.workflows.write
API keys: 9 refused to API keys
SDK: genesis.call('gears_listOperationalRecords', …) · helpers under genesis.gears
CLI: genesis gears
MCP: 9 tools

Operations

Operation	Endpoint	API key
Read meter, audit, evidence, replay and probe records	GET`/operations/records`	API keys refused
List workflow runs	GET`/runs`	API keys refused
Start a workflow run	POST`/runs`	API keys refused
Get a workflow run	GET`/runs/{id}`	API keys refused
Read a run's journal history	GET`/runs/{id}/history`	API keys refused
Send a signal to a running workflow	POST`/runs/{id}/signals`	API keys refused
List registered workflow definitions	GET`/workflows`	API keys refused
Register a workflow definition	POST`/workflows`	API keys refused
Get a workflow definition	GET`/workflows/{id}`	API keys refused

Operations

Read meter, audit, evidence, replay and probe records

GET/v1/gears/operations/records

gears.operations.readAPI keys refusedgears_listOperationalRecords

Responses

200Operational records for your scope
Response fields
- meterRecordsobject[]
- meterRecords[].[].productstring
- meterRecords[].[].gardenMeterstring
- meterRecords[].[].quantitynumber
- meterRecords[].[].scopeKeystring
- auditRecordsobject[]
- auditRecords[].[].productstring
- auditRecords[].[].auditActionstring
- auditRecords[].[].actorIdstring
- auditRecords[].[].targetRefstring
- evidenceRecordsobject[]
- evidenceRecords[].[].productstring
- evidenceRecords[].[].evidenceRefstring
- evidenceRecords[].[].evidenceKindstring
- replayEvidenceobject[]
- replayEvidence[].[].productstring
- replayEvidence[].[].replayEnginestring
- replayEvidence[].[].runIdstring
- replayEvidence[].[].journalSequenceinteger
- replayEvidence[].[].evidenceRefstring
- probeEventsobject[]
- probeEvents[].[].productstring
- probeEvents[].[].eventTypestring
- probeEvents[].[].actorIdstring
- probeEvents[].[].targetRefstring
403gears.operations.read or gears.audit.read required
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/gears/operations/records" \
  -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('gears_listOperationalRecords')

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

Runs

List workflow runs

GET/v1/gears/runs

gears.runs.readAPI keys refusedgears_listRuns

Responses

200Runs in your scope
Response fields
- idstringrequired
- scopeobject
- scope.platformIdstring
- scope.organizationIdstring
- scope.workspaceIdstring
- scope.projectIdstring
- scope.environmentIdstring
- workflowIdstringrequired
- workflowVersionstringrequired
- status"Running" | "Succeeded" | "Failed" | "Cancelled"required
- actorIdstringrequired
- inputRefstringrequired
- contextFrameIdstring | null
- stationSessionIdstring | null
403gears.runs.read required
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/gears/runs" \
  -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('gears_listRuns')

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

Start a workflow run

POST/v1/gears/runs

gears.runs.writeAPI keys refusedIdempotency-Key optionalgears_startRun

Parameters

Idempotency-Keyheader · string
Optional; when present, retries with the same key return the original result instead of acting twice

Request body application/json

workflowIdstringrequired
workflowVersionstringrequired
actorIdstringrequired
inputRefstringrequired
Reference to the run input
contextFrameIdstring
stationSessionIdstring

Responses

201Run started
Response fields
- idstringrequired
- scopeobject
- scope.platformIdstring
- scope.organizationIdstring
- scope.workspaceIdstring
- scope.projectIdstring
- scope.environmentIdstring
- workflowIdstringrequired
- workflowVersionstringrequired
- status"Running" | "Succeeded" | "Failed" | "Cancelled"required
- actorIdstringrequired
- inputRefstringrequired
- contextFrameIdstring | null
- stationSessionIdstring | null
400Invalid body
403gears.runs.write required
404Workflow not found in your scope
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/gears/runs" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "string",
    "workflowVersion": "string",
    "actorId": "string",
    "inputRef": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const idempotencyKey = '<a stable key per change>'
const result = await genesis.call('gears_startRun', {
  body: {
    workflowId: 'string',
    workflowVersion: 'string',
    actorId: 'string',
    inputRef: 'string',
  },
}, {
  headers: { 'Idempotency-Key': idempotencyKey }, // one key per change, reused on every retry
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "gears_startRun",
    "arguments": {
      "body": {
        "workflowId": "string",
        "workflowVersion": "string",
        "actorId": "string",
        "inputRef": "string"
      },
      "idempotency_key": "<a stable key per change>"
    }
  }
}

Get a workflow run

GET/v1/gears/runs/{id}

gears.runs.readAPI keys refusedgears_getRun

Parameters

idpath · stringrequired

Responses

200Run
Response fields
- idstringrequired
- scopeobject
- scope.platformIdstring
- scope.organizationIdstring
- scope.workspaceIdstring
- scope.projectIdstring
- scope.environmentIdstring
- workflowIdstringrequired
- workflowVersionstringrequired
- status"Running" | "Succeeded" | "Failed" | "Cancelled"required
- actorIdstringrequired
- inputRefstringrequired
- contextFrameIdstring | null
- stationSessionIdstring | null
404Not found in your scope
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/gears/runs/$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('gears_getRun', {
  id: '<id>',
})

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

History

Read a run's journal history

GET/v1/gears/runs/{id}/history

gears.runs.readAPI keys refusedgears_getRunHistory

Parameters

idpath · stringrequired

Responses

200Journal entries in sequence order
Response fields
- sequenceintegerrequired
- runIdstringrequired
- kindstringrequired
- actorIdstring
- detailRefstring | null
404Not found in your scope
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/gears/runs/$ID/history" \
  -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('gears_getRunHistory', {
  id: '<id>',
})

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

Signals

Send a signal to a running workflow

POST/v1/gears/runs/{id}/signals

gears.signals.writeAPI keys refusedIdempotency-Key optionalgears_signalRun

Parameters

idpath · stringrequired
Idempotency-Keyheader · string
Optional; when present, retries with the same key return the original result instead of acting twice

Request body application/json

namestringrequired
payloadRefstringrequired
actorIdstringrequired

Responses

202Signal accepted
Response fields
A JSON object.
403gears.signals.write required
404Not found in your scope
409Run is already terminal
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/gears/runs/$ID/signals" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "string",
    "payloadRef": "string",
    "actorId": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const idempotencyKey = '<a stable key per change>'
const result = await genesis.call('gears_signalRun', {
  id: '<id>',
  body: {
    name: 'string',
    payloadRef: 'string',
    actorId: 'string',
  },
}, {
  headers: { 'Idempotency-Key': idempotencyKey }, // one key per change, reused on every retry
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "gears_signalRun",
    "arguments": {
      "id": "<id>",
      "body": {
        "name": "string",
        "payloadRef": "string",
        "actorId": "string"
      },
      "idempotency_key": "<a stable key per change>"
    }
  }
}

Workflows

List registered workflow definitions

GET/v1/gears/workflows

gears.workflows.readAPI keys refusedgears_listWorkflows

Responses

200Workflow definitions in your scope
Response fields
- scopeobject
- scope.platformIdstring
- scope.organizationIdstring
- scope.workspaceIdstring
- scope.projectIdstring
- scope.environmentIdstring
- workflowIdstringrequired
- workflowVersionstringrequired
- namestringrequired
- definitionRefstringrequired
- registeredBystringrequired
403gears.workflows.read required
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/gears/workflows" \
  -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('gears_listWorkflows')

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

Register a workflow definition

POST/v1/gears/workflows

gears.workflows.writeAPI keys refusedIdempotency-Key optionalgears_registerWorkflow

Parameters

Idempotency-Keyheader · string
Optional; when present, retries with the same key return the original result instead of acting twice

Request body application/json

workflowIdstringrequired
workflowVersionstringrequired
namestringrequired
definitionRefstringrequired
Reference to the stored workflow definition
registeredBystringrequired
Actor registering the definition

Responses

201Workflow registered
Response fields
- scopeobject
- scope.platformIdstring
- scope.organizationIdstring
- scope.workspaceIdstring
- scope.projectIdstring
- scope.environmentIdstring
- workflowIdstringrequired
- workflowVersionstringrequired
- namestringrequired
- definitionRefstringrequired
- registeredBystringrequired
400Invalid body
403gears.workflows.write required
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/gears/workflows" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflowId": "string",
    "workflowVersion": "string",
    "name": "string",
    "definitionRef": "string",
    "registeredBy": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const idempotencyKey = '<a stable key per change>'
const result = await genesis.call('gears_registerWorkflow', {
  body: {
    workflowId: 'string',
    workflowVersion: 'string',
    name: 'string',
    definitionRef: 'string',
    registeredBy: 'string',
  },
}, {
  headers: { 'Idempotency-Key': idempotencyKey }, // one key per change, reused on every retry
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "gears_registerWorkflow",
    "arguments": {
      "body": {
        "workflowId": "string",
        "workflowVersion": "string",
        "name": "string",
        "definitionRef": "string",
        "registeredBy": "string"
      },
      "idempotency_key": "<a stable key per change>"
    }
  }
}

Get a workflow definition

GET/v1/gears/workflows/{id}

gears.workflows.readAPI keys refusedgears_getWorkflow

Parameters

idpath · stringrequired

Responses

200Workflow definition
Response fields
- scopeobject
- scope.platformIdstring
- scope.organizationIdstring
- scope.workspaceIdstring
- scope.projectIdstring
- scope.environmentIdstring
- workflowIdstringrequired
- workflowVersionstringrequired
- namestringrequired
- definitionRefstringrequired
- registeredBystringrequired
404Not found in your scope
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/gears/workflows/$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('gears_getWorkflow', {
  id: '<id>',
})

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

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