Documentation

Four steps to a first call.

Smara is a REST API. There is no SDK you have to adopt and no agent framework you have to move to — if it can send an HTTP request with a bearer token, it can use Smara.

Open the API reference Download openapi.json

Quickstart

Create an account

Issue an API key

From the portal, create a key and copy the secret. It is shown exactly once and stored only as a hash.

API keys

Assemble your first context

Call POST /v1/context with an agent id and a query. On a fresh tenant it returns an empty set — that is the correct answer, and it means auth works.

Reference

Write what happens

Append turns, tool calls and outcomes to POST /v1/episodes. Consolidation picks them up from there — no further wiring.

How consolidation works

Authentication

Two callers, two credentials.

Agents call the data plane with a per-tenant API key: Authorization: Bearer smara_live_…. A key resolves to exactly one tenant and carries scopes such as memory:read and memory:write.

People call the control plane — tenants, members, keys — with a Firebase ID token from the portal session. Control-plane endpoints will not accept an API key, and data-plane endpoints will not accept an ID token.

Secrets are shown once at creation and stored only as a SHA-256 hash. There is no endpoint that returns a key secret, including to the person who created it. Lose it and you revoke and reissue.

first call

export SMARA_API_URL="https://<your-memory-api-host>"
export SMARA_API_KEY="smara_live_…"

curl "$SMARA_API_URL/v1/context" \
  -H "Authorization: Bearer $SMARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"support-copilot","query":"hello","token_budget":1000}'

write an episode

curl "$SMARA_API_URL/v1/episodes" \
  -H "Authorization: Bearer $SMARA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess_9f21",
    "agent_id": "support-copilot",
    "kind": "tool_call",
    "payload": { "tool": "crm.lookup", "args": { "org": "acme" } }
  }'

What is here today

The interactive API reference is live and generated from the service itself. Long-form guides — consolidation tuning, graph modelling, retention policy — are still being written. Until they land, the reference plus the architecture page are the complete picture.