Atoms API
The atoms endpoints are the core of Parametric Memory. They handle storing and retrieving individual named knowledge units.
Store an atom
POST /atoms
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json{
"key": "v1.user.Glen.preference.theme",
"value": "dark"
}Response 201:
{
"key": "v1.user.Glen.preference.theme",
"version": 1,
"hash": "a9b2c3d4...",
"rootHash": "f1e2d3c4...",
"createdAt": 1743638400000
}Retrieve an atom
GET /atoms/:key
Authorization: Bearer YOUR_API_KEYResponse 200:
{
"key": "v1.user.Glen.preference.theme",
"value": "dark",
"version": 3,
"hash": "a9b2c3d4...",
"proof": {
"leafHash": "a9b2c3d4...",
"siblings": ["b1c2d3e4...", "c2d3e4f5..."],
"rootHash": "f1e2d3c4...",
"leafIndex": 42,
"treeSize": 500
}
}Batch store
POST /batch-atoms
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json{
"atoms": [
{ "key": "v1.user.Glen.preference.theme", "value": "dark" },
{ "key": "v1.user.Glen.preference.language", "value": "TypeScript" }
]
}Batch operations are processed atomically — either all succeed or all fail.
Error responses
| Status | Code | Meaning |
|---|---|---|
401 | UNAUTHORIZED | Missing or invalid API key |
403 | FORBIDDEN | Key lacks full scope (read-only key) |
404 | NOT_FOUND | Atom key does not exist |
413 | PAYLOAD_TOO_LARGE | Value exceeds tier limit |
422 | SENSITIVE_CONTENT_REJECTED | Value matched a credential pattern or entropy check — see Atom Safety |
429 | RATE_LIMITED | Too many requests — back off and retry |