Skip to main content

​
Authentication

All memory endpoints (prefixed /v1/) require an API key in the Authorization header: 
Authorization: Bearer plm_live_your_key_here
The key is extracted and validated on every request. If invalid or missing: 
{
  "detail": "Unauthorized",
  "status": 401
}
The API key determines the workspace — all responses are scoped to that workspace automatically.

​
Memory endpoints

All memory endpoints are namespaced under /v1/ and require a valid API key.

​
POST /v1/remember

Write to all three memory layers.
​
agent_id
str
required
Agent identifier.
​
content
str
required
Memory content (1–8000 characters).
​
importance
float
Importance score (0.0–1.0). Default: 0.5.
​
metadata
dict[str, Any]
Custom metadata dictionary.
​
200
object
{
  "working": {
    "id": "...",
    "content": "...",
    "importance": 0.5,
    "created_at": "2025-03-18T..."
  },
  "episodic": {
    "id": "...",
    "content": "...",
    "event": "agent_response",
    "created_at": "2025-03-18T..."
  },
  "facts": []
}

​
POST /v1/recall

Search across all three layers and return ranked results.
​
agent_id
str
required
Agent identifier.
​
query
str
required
Search query (1–500 characters).
​
top_k
int
Maximum results (1–100). Default: 10.
​
layers
list[str]
Filter to layers: “working”, “episodic”, “semantic”. Default: all three.
​
200
object
{
  "query": "Python frameworks",
  "results": [
    {
      "id": "...",
      "layer": "episodic",
      "content": "User prefers async Python",
      "score": 0.94,
      "similarity": 0.92,
      "recency": 0.96,
      "importance": 0.95,
      "created_at": "2025-03-18T..."
    }
  ],
  "total_found": 42,
  "cache_hit": false,
  "latency_ms": 45.2
}

​
POST /v1/context

Build a token-budgeted context string.
​
agent_id
str
required
Agent identifier.
​
query
str
required
Search query.
​
token_budget
int
Maximum tokens. Default: 2048.
​
200
object
{
  "query": "what does the user prefer?",
  "content": "[EPISODIC] User prefers async Python (score: 0.94)\n[SEMANTIC] User PREFERS async Python (score: 0.87)",
  "token_count": 28,
  "token_budget": 500,
  "memories_used": 2,
  "cache_hit": false,
  "latency_ms": 12.5
}

​
GET /v1/stats

Get memory statistics for the current workspace.
​
200
object
{
  "workspace_id": "acme-corp",
  "working_entries": 42,
  "episodic_records": 1250,
  "semantic_facts": 380,
  "agents": ["support-agent", "sales-agent"],
  "last_write": "2025-03-18T10:30:00Z"
}

​
DELETE /v1/memory

Clear all working memory for an agent.
​
agent_id
str
required
Agent identifier.
​
200
object
{
  "deleted": 23,
  "agent_id": "support-agent"
}

​
Admin endpoints

Admin endpoints require PLYRA_ADMIN_API_KEY instead of a regular API key. 
Authorization: Bearer $PLYRA_ADMIN_API_KEY

​
POST /admin/keys

Create a new API key.
​
workspace_id
str
required
Workspace identifier.
​
label
str
required
Human-readable label for this key.
​
env
str
Environment: “live” or “test”. Default: “live”.
​
201
object
{
  "key": "plm_live_a3f9...",
  "key_id": "key_01j...",
  "workspace_id": "acme-corp",
  "label": "production — support agent",
  "created_at": "2025-03-18T10:00:00Z"
}
The key field is returned only once. It is hashed server-side and cannot be retrieved again.

​
GET /admin/keys/

List all keys for a workspace.
​
200
array
[
  {
    "key_id": "key_01j...",
    "workspace_id": "acme-corp",
    "label": "production — support agent",
    "created_at": "2025-03-18T10:00:00Z",
    "last_used": "2025-03-18T10:15:00Z"
  }
]

​
DELETE /admin/keys/

Revoke an API key. Revocation is instant.
​
200
object
{
  "revoked": true,
  "key_id": "key_01j..."
}

​
Health endpoint

​
GET /health

Server health and version info. No authentication required.
​
200
object
{
  "status": "ok",
  "version": "0.3.0",
  "env": "production",
  "uptime_seconds": 3600.5,
  "database": "ok",
  "vectors": "ok"
}

​
Error responses

All errors return JSON with a detail field and appropriate HTTP status:
StatusMeaning
400Bad request (invalid parameters)
401Unauthorized (missing/invalid API key)
403Forbidden (key doesn’t have permission)
404Not found
429Rate limited
500Server error
Example error: 
{
  "detail": "Invalid token",
  "status": 401
}