Usage

Enagram exposes a simple HTTP API on your application's endpoint. You send interaction events to build up memory, then retrieve assembled working memory context to inject into your agent's prompt.

Your application's base URL and instance key are both shown in the API tab of the dashboard.

Authentication

All requests must include your instance key as a Bearer token:

Authorization: Bearer eng_...

Your instance key is unique to each application and is stored securely within the application. Retrieve it from the API tab — it is never stored in the dashboard database.

Sending events

POST /events ingests an interaction event into the memory pipeline. Events are scored for salience, compiled into episodes, and eventually promoted into semantic facts, procedures, and identity signals.

Request body

Field	Type	Required	Description
`session_id`	string	Yes	Groups related events into a session. Use a consistent ID per conversation.
`agent_id`	string	Yes	Identifies the user or agent this memory belongs to.
`event_type`	string	Yes	Type of event — `user_message`, `model_response`, `outcome`, or `correction`.
`payload`	object	Yes	Arbitrary JSON — typically `{ "text": "..." }` for message events.
`outcome`	string	No	`success`, `failure`, `partial`, or `unknown`. See Outcomes below.
`occurred_at`	number	No	Unix timestamp in milliseconds. Defaults to server time.

Response

Returns 200 OK with { "id": "...", "salience": 0.72, "stored": true }.

stored: false means the event was below the salience threshold and was not committed to memory.

const response = await fetch("https://{app-id}.api.enagram.io/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer eng_...",
  },
  body: JSON.stringify({
    session_id: "sess_001",
    event_type: "user_message",
    payload: { text: "I prefer concise answers." },
  }),
});

const { id, salience, stored } = await response.json();

Retrieving working memory

POST /working-memory assembles a prompt-ready context string from the agent's long-term memory, filtered and ranked for relevance to the current session.

Request body

Field	Type	Required	Description
`session_id`	string	Yes	The current session — used to weight recent context.
`token_budget`	number	No	Max tokens to assemble. Defaults to the app's configured budget.
`query`	string	No	Optional semantic query to bias memory retrieval toward a topic.

Response

Returns { "context": "...", "sources": [...] }. Prepend context to your system prompt before calling your LLM.

const response = await fetch("https://{app-id}.api.enagram.io/working-memory", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer eng_...",
  },
  body: JSON.stringify({
    session_id: "sess_001",
    token_budget: 2048,
    query: "user preferences",
  }),
});

const { context, sources } = await response.json();

// Prepend context to your system prompt
const systemPrompt = context + "\n\n" + yourBasePrompt;

Outcomes

Outcomes are an optional quality signal that teach the pipeline what worked. The compiler runs automatically after every model_response event — you do not need to send an outcome for compilation to happen. When you do send one, it adjusts episode salience and procedure reinforcement weights.

Outcome values

Value	Meaning
`success`	The interaction achieved what the user wanted. Reinforces procedures.
`failure`	The interaction did not achieve what the user wanted. Weakens procedures.
`partial`	Mixed result. Neutral effect on procedure weights.
`unknown`	No signal available. Treated the same as `partial`.

Attach an outcome directly to any event via the outcome field, or send a dedicated outcome event type at the end of a session for explicit control.

The most common pattern is to omit the outcome entirely for conversational agents — the pipeline compiles after each model response with neutral weighting. Reserve explicit outcomes for cases where you have a real signal: a user clicking thumbs up/down, a task completing successfully, or a correction being made.

// Send a positive outcome after a successful interaction
await fetch("https://{app-id}.api.enagram.io/events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer eng_...",
  },
  body: JSON.stringify({
    session_id: "sess_001",
    event_type: "outcome",
    outcome: "positive",
    payload: { text: "User confirmed the answer was helpful." },
  }),
});

Observing memory state

The /observe/* endpoints let you inspect the agent's memory directly without affecting it.

Endpoint	Description
`GET /observe/summary`	Counts of events, episodes, facts, procedures, conflicts
`GET /observe/events`	Paginated raw event log
`GET /observe/episodes`	Compiled episodic memory
`GET /observe/facts`	Semantic facts with confidence scores
`GET /observe/identity`	Identity signals (stable, seasonal, volatile)
`GET /observe/procedures`	Learned procedures with success rates
`GET /observe/agents`	Paginated list of agent IDs with event activity
`GET /observe/sessions`	Paginated list of sessions for a given `agent_id`

Deleting events

DELETE /events hard-deletes events for an agent and recompiles memory from the remaining event log. Use this to honour user data deletion requests.

Query parameters

Parameter	Required	Description
`agent_id`	Yes	Delete all events for this agent.
`session_id`	No	Scope the deletion to a single session within the agent.

After deletion, compiled memory (episodes, facts, procedures, identity signals) is cleared for that agent and recompiled from whatever events remain. If all events are deleted, the agent's memory is empty.

# Delete all memory for an agent
curl -X DELETE "https://{app-id}.api.enagram.io/events?agent_id=user-123" \
  -H "Authorization: Bearer eng_..."

# Delete a single session
curl -X DELETE "https://{app-id}.api.enagram.io/events?agent_id=user-123&session_id=session-456" \
  -H "Authorization: Bearer eng_..."

Health check

GET /health returns 200 OK when the instance is ready. Use this for readiness probes or uptime monitoring.