API reference

Minds

Owned Minds and their dedicated, persisted memory.

Operations: 21
Base path: https://os.one.ml/api/v1/minds
Scopes: Authorized by the service; see each operation
API keys: 8 need a signed-in session · 13 refused to API keys
SDK: genesis.call('minds_listMindAttachments', …) · helpers under genesis.minds
CLI: genesis minds
MCP: 21 tools

Operations

Operation	Endpoint	API key
List canonical Mind attachments including tombstones	GET`/{mind_id}/attachments`	Signed-in session
Attach an existing agent or group to a Mind	POST`/{mind_id}/attachments`	Signed-in session
Detach a canonical Mind attachment and retain its revision	DELETE`/{mind_id}/attachments/{attachment_id}`	Signed-in session
List canonical owner agent groups	GET`/agent-groups`	Signed-in session
Create a canonical owner agent group	POST`/agent-groups`	Signed-in session
List canonical group members including tombstones	GET`/agent-groups/{group_id}/members`	Signed-in session
Add a canonical agent to a group with an explicit revision	POST`/agent-groups/{group_id}/members`	Signed-in session
Remove a group member and retain its revision	DELETE`/agent-groups/{group_id}/members/{agent_id}`	Signed-in session
Insert memory using an existing agent credential	POST`/agent/memory/episodic`	API keys refused
Read persisted agent memory by storage UUID	GET`/agent/memory/episodic/{storage_id}`	API keys refused
Search private or explicitly authorized group memory	POST`/agent/search`	API keys refused
Persist an episodic event in an explicit ready Mind; never automatically replay	POST`/memory/episodic`	API keys refused
Read a persisted memory by storage UUID in an explicit ready Mind	GET`/memory/episodic/{storage_id}`	API keys refused
Update content of the same stored episodic event	PUT`/memory/episodic/{storage_id}`	API keys refused
Search actual episodic memory in an explicit ready Mind	POST`/search`	API keys refused
List owned Minds and the verified creation-context fingerprint	GET`/services`	API keys refused
Create one capped Sandbox Mind; retain the same operation key after uncertainty	POST`/services`	API keys refused
Read one Mind owned by the verified organization and project	GET`/services/{mind_id}`	API keys refused
Resume an owned Mind on its retained volume without an automatic retry	POST`/services/{mind_id}/resume`	API keys refused
Stop an owned Mind while retaining its volume without an automatic retry	POST`/services/{mind_id}/stop`	API keys refused
Read native operational usage for the selected project	GET`/usage`	API keys refused

{mind id}

List canonical Mind attachments including tombstones

GET/v1/minds/{mind_id}/attachments

Signed-in sessionAuthorized by the serviceminds_listMindAttachments

Original selected pf_console human bearer only, verified online with current organization/project/workspace/Sandbox context. No agent credential fallback, caller tenant headers, credential issuance, context fingerprint or automatic retry. Independently default-off owner-management admission; all bodies use camelCase.

Parameters

mind_idpath · string (uuid)required

Responses

200Canonical IAM metadata, including any retained revocation tombstone.
Response fields
- attachmentsobject[]required
- attachments[].[].idstringrequired
  pattern ^mat_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- attachments[].[].versionintegerrequired
  min 1 · max 9007199254740991
- attachments[].[].organizationIdstringrequired
- attachments[].[].projectIdstringrequired
- attachments[].[].mindIdstring (uuid)required
  pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
- attachments[].[].subjectobject | objectrequired
- attachments[].[].permissions["minds.agent_data.read"] | ["minds.agent_data.read","minds.agent_data.write"]required
- attachments[].[].sharedNamespacestring | nullrequired
  Server-derived group:<agp ID> for group subjects; null for an individual agent.
- attachments[].[].expiresAtintegerrequired
  min 1 · max 9007199254740991
- attachments[].[].revokedAtinteger | nullrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/minds/$MIND_ID/attachments" \
  -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('minds_listMindAttachments', {
  mind_id: '<mind_id>',
})

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

Attach an existing agent or group to a Mind

POST/v1/minds/{mind_id}/attachments

Signed-in sessionAuthorized by the serviceminds_attachMind

Parameters

mind_idpath · string (uuid)required

Request body application/json

operationIdstring (uuid)required
pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
expectedVersionintegerrequired
min 0 · max 9007199254740990
subjectobject | objectrequired
permissions["minds.agent_data.read"] | ["minds.agent_data.read","minds.agent_data.write"]required
expiresAtintegerrequired
Explicit Unix milliseconds, future and at most30days from current server time. min 1 · max 9007199254740991

Responses

200Canonical IAM metadata, including any retained revocation tombstone.
Response fields
- idstringrequired
  pattern ^mat_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- versionintegerrequired
  min 1 · max 9007199254740991
- organizationIdstringrequired
- projectIdstringrequired
- mindIdstring (uuid)required
  pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
- subjectobject | objectrequired
- permissions["minds.agent_data.read"] | ["minds.agent_data.read","minds.agent_data.write"]required
- sharedNamespacestring | nullrequired
  Server-derived group:<agp ID> for group subjects; null for an individual agent.
- expiresAtintegerrequired
  min 1 · max 9007199254740991
- revokedAtinteger | nullrequired
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/$MIND_ID/attachments" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "00000000-0000-4000-8000-000000000000",
    "expectedVersion": 0,
    "subject": {
      "kind": "agent",
      "agentId": "string"
    },
    "permissions": [
      "minds.agent_data.read"
    ],
    "expiresAt": 1
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('minds_attachMind', {
  mind_id: '<mind_id>',
  body: {
    operationId: '00000000-0000-4000-8000-000000000000',
    expectedVersion: 0,
    subject: {
      kind: 'agent',
      agentId: 'string',
    },
    permissions: [
      'minds.agent_data.read',
    ],
    expiresAt: 1,
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_attachMind",
    "arguments": {
      "mind_id": "<mind_id>",
      "body": {
        "operationId": "00000000-0000-4000-8000-000000000000",
        "expectedVersion": 0,
        "subject": {
          "kind": "agent",
          "agentId": "string"
        },
        "permissions": [
          "minds.agent_data.read"
        ],
        "expiresAt": 1
      }
    }
  }
}

Detach a canonical Mind attachment and retain its revision

DELETE/v1/minds/{mind_id}/attachments/{attachment_id}

Signed-in sessionAuthorized by the serviceminds_detachMind

Parameters

mind_idpath · string (uuid)required
attachment_idpath · stringrequired

Request body application/json

operationIdstring (uuid)required
pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
expectedVersionintegerrequired
min 0 · max 9007199254740990

Responses

200Canonical IAM metadata, including any retained revocation tombstone.
Response fields
- idstringrequired
  pattern ^mat_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- versionintegerrequired
  min 1 · max 9007199254740991
- organizationIdstringrequired
- projectIdstringrequired
- mindIdstring (uuid)required
  pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
- subjectobject | objectrequired
- permissions["minds.agent_data.read"] | ["minds.agent_data.read","minds.agent_data.write"]required
- sharedNamespacestring | nullrequired
  Server-derived group:<agp ID> for group subjects; null for an individual agent.
- expiresAtintegerrequired
  min 1 · max 9007199254740991
- revokedAtinteger | nullrequired
4xx 5xxThe error envelope.

curl -X DELETE "https://os.one.ml/api/v1/minds/$MIND_ID/attachments/$ATTACHMENT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "00000000-0000-4000-8000-000000000000",
    "expectedVersion": 0
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('minds_detachMind', {
  mind_id: '<mind_id>',
  attachment_id: '<attachment_id>',
  body: {
    operationId: '00000000-0000-4000-8000-000000000000',
    expectedVersion: 0,
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_detachMind",
    "arguments": {
      "mind_id": "<mind_id>",
      "attachment_id": "<attachment_id>",
      "body": {
        "operationId": "00000000-0000-4000-8000-000000000000",
        "expectedVersion": 0
      }
    }
  }
}

Agent groups

List canonical owner agent groups

GET/v1/minds/agent-groups

Signed-in sessionAuthorized by the serviceminds_listAgentGroups

Responses

200Canonical IAM metadata, including any retained revocation tombstone.
Response fields
- groupsobject[]required
- groups[].[].idstringrequired
  pattern ^agp_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- groups[].[].organizationIdstringrequired
- groups[].[].ownerIdstringrequired
- groups[].[].organizationGenerationintegerrequired
  min 1 · max 9007199254740991
- groups[].[].namestringrequired
  Non-whitespace label, at most128 UTF-8 bytes; original bytes retained. min length 1 · max length 128
- groups[].[].versionintegerrequired
  min 1 · max 9007199254740991
- groups[].[].revokedAtinteger | nullrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/minds/agent-groups" \
  -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('minds_listAgentGroups')

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

Create a canonical owner agent group

POST/v1/minds/agent-groups

Signed-in sessionAuthorized by the serviceminds_createAgentGroup

Request body application/json

operationIdstring (uuid)required
pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
namestringrequired
Non-whitespace and at most128 UTF-8 bytes. min length 1 · max length 128

Responses

200Canonical IAM metadata, including any retained revocation tombstone.
Response fields
- idstringrequired
  pattern ^agp_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- organizationIdstringrequired
- ownerIdstringrequired
- organizationGenerationintegerrequired
  min 1 · max 9007199254740991
- namestringrequired
  Non-whitespace label, at most128 UTF-8 bytes; original bytes retained. min length 1 · max length 128
- versionintegerrequired
  min 1 · max 9007199254740991
- revokedAtinteger | nullrequired
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/agent-groups" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "00000000-0000-4000-8000-000000000000",
    "name": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('minds_createAgentGroup', {
  body: {
    operationId: '00000000-0000-4000-8000-000000000000',
    name: 'string',
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_createAgentGroup",
    "arguments": {
      "body": {
        "operationId": "00000000-0000-4000-8000-000000000000",
        "name": "string"
      }
    }
  }
}

Members

List canonical group members including tombstones

GET/v1/minds/agent-groups/{group_id}/members

Signed-in sessionAuthorized by the serviceminds_listAgentGroupMembers

Parameters

group_idpath · stringrequired

Responses

200Canonical IAM metadata, including any retained revocation tombstone.
Response fields
- membersobject[]required
- members[].[].groupIdstringrequired
  pattern ^agp_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- members[].[].agentIdstringrequired
  pattern ^a_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- members[].[].agentDidstringrequired
  pattern ^did:[A-Za-z0-9:._%-]{1,512}$
- members[].[].agentCreatedAtintegerrequired
  min 1 · max 9007199254740991
- members[].[].versionintegerrequired
  min 1 · max 9007199254740991
- members[].[].revokedAtinteger | nullrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/minds/agent-groups/$GROUP_ID/members" \
  -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('minds_listAgentGroupMembers', {
  group_id: '<group_id>',
})

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

Add a canonical agent to a group with an explicit revision

POST/v1/minds/agent-groups/{group_id}/members

Signed-in sessionAuthorized by the serviceminds_addAgentGroupMember

Parameters

group_idpath · stringrequired

Request body application/json

operationIdstring (uuid)required
pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
expectedVersionintegerrequired
min 0 · max 9007199254740990
agentIdstringrequired
pattern ^a_[0-7][0-9A-HJKMNP-TV-Z]{25}$

Responses

200Canonical IAM metadata, including any retained revocation tombstone.
Response fields
- groupIdstringrequired
  pattern ^agp_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- agentIdstringrequired
  pattern ^a_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- agentDidstringrequired
  pattern ^did:[A-Za-z0-9:._%-]{1,512}$
- agentCreatedAtintegerrequired
  min 1 · max 9007199254740991
- versionintegerrequired
  min 1 · max 9007199254740991
- revokedAtinteger | nullrequired
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/agent-groups/$GROUP_ID/members" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "00000000-0000-4000-8000-000000000000",
    "expectedVersion": 0,
    "agentId": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('minds_addAgentGroupMember', {
  group_id: '<group_id>',
  body: {
    operationId: '00000000-0000-4000-8000-000000000000',
    expectedVersion: 0,
    agentId: 'string',
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_addAgentGroupMember",
    "arguments": {
      "group_id": "<group_id>",
      "body": {
        "operationId": "00000000-0000-4000-8000-000000000000",
        "expectedVersion": 0,
        "agentId": "string"
      }
    }
  }
}

Remove a group member and retain its revision

DELETE/v1/minds/agent-groups/{group_id}/members/{agent_id}

Signed-in sessionAuthorized by the serviceminds_removeAgentGroupMember

Parameters

group_idpath · stringrequired
agent_idpath · stringrequired

Request body application/json

operationIdstring (uuid)required
pattern ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
expectedVersionintegerrequired
min 0 · max 9007199254740990

Responses

200Canonical IAM metadata, including any retained revocation tombstone.
Response fields
- groupIdstringrequired
  pattern ^agp_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- agentIdstringrequired
  pattern ^a_[0-7][0-9A-HJKMNP-TV-Z]{25}$
- agentDidstringrequired
  pattern ^did:[A-Za-z0-9:._%-]{1,512}$
- agentCreatedAtintegerrequired
  min 1 · max 9007199254740991
- versionintegerrequired
  min 1 · max 9007199254740991
- revokedAtinteger | nullrequired
4xx 5xxThe error envelope.

curl -X DELETE "https://os.one.ml/api/v1/minds/agent-groups/$GROUP_ID/members/$AGENT_ID" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operationId": "00000000-0000-4000-8000-000000000000",
    "expectedVersion": 0
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('minds_removeAgentGroupMember', {
  group_id: '<group_id>',
  agent_id: '<agent_id>',
  body: {
    operationId: '00000000-0000-4000-8000-000000000000',
    expectedVersion: 0,
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_removeAgentGroupMember",
    "arguments": {
      "group_id": "<group_id>",
      "agent_id": "<agent_id>",
      "body": {
        "operationId": "00000000-0000-4000-8000-000000000000",
        "expectedVersion": 0
      }
    }
  }
}

Agent

Insert memory using an existing agent credential

POST/v1/minds/agent/memory/episodic

API keys refusedAuthorized by the serviceminds_agentInsertEpisodicMemory

Uses an existing mak_acr credential or Auth agent token, independently of the human Console selection. Requires explicit mind and optional authorized canonical group. No attachment, key creation, token exchange, human delegation or automatic retry. Producer admission is default off (MINDS_AGENT_MEMORY_ENABLED).

Parameters

mindquery · string (uuid)required
groupquery · string
dpopheader · string
Caller-signed proof for the controller capability endpoint: POST for insert, GET for read/search, canonical htu excluding query. Required only by sender-constrained agent tokens. No automatic nonce retry.

Request body application/json

eventobjectrequired
event.idstring (uuid)required
Caller event UUID; insertion returns a distinct storage UUID used by get. pattern ^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
event.contentstringrequired
Non-whitespace content; maximum 16,000 UTF-8 bytes. min length 1 · max length 16000
event.timestampstring (date-time)required
max length 128
event.event_type"Conversation" | "Command" | "Query" | "Document" | "Error" | "Success" | "Learning" | "Decision" | "Action" | "Context" | "Knowledge"
event.summarystring | null
Nullable summary; maximum 2,000 UTF-8 bytes. max length 2000
event.tagsstring[]

Responses

200Actual persisted agent-memory result.
Response fields
- idstring (uuid)required
  Persisted storage UUID; distinct from the caller event UUID. pattern ^[0-9a-f-]{36}$
401Existing credential rejected or DPOP_NONCE_REQUIRED. Sign a fresh proof explicitly; this call is never automatically repeated.
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/agent/memory/episodic?mind=$MIND" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "id": "00000000-0000-4000-8000-000000000000",
      "content": "string",
      "timestamp": "2026-10-20T00:00:00Z"
    }
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('minds_agentInsertEpisodicMemory', {
  mind: '<mind>',
  body: {
    event: {
      id: '00000000-0000-4000-8000-000000000000',
      content: 'string',
      timestamp: '2026-10-20T00:00:00Z',
    },
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_agentInsertEpisodicMemory",
    "arguments": {
      "mind": "<mind>",
      "body": {
        "event": {
          "id": "00000000-0000-4000-8000-000000000000",
          "content": "string",
          "timestamp": "2026-10-20T00:00:00Z"
        }
      }
    }
  }
}

Read persisted agent memory by storage UUID

GET/v1/minds/agent/memory/episodic/{storage_id}

API keys refusedAuthorized by the serviceminds_agentGetEpisodicMemory

Parameters

storage_idpath · string (uuid)required
mindquery · string (uuid)required
groupquery · string
dpopheader · string
Caller-signed proof for the controller capability endpoint: POST for insert, GET for read/search, canonical htu excluding query. Required only by sender-constrained agent tokens. No automatic nonce retry.

Responses

200Actual persisted agent-memory result.
Response fields
- itemobject | nullrequired
401Existing credential rejected or DPOP_NONCE_REQUIRED. Sign a fresh proof explicitly; this call is never automatically repeated.
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/minds/agent/memory/episodic/$STORAGE_ID?mind=$MIND" \
  -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('minds_agentGetEpisodicMemory', {
  storage_id: '<storage_id>',
  mind: '<mind>',
})

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

Search private or explicitly authorized group memory

POST/v1/minds/agent/search

API keys refusedAuthorized by the serviceminds_agentSearchMemory

Parameters

mindquery · string (uuid)required
groupquery · string
dpopheader · string
Caller-signed proof for the controller capability endpoint: POST for insert, GET for read/search, canonical htu excluding query. Required only by sender-constrained agent tokens. No automatic nonce retry.

Request body application/json

textstringrequired
Non-whitespace search text; maximum 1,000 UTF-8 bytes. min length 1 · max length 1000
limitinteger
min 1 · max 100 · default 20

Responses

200Actual persisted agent-memory result.
Response fields
- idstring (uuid)required
  Caller event UUID; insertion returns a distinct storage UUID used by get. pattern ^[0-9a-f-]{36}$
- contentstringrequired
  min length 1 · max length 16000
- timestampstring (date-time)required
- event_type"Conversation" | "Command" | "Query" | "Document" | "Error" | "Success" | "Learning" | "Decision" | "Action" | "Context" | "Knowledge"required
- summarystring | null
  max length 2000
- tagsstring[]required
401Existing credential rejected or DPOP_NONCE_REQUIRED. Sign a fresh proof explicitly; this call is never automatically repeated.
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/agent/search?mind=$MIND" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "string"
  }'

import { Genesis } from '@lifesi/genesis'

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

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

Memory

Persist an episodic event in an explicit ready Mind; never automatically replay

POST/v1/minds/memory/episodic

API keys refusedAuthorized by the serviceminds_insertEpisodicMemory

Requires an original human One account session with a verified pf_console Sandbox selection. API keys and M2M credentials have no Minds producer and are refused. No caller tenant fields.

Parameters

mindquery · string (uuid)required

Request body application/json

eventobjectrequired
event.idstring (uuid)required
Caller event UUID; insertion returns a distinct storage UUID used by get. pattern ^[0-9a-f-]{36}$
event.contentstringrequired
min length 1 · max length 16000
event.timestampstring (date-time)required
event.event_type"Conversation" | "Command" | "Query" | "Document" | "Error" | "Success" | "Learning" | "Decision" | "Action" | "Context" | "Knowledge"
event.summarystring | null
max length 2000
event.tagsstring[]

Responses

200Actual persisted service response; creation 202 is provisioning, not Ready.
Response fields
- idstring (uuid)required
  Persisted storage UUID; distinct from the caller event UUID. pattern ^[0-9a-f-]{36}$
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/memory/episodic?mind=$MIND" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event": {
      "id": "00000000-0000-4000-8000-000000000000",
      "content": "string",
      "timestamp": "2026-10-20T00:00:00Z"
    }
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('minds_insertEpisodicMemory', {
  mind: '<mind>',
  body: {
    event: {
      id: '00000000-0000-4000-8000-000000000000',
      content: 'string',
      timestamp: '2026-10-20T00:00:00Z',
    },
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_insertEpisodicMemory",
    "arguments": {
      "mind": "<mind>",
      "body": {
        "event": {
          "id": "00000000-0000-4000-8000-000000000000",
          "content": "string",
          "timestamp": "2026-10-20T00:00:00Z"
        }
      }
    }
  }
}

Read a persisted memory by storage UUID in an explicit ready Mind

GET/v1/minds/memory/episodic/{storage_id}

API keys refusedAuthorized by the serviceminds_getEpisodicMemory

Requires an original human One account session with a verified pf_console Sandbox selection. API keys and M2M credentials have no Minds producer and are refused. No caller tenant fields.

Parameters

storage_idpath · string (uuid)required
mindquery · string (uuid)required

Responses

200Actual persisted service response; creation 202 is provisioning, not Ready.
Response fields
- itemobject | nullrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/minds/memory/episodic/$STORAGE_ID?mind=$MIND" \
  -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('minds_getEpisodicMemory', {
  storage_id: '<storage_id>',
  mind: '<mind>',
})

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

Update content of the same stored episodic event

PUT/v1/minds/memory/episodic/{storage_id}

API keys refusedAuthorized by the serviceminds_updateEpisodicMemory

Original human Console Sandbox authorization only. Requires the existing logical event_id and preserves all other stored metadata. No delete/recreate, automatic retry or atomic compare-and-swap guarantee. Reconcile an unknown result with get.

Parameters

storage_idpath · string (uuid)required
mindquery · string (uuid)required

Request body application/json

event_idstring (uuid)required
min length 36 · max length 36
contentstringrequired
min length 1 · max length 16000

Responses

200The existing event content was updated.
Response fields
- oktruerequired
4xx 5xxThe error envelope.

curl -X PUT "https://os.one.ml/api/v1/minds/memory/episodic/$STORAGE_ID?mind=$MIND" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "00000000-0000-4000-8000-000000000000",
    "content": "string"
  }'

import { Genesis } from '@lifesi/genesis'

const genesis = new Genesis({ apiKey: process.env.GENESIS_API_KEY })
const result = await genesis.call('minds_updateEpisodicMemory', {
  storage_id: '<storage_id>',
  mind: '<mind>',
  body: {
    event_id: '00000000-0000-4000-8000-000000000000',
    content: 'string',
  },
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_updateEpisodicMemory",
    "arguments": {
      "storage_id": "<storage_id>",
      "mind": "<mind>",
      "body": {
        "event_id": "00000000-0000-4000-8000-000000000000",
        "content": "string"
      }
    }
  }
}

Search

Search actual episodic memory in an explicit ready Mind

POST/v1/minds/search

API keys refusedAuthorized by the serviceminds_searchMemory

Requires an original human One account session with a verified pf_console Sandbox selection. API keys and M2M credentials have no Minds producer and are refused. No caller tenant fields.

Parameters

mindquery · string (uuid)required

Request body application/json

textstringrequired
min length 1 · max length 1000
limitinteger
min 1 · max 100 · default 20

Responses

200Actual persisted service response; creation 202 is provisioning, not Ready.
Response fields
- idstring (uuid)required
  Caller event UUID; insertion returns a distinct storage UUID used by get. pattern ^[0-9a-f-]{36}$
- contentstringrequired
  min length 1 · max length 16000
- timestampstring (date-time)required
- event_type"Conversation" | "Command" | "Query" | "Document" | "Error" | "Success" | "Learning" | "Decision" | "Action" | "Context" | "Knowledge"required
- summarystring | null
  max length 2000
- tagsstring[]required
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/search?mind=$MIND" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "string"
  }'

import { Genesis } from '@lifesi/genesis'

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

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

Services

List owned Minds and the verified creation-context fingerprint

GET/v1/minds/services

API keys refusedAuthorized by the serviceminds_listMinds

Requires an original human One account session with a verified pf_console Sandbox selection. API keys and M2M credentials have no Minds producer and are refused. No caller tenant fields.

Parameters

afterquery · string (uuid)
limitquery · integer

Responses

200Actual persisted service response; creation 202 is provisioning, not Ready.
Response fields
- schema_version"minds.controller.v1"required
- itemsobject[]required
- items[].[].schema_version"minds.controller.v1"required
- items[].[].mind_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- items[].[].organization_idstringrequired
- items[].[].project_idstringrequired
- items[].[].namestringrequired
- items[].[].regionstringrequired
- items[].[].plan"free" | "pro"required
- items[].[].capacityobjectrequired
- items[].[].capacity.profile_idstringrequired
- items[].[].capacity.cpusintegerrequired
  min 1
- items[].[].capacity.memory_mbintegerrequired
  min 1
- items[].[].capacity.volume_size_gbintegerrequired
  min 1
- items[].[].observed_capacityobject | nullrequired
- items[].[].servicesstring[]required
- items[].[].volume_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- items[].[].base_urlstring (uri)required
- items[].[].desired_state"running" | "stopped" | "deleted"required
- items[].[].observed_state"pending" | "running" | "stopped" | "deleted" | "failed" | "uncertain"required
- items[].[].desired_generationintegerrequired
  min 1
- items[].[].observed_generationintegerrequired
  min 0
- items[].[].status"ready" | "provisioning" | "stopped" | "deleted" | "failed" | "uncertain"required
- items[].[].capacity_appliedbooleanrequired
- items[].[].operation_idstring (uuid) | nullrequired
- items[].[].error_codestring | nullrequired
- items[].[].created_atstring (date-time)required
- items[].[].updated_atstring (date-time)required
- next_cursorstring (uuid) | nullrequired
- context_sha256stringrequired
  Informational fingerprint of the verified human full selection. Required assertion when creating; grants no authority. pattern ^[a-f0-9]{64}$
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/minds/services" \
  -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('minds_listMinds')

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

Create one capped Sandbox Mind; retain the same operation key after uncertainty

POST/v1/minds/services

API keys refusedIdempotency-Key requiredAuthorized by the serviceminds_createMind

Requires an original human One account session with a verified pf_console Sandbox selection. API keys and M2M credentials have no Minds producer and are refused. No caller tenant fields.

Parameters

idempotency-keyheader · string (uuid)required
x-genesis-minds-creation-contextheader · stringrequired

Request body application/json

namestringrequired
Mind on existing Sandbox placement; capacity and tenant are server owned. max length 80 · pattern ^Sandbox(?: .+)?$
plan"free" | "pro"
Optional explicit plan. Omitted/free selects F1; pro defaults to D1. Server-side funding and admission still apply.
profile_id"F1" | "D1" | "D2"
Optional fixed native profile. Pro accepts F1, D1 or D2 and defaults to D1. Omitted/free plan accepts only F1. P1 is unavailable; arbitrary capacity is never accepted.

Responses

202Actual persisted service response; creation 202 is provisioning, not Ready.
Response fields
- schema_version"minds.controller.v1"required
- mind_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- organization_idstringrequired
- project_idstringrequired
- namestringrequired
- regionstringrequired
- plan"free" | "pro"required
- capacityobjectrequired
- capacity.profile_idstringrequired
- capacity.cpusintegerrequired
  min 1
- capacity.memory_mbintegerrequired
  min 1
- capacity.volume_size_gbintegerrequired
  min 1
- observed_capacityobject | nullrequired
- servicesstring[]required
- volume_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- base_urlstring (uri)required
- desired_state"running" | "stopped" | "deleted"required
- observed_state"pending" | "running" | "stopped" | "deleted" | "failed" | "uncertain"required
- desired_generationintegerrequired
  min 1
- observed_generationintegerrequired
  min 0
- status"ready" | "provisioning" | "stopped" | "deleted" | "failed" | "uncertain"required
- capacity_appliedbooleanrequired
- operation_idstring (uuid) | nullrequired
- error_codestring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/services" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "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('minds_createMind', {
  body: {
    name: 'string',
  },
}, {
  headers: { 'Idempotency-Key': idempotencyKey }, // one key per change, reused on every retry
})

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

Read one Mind owned by the verified organization and project

GET/v1/minds/services/{mind_id}

API keys refusedAuthorized by the serviceminds_getMind

Requires an original human One account session with a verified pf_console Sandbox selection. API keys and M2M credentials have no Minds producer and are refused. No caller tenant fields.

Parameters

mind_idpath · string (uuid)required

Responses

200Actual persisted service response; creation 202 is provisioning, not Ready.
Response fields
- schema_version"minds.controller.v1"required
- mind_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- organization_idstringrequired
- project_idstringrequired
- namestringrequired
- regionstringrequired
- plan"free" | "pro"required
- capacityobjectrequired
- capacity.profile_idstringrequired
- capacity.cpusintegerrequired
  min 1
- capacity.memory_mbintegerrequired
  min 1
- capacity.volume_size_gbintegerrequired
  min 1
- observed_capacityobject | nullrequired
- servicesstring[]required
- volume_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- base_urlstring (uri)required
- desired_state"running" | "stopped" | "deleted"required
- observed_state"pending" | "running" | "stopped" | "deleted" | "failed" | "uncertain"required
- desired_generationintegerrequired
  min 1
- observed_generationintegerrequired
  min 0
- status"ready" | "provisioning" | "stopped" | "deleted" | "failed" | "uncertain"required
- capacity_appliedbooleanrequired
- operation_idstring (uuid) | nullrequired
- error_codestring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/minds/services/$MIND_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('minds_getMind', {
  mind_id: '<mind_id>',
})

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

Resume

Resume an owned Mind on its retained volume without an automatic retry

POST/v1/minds/services/{mind_id}/resume

API keys refusedIdempotency-Key requiredAuthorized by the serviceminds_resumeMind

Requires the original human Console Sandbox selection and existing Minds update permission. Retain the same key and original expected_generation after uncertainty. The controller resolves durable replay before checking generation; no capacity or tenant fields are accepted.

Parameters

mind_idpath · string (uuid)required
idempotency-keyheader · string (uuid)required

Request body application/json

expected_generationintegerrequired
Original desired_generation from a fresh owned read; keep unchanged with the idempotency key if outcome is unknown. min 1 · max 9007199254740990
wake_reason"manual" | "scheduled_job" | "webhook" | "memory_consolidation" | "activity"
Optional reason for this resume intent. Preserve it with the original generation and idempotency key after uncertainty; no automatic replay.

Responses

202Resume accepted on the retained Mind; poll its owned read until ready.
Response fields
- schema_version"minds.controller.v1"required
- mind_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- organization_idstringrequired
- project_idstringrequired
- namestringrequired
- regionstringrequired
- plan"free" | "pro"required
- capacityobjectrequired
- capacity.profile_idstringrequired
- capacity.cpusintegerrequired
  min 1
- capacity.memory_mbintegerrequired
  min 1
- capacity.volume_size_gbintegerrequired
  min 1
- observed_capacityobject | nullrequired
- servicesstring[]required
- volume_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- base_urlstring (uri)required
- desired_state"running" | "stopped" | "deleted"required
- observed_state"pending" | "running" | "stopped" | "deleted" | "failed" | "uncertain"required
- desired_generationintegerrequired
  min 1
- observed_generationintegerrequired
  min 0
- status"ready" | "provisioning" | "stopped" | "deleted" | "failed" | "uncertain"required
- capacity_appliedbooleanrequired
- operation_idstring (uuid) | nullrequired
- error_codestring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/services/$MIND_ID/resume" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_generation": 1
  }'

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('minds_resumeMind', {
  mind_id: '<mind_id>',
  body: {
    expected_generation: 1,
  },
}, {
  headers: { 'Idempotency-Key': idempotencyKey }, // one key per change, reused on every retry
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_resumeMind",
    "arguments": {
      "mind_id": "<mind_id>",
      "body": {
        "expected_generation": 1
      },
      "idempotency_key": "<a stable key per change>"
    }
  }
}

Stop

Stop an owned Mind while retaining its volume without an automatic retry

POST/v1/minds/services/{mind_id}/stop

API keys refusedIdempotency-Key requiredAuthorized by the serviceminds_stopMind

Parameters

mind_idpath · string (uuid)required
idempotency-keyheader · string (uuid)required

Request body application/json

expected_generationintegerrequired
Original desired_generation from a fresh owned read; keep unchanged with the idempotency key if outcome is unknown. min 1 · max 9007199254740990

Responses

202Stop accepted on the retained Mind; poll its owned read until stopped.
Response fields
- schema_version"minds.controller.v1"required
- mind_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- organization_idstringrequired
- project_idstringrequired
- namestringrequired
- regionstringrequired
- plan"free" | "pro"required
- capacityobjectrequired
- capacity.profile_idstringrequired
- capacity.cpusintegerrequired
  min 1
- capacity.memory_mbintegerrequired
  min 1
- capacity.volume_size_gbintegerrequired
  min 1
- observed_capacityobject | nullrequired
- servicesstring[]required
- volume_idstring (uuid)required
  pattern ^[0-9a-f-]{36}$
- base_urlstring (uri)required
- desired_state"running" | "stopped" | "deleted"required
- observed_state"pending" | "running" | "stopped" | "deleted" | "failed" | "uncertain"required
- desired_generationintegerrequired
  min 1
- observed_generationintegerrequired
  min 0
- status"ready" | "provisioning" | "stopped" | "deleted" | "failed" | "uncertain"required
- capacity_appliedbooleanrequired
- operation_idstring (uuid) | nullrequired
- error_codestring | nullrequired
- created_atstring (date-time)required
- updated_atstring (date-time)required
4xx 5xxThe error envelope.

curl -X POST "https://os.one.ml/api/v1/minds/services/$MIND_ID/stop" \
  -H "Authorization: Bearer $GENESIS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_generation": 1
  }'

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('minds_stopMind', {
  mind_id: '<mind_id>',
  body: {
    expected_generation: 1,
  },
}, {
  headers: { 'Idempotency-Key': idempotencyKey }, // one key per change, reused on every retry
})

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "minds_stopMind",
    "arguments": {
      "mind_id": "<mind_id>",
      "body": {
        "expected_generation": 1
      },
      "idempotency_key": "<a stable key per change>"
    }
  }
}

Usage

Read native operational usage for the selected project

GET/v1/minds/usage

API keys refusedAuthorized by the serviceminds_getUsage

Requires the original human Console Sandbox selection and Minds read permission. Explicit RFC3339 from/to window must be positive and at most 93 days. Account totals and financial fields are excluded; unreported telemetry is not zero.

Parameters

fromquery · string (date-time)required
toquery · string (date-time)required

Responses

200Selected-project allocations and reported host telemetry with explicit completeness.
Response fields
- schema_version"minds.controller.v1"required
- organization_idstringrequired
- project_idstringrequired
- fromstring (date-time)required
  max length 40
- tostring (date-time)required
  max length 40
- measured_atstring (date-time)required
  max length 40
- basis"host_confirmed_intervals"required
- mindsobject[]required
- minds[].[].mind_idstring (uuid)required
- minds[].[].namestringrequired
- minds[].[].profile_idstring | nullrequired
- minds[].[].desired_state"running" | "stopped" | "deleted"required
- minds[].[].observed_state"pending" | "running" | "stopped" | "deleted" | "failed" | "uncertain"required
- minds[].[].stop_reasonstring | nullrequired
- minds[].[].last_activity_atstring | null (date-time)required
- minds[].[].compute_secondsnumberrequired
  min 0
- minds[].[].vcpu_secondsnumberrequired
  min 0
- minds[].[].memory_mb_secondsnumberrequired
  min 0
- minds[].[].storage_gb_secondsnumberrequired
  min 0
- minds[].[].measuredobject | objectrequired
- minds[].[].metering_computebooleanrequired
- minds[].[].completebooleanrequired
- minds[].[].incomplete_reason"host_state_uncertain" | "compute_unconfirmed_after_failure" | "running_without_ledger_interval" | "ledger_open_after_stop" | "host_not_reporting" | nullrequired
4xx 5xxThe error envelope.

curl "https://os.one.ml/api/v1/minds/usage?from=$FROM&to=$TO" \
  -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('minds_getUsage', {
  from: '<from>',
  to: '<to>',
})

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

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