API reference

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.

str

required

Agent identifier.

str

required

Memory content (1–8000 characters).

float

Importance score (0.0–1.0). Default: 0.5.

dict[str, Any]

Custom metadata dictionary.

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.

str

required

Agent identifier.

str

required

Search query (1–500 characters).

int

Maximum results (1–100). Default: 10.

list[str]

Filter to layers: “working”, “episodic”, “semantic”. Default: all three.

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.

str

required

Agent identifier.

str

required

Search query.

int

Maximum tokens. Default: 2048.

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.

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.

str

required

Agent identifier.

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.

str

required

Workspace identifier.

str

required

Human-readable label for this key.

str

Environment: “live” or “test”. Default: “live”.

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.

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.

object

{
  "revoked": true,
  "key_id": "key_01j..."
}

Health endpoint

GET /health

Server health and version info. No authentication required.

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:

Status	Meaning
400	Bad request (invalid parameters)
401	Unauthorized (missing/invalid API key)
403	Forbidden (key doesn’t have permission)
404	Not found
429	Rate limited
500	Server error

Example error:

{
  "detail": "Invalid token",
  "status": 401
}

Getting started

Configuration

Reference

API reference

Authentication

Memory endpoints

POST /v1/remember

POST /v1/recall

POST /v1/context

GET /v1/stats

DELETE /v1/memory

Admin endpoints

POST /admin/keys

GET /admin/keys/

DELETE /admin/keys/

Health endpoint

GET /health

Error responses

​Authentication

​Memory endpoints

​POST /v1/remember

​POST /v1/recall

​POST /v1/context

​GET /v1/stats

​DELETE /v1/memory

​Admin endpoints

​POST /admin/keys

​GET /admin/keys/

​DELETE /admin/keys/

​Health endpoint

​GET /health

​Error responses

Authentication

Memory endpoints

POST /v1/remember

POST /v1/recall

POST /v1/context

GET /v1/stats

DELETE /v1/memory

Admin endpoints

POST /admin/keys

GET /admin/keys/

DELETE /admin/keys/

Health endpoint

GET /health

Error responses