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.
`event_type`	string	Yes	Type of event — e.g. `user_message`, `assistant_message`, `outcome`, `correction`.
`payload`	object	Yes	Arbitrary JSON — typically `{ "text": "..." }` for message events.
`outcome`	string	No	`positive`, `negative`, or `neutral`. Used for reinforcement learning.
`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;

Sending outcomes

Outcomes teach the memory pipeline what works. Sending a positive or negative outcome after an interaction adjusts salience weights and procedure success rates over time.

// 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

Health check

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