REST API — Elephantasm Docs

Base URL

https://api.elephantasm.com/api

All endpoints are prefixed with /api. The SDKs handle this automatically.

Authentication

All endpoints (except health check) require a Bearer token:

curl https://api.elephantasm.com/api/animas \
  -H "Authorization: Bearer sk_live_..."

API keys are created in the Elephantasm dashboard. Keys use the sk_live_ prefix.

Endpoints

GET /health

Health check endpoint. No authentication required.

curl https://api.elephantasm.com/api/health

Response 200:

{
  "status": "healthy",
  "timestamp": "2026-02-04T12:00:00Z",
  "checks": {
    "database": "healthy"
  }
}

POST /animas — Create Anima

Create a new anima (agent entity).

curl -X POST https://api.elephantasm.com/api/animas \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "Customer support bot"}'

Request Body

Name	Type	Required	Description
name	string	required	Human-readable name (max 255 chars).
description	string	optional	Optional description.
meta	object	optional	Arbitrary metadata.

Response `201`

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "my-agent",
  "description": "Customer support bot",
  "meta": null,
  "user_id": "...",
  "is_deleted": false,
  "created_at": "2026-02-04T12:00:00Z",
  "updated_at": "2026-02-04T12:00:00Z"
}

GET /animas/:anima_id

Get an anima by ID.

curl https://api.elephantasm.com/api/animas/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_..."

Path Parameters

Name	Type	Required	Description
anima_id	UUID	required	Anima identifier.

Response `200`

Returns the anima object (same schema as POST response).

Returns 404 if the anima doesn't exist or belongs to a different user.

POST /events — Create Event

Create an event (capture an interaction for memory synthesis). This is the backend endpoint for extract().

curl -X POST https://api.elephantasm.com/api/events \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "anima_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "message.in",
    "content": "What is the weather in San Francisco?",
    "role": "user",
    "session_id": "conv-123"
  }'

Request Body

Name	Type	Required	Description
anima_id	UUID	required	Target anima ID.
event_type	string	required	Event type: message.in, message.out, tool.call, tool.result, system.
content	string	required	Event content body.
role	string	optional	Message role: user, assistant, system, tool.
author	string	optional	Who produced this event.
summary	string	optional	Optional summary.
occurred_at	string	optional	ISO 8601 timestamp. Defaults to now.
session_id	string	optional	Session grouping identifier.
meta	object	optional	Arbitrary metadata (default: {}).
source_uri	string	optional	Source system identifier.
dedupe_key	string	optional	Custom deduplication key.
importance_score	number	optional	Priority hint, 0.0–1.0.

Response `201`

{
  "id": "...",
  "anima_id": "550e8400-e29b-41d4-a716-446655440000",
  "event_type": "message.in",
  "content": "What is the weather in San Francisco?",
  "role": "user",
  "author": null,
  "summary": null,
  "occurred_at": "2026-02-04T12:00:00Z",
  "session_id": "conv-123",
  "meta": {},
  "source_uri": null,
  "dedupe_key": "a1b2c3d4...",
  "importance_score": null,
  "is_deleted": false,
  "created_at": "2026-02-04T12:00:00Z",
  "updated_at": "2026-02-04T12:00:00Z"
}

Returns 409 if a duplicate dedupe_key already exists (safe to retry).

GET /animas/:anima_id/memory-packs/latest

Get the latest compiled memory pack for an anima. This is the backend endpoint for inject().

curl "https://api.elephantasm.com/api/animas/550e8400.../memory-packs/latest?preset=conversational" \
  -H "Authorization: Bearer sk_live_..."

Path Parameters

Name	Type	Required	Description
anima_id	UUID	required	Anima identifier.

Query Parameters

Name	Type	Required	Description
query	string	optional	Semantic search query for memory retrieval.
preset	string	optional	Compilation preset: conversational, self_determined.

Response `200`

Returns a memory pack object or null if no packs exist.

{
  "id": "...",
  "anima_id": "550e8400-e29b-41d4-a716-446655440000",
  "query": null,
  "preset_name": "conversational",
  "session_memory_count": 5,
  "knowledge_count": 3,
  "long_term_memory_count": 8,
  "has_identity": true,
  "token_count": 2847,
  "max_tokens": 4000,
  "content": {
    "context": "## Long-Term Memory Context\n\n...",
    "identity": { "prose": "..." },
    "session_memories": [...],
    "knowledge": [...],
    "long_term_memories": [...],
    "temporal_context": { "formatted": "Last interaction: 2 hours ago..." }
  },
  "compiled_at": "2026-02-04T12:00:00Z",
  "created_at": "2026-02-04T12:00:00Z"
}

The content.context field contains the pre-formatted string that as_prompt() / asPrompt() returns in the SDKs.

GET /subscriptions/usage

Get current subscription usage statistics.

curl https://api.elephantasm.com/api/subscriptions/usage \
  -H "Authorization: Bearer sk_live_..."

Response `200`

Returns current usage metrics for your subscription plan.

Error Responses

All errors follow a consistent format:

{
  "detail": "Human-readable error description"
}

Status	Meaning	When
`401`	Authentication failed	Missing or invalid API key
`404`	Not found	Resource doesn't exist or RLS isolation
`409`	Conflict	Duplicate `dedupe_key` on event creation
`422`	Validation error	Invalid request parameters
`429`	Rate limited	Too many requests or plan limit exceeded
`5xx`	Server error	Internal errors

The SDKs map these HTTP status codes to typed exceptions/errors automatically. Use the Python SDK or TypeScript SDK for a better developer experience.