API reference

Flocks

Your own machines and cloud instances with a harness installed: enroll nodes, rotate their credentials and read their state.

Operations: 10
Base path: https://os.one.ml/api/v1/flocks
Scopes: flocks:read flocks:write
API keys: 1 failed with an API key · 2 need a signed-in session · 4 not yet tested · 3 tested with an API key
SDK: genesis.call('flocks_enrollNode', …) · helpers under genesis.flocks
CLI: genesis flocks
MCP: 10 tools

Operations

Operation	Endpoint	API key
Exchange a join token under verified One account org identity	POST`/byom/enroll`	—
List customer hardware belonging to the verified org	GET`/byom/nodes`	Tested with an API key
Revoke an org-owned node binding immediately	DELETE`/byom/nodes/{id}`	Signed-in session
Update an org-owned node nickname	PATCH`/byom/nodes/{id}`	—
Record presence using One account auth plus the node-specific binding	POST`/byom/nodes/{id}/heartbeat`	—
Read server-owned enrollment availability for the verified org	GET`/byom/readiness`	Tested with an API key
Create an org-scoped single-use join token (admin required)	POST`/byom/tokens`	Signed-in session
Activate the exact saved One account node reservation idempotently	POST`/nodes/{id}/activate`	—
Prepare a fixed-scope key, persist it, then commit; cancel an uncertain prepare before retrying	POST`/nodes/{id}/credential:rotate`	Failed with an API key
Exchange a one-time Console join for a node-only One account credential; persist it before activation	POST`/nodes/enroll`	Tested with an API key

Byom

Exchange a join token under verified One account org identity

POST/v1/flocks/byom/enroll

flocks:writeflocks_enrollNode

Request body application/json

tokenstringrequired
max length 256
namestringrequired
max length 128
platformstringrequired
max length 128
cpu_countintegerrequired
min 1 · max 65536

Responses

200Success
Response fields
- nodeobjectrequired
- node.idstringrequired
- node.namestringrequired
- node.nicknamestringrequired
- node.platformstringrequired
- node.cpu_countintegerrequired
  min 1
- node.state"enrolled" | "revoked"required
- node.last_seen_atintegerrequired
- node.enrolled_atintegerrequired
- node_bindingstringrequired
- heartbeat_interval_secondsintegerrequired
401Invalid One account credential or node binding
403Insufficient permission
404Unknown resource in verified org
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/flocks/byom/enroll" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string",
    "name": "string",
    "platform": "string",
    "cpu_count": 1
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('flocks_enrollNode', {
  body: {
    token: 'string',
    name: 'string',
    platform: 'string',
    cpu_count: 1,
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flocks_enrollNode",
    "arguments": {
      "body": {
        "token": "string",
        "name": "string",
        "platform": "string",
        "cpu_count": 1
      }
    }
  }
}

List customer hardware belonging to the verified org

GET/v1/flocks/byom/nodes

flocks:readTested with an API keyflocks_listNodes

Responses

200Success
Response fields
- idstringrequired
- namestringrequired
- nicknamestringrequired
- platformstringrequired
- cpu_countintegerrequired
  min 1
- state"enrolled" | "revoked"required
- last_seen_atintegerrequired
- enrolled_atintegerrequired
401Invalid One account credential or node binding
403Insufficient permission
404Unknown resource in verified org
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/flocks/byom/nodes" \
  -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('flocks_listNodes')

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

Revoke an org-owned node binding immediately

DELETE/v1/flocks/byom/nodes/{id}

flocks:writeSigned-in sessionflocks_revokeNode

Parameters

idpath · stringrequired

Responses

200Success
Response fields
- idstringrequired
- namestringrequired
- nicknamestringrequired
- platformstringrequired
- cpu_countintegerrequired
  min 1
- state"enrolled" | "revoked"required
- last_seen_atintegerrequired
- enrolled_atintegerrequired
401Invalid One account credential or node binding
403Insufficient permission
404Unknown resource in verified org
4xx 5xxThe error envelope.

curl -X DELETE "https://os.one.ml/api/v1/flocks/byom/nodes/$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('flocks_revokeNode', {
  id: '<id>',
})

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

Update an org-owned node nickname

PATCH/v1/flocks/byom/nodes/{id}

flocks:writeflocks_renameNode

Parameters

idpath · stringrequired

Request body application/json

nicknamestringrequired
max length 128

Responses

200Success
Response fields
- idstringrequired
- namestringrequired
- nicknamestringrequired
- platformstringrequired
- cpu_countintegerrequired
  min 1
- state"enrolled" | "revoked"required
- last_seen_atintegerrequired
- enrolled_atintegerrequired
401Invalid One account credential or node binding
403Insufficient permission
404Unknown resource in verified org
4xx 5xxThe error envelope.

curl -X PATCH "https://os.one.ml/api/v1/flocks/byom/nodes/$ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nickname": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('flocks_renameNode', {
  id: '<id>',
  body: {
    nickname: 'string',
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flocks_renameNode",
    "arguments": {
      "id": "<id>",
      "body": {
        "nickname": "string"
      }
    }
  }
}

Record presence using One account auth plus the node-specific binding

POST/v1/flocks/byom/nodes/{id}/heartbeat

flocks:writeflocks_heartbeatNode

Parameters

idpath · stringrequired

Request body application/json

node_bindingstringrequired
min length 64 · max length 64

Responses

200Success
Response fields
- acceptedbooleanrequired
401Invalid One account credential or node binding
403Insufficient permission
404Unknown resource in verified org
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/flocks/byom/nodes/$ID/heartbeat" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "node_binding": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('flocks_heartbeatNode', {
  id: '<id>',
  body: {
    node_binding: 'string',
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flocks_heartbeatNode",
    "arguments": {
      "id": "<id>",
      "body": {
        "node_binding": "string"
      }
    }
  }
}

Read server-owned enrollment availability for the verified org

GET/v1/flocks/byom/readiness

flocks:readTested with an API keyflocks_getEnrollmentReadiness

Responses

200Enrollment readiness
Response fields
- node_enrollment_availablebooleanrequired
  True only when the service can complete the scoped One account node credential flow.
- reason_code"node_credential_issuer_unavailable"
  Present while a supported scoped node credential issuer is unavailable.
401Invalid One account credential
403Insufficient permission
503The configured durable inventory store is unavailable
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/flocks/byom/readiness" \
  -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('flocks_getEnrollmentReadiness')

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

Create an org-scoped single-use join token (admin required)

POST/v1/flocks/byom/tokens

flocks:writeSigned-in sessionflocks_createJoinToken

Request body application/json

ttl_secondsinteger
min 60 · max 600 · default 600

Responses

200Success
Response fields
- tokenstringrequired
- expires_atintegerrequired
401Invalid One account credential or node binding
403Insufficient permission
404Unknown resource in verified org
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/flocks/byom/tokens" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

import { Genesis } from '@lifesi/genesis'

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

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

Activate

Activate the exact saved One account node reservation idempotently

POST/v1/flocks/nodes/{id}/activate

flocks:writeflocks_activateNode

Parameters

idpath · string (uuid)required

Request body application/json

node_noncestringrequired
pattern ^[0-9a-f]{64}$
namestringrequired
min length 1 · max length 128
platformstringrequired
min length 1 · max length 128
cpu_countintegerrequired
min 1 · max 65536

Responses

200The same enrolled node, without reusable secrets
Response fields
- nodeobjectrequired
- node.idstringrequired
- node.namestringrequired
- node.nicknamestringrequired
- node.platformstringrequired
- node.cpu_countintegerrequired
  min 1
- node.state"enrolled" | "revoked"required
- node.last_seen_atintegerrequired
- node.enrolled_atintegerrequired
- activatedbooleanrequired
401Inactive node credential
404Unknown or foreign node/nonce
409Conflicting or revoked reservation
503Native receiver unavailable
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/flocks/nodes/$ID/activate" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "node_nonce": "string",
    "name": "string",
    "platform": "string",
    "cpu_count": 1
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('flocks_activateNode', {
  id: '<id>',
  body: {
    node_nonce: 'string',
    name: 'string',
    platform: 'string',
    cpu_count: 1,
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flocks_activateNode",
    "arguments": {
      "id": "<id>",
      "body": {
        "node_nonce": "string",
        "name": "string",
        "platform": "string",
        "cpu_count": 1
      }
    }
  }
}

Credential:rotate

Prepare a fixed-scope key, persist it, then commit; cancel an uncertain prepare before retrying

POST/v1/flocks/nodes/{id}/credential:rotate

flocks:writeFailed with an API keyflocks_rotateNodeCredential

Parameters

idpath · string (uuid)required

Request body application/json

action"prepare" | "commit" | "cancel"required
node_noncestringrequired
pattern ^[0-9a-f]{64}$
operation_noncestringrequired
pattern ^[0-9a-f]{64}$

Responses

200Committed or cancelled
Response fields
- acceptedbooleanrequired
201Prepared key shown once; persist before commit
Response fields
- node_idstring (uuid)required
- organization_idstringrequired
- credential_idstringrequired
- credential_valuestringrequired
  min length 1 · max length 4096
- scopes"flocks:node"[]required
- expires_atstring (date-time)required
- node_nonce_hashstring
  pattern ^[0-9a-f]{64}$
401Inactive key version
404Unknown or foreign node/nonce
409Pending, terminal or premature rotation
503Rotation unavailable; retain recovery state
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/flocks/nodes/$ID/credential:rotate" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "prepare",
    "node_nonce": "string",
    "operation_nonce": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('flocks_rotateNodeCredential', {
  id: '<id>',
  body: {
    action: 'prepare',
    node_nonce: 'string',
    operation_nonce: 'string',
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flocks_rotateNodeCredential",
    "arguments": {
      "id": "<id>",
      "body": {
        "action": "prepare",
        "node_nonce": "string",
        "operation_nonce": "string"
      }
    }
  }
}

Nodes

Exchange a one-time Console join for a node-only One account credential; persist it before activation

POST/v1/flocks/nodes/enroll

flocks:writeTested with an API keyNo key neededflocks_exchangeJoinToken

Request body application/json

tokenstringrequired
pattern ^[0-9a-f]{64}$
node_noncestringrequired
pattern ^[0-9a-f]{64}$

Responses

201Credential shown once; save privately before activation
Response fields
- node_idstring (uuid)required
- organization_idstringrequired
- credential_idstringrequired
- credential_valuestringrequired
  min length 1 · max length 4096
- scopes"flocks:node"[]required
- expires_atstring (date-time)required
- node_nonce_hashstring
  pattern ^[0-9a-f]{64}$
400Invalid closed body or unexpected bearer
401Expired or used join
503Native issuance unavailable
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/flocks/nodes/enroll" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "string",
    "node_nonce": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('flocks_exchangeJoinToken', {
  body: {
    token: 'string',
    node_nonce: 'string',
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "flocks_exchangeJoinToken",
    "arguments": {
      "body": {
        "token": "string",
        "node_nonce": "string"
      }
    }
  }
}

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