API REFERENCE
The API
One base URL, one Bearer key, and a handful of endpoints. Everything the widget does, you can do server to server.
Base URL
Every endpoint lives under a single host. Paths are versioned with a /v1 prefix.
https://eerraa.online
Authentication
Authenticate every request with your project key as a Bearer token. Keys start with era_ and belong to one project. Create and rotate them in the admin under Settings.
Authorization: Bearer era_your_project_key
VITE_ / NEXT_PUBLIC_ variable. The browser widget never sees it, it boots from the public config endpoint instead.A missing or wrong key returns PROJECT_INVALID_KEY. If the request comes from a browser, the origin must be on your project allowlist or you get ORIGIN_NOT_ALLOWED.
User identity
Most endpoints take a user_context object that names the end user. This is what powers per-user memory, private knowledge, the vault, and scheduling.
A project runs in one of two identity modes. In open mode the identity is trusted as sent, good for personalization. In signed mode the identity is tamper-proof: you sign it server side with an HMAC secret, and that gates private uploads, the vault, per-user MCP OAuth, and the My-tasks panel.
| Field | Type | Description |
|---|---|---|
idrequired | string | Stable unique id for the end user in your system. |
name | string | Display name. |
email | string | Email address. |
role | string | Your app role, usable in policies. |
data | object | Any extra fields your tools or policies read. |
_ts | number | Unix seconds, added at sign time. Signed mode only. |
_sig | string | HMAC-SHA256 hex over the canonical identity. Signed mode only. |
On endpoints that carry the identity in a header rather than a body (history, and any GET), pass the URL-encoded JSON in the X-Era-User header.
X-Era-User: %7B%22id%22%3A%22u_42%22%2C%22_ts%22%3A1735689600%2C%22_sig%22%3A%22...%22%7D
Content types
Requests with a JSON body send Content-Type: application/json. Knowledge upload is the one exception, it is multipart/form-data.
Most responses are JSON. The chat endpoint is different: it streams text/event-stream (Server-Sent Events). Send this header to opt in.
Accept: text/event-stream
Endpoints
Each endpoint has its own page with request fields, responses, and copy-paste examples.
/v1/chatSend a message, stream the agent reply and tool activity over SSE.GET/v1/historyFetch prior messages for a session.DELETE/v1/sessions/{id}Delete a session and its history.POST/v1/feedbackRecord a thumbs up or down on a reply.PUT/v1/credentialsStore a per-user secret in the encrypted vault.POST/v1/knowledgeUpload a document to a user knowledge base.GET/v1/scheduled-tasksThe My-tasks panel: list, mark seen, update, cancel.POST/v1/oauth/mcp/startStart a per-user MCP OAuth connection.GET/v1/project-configBootstrap config the widget loads on start.When something goes wrong, the response carries a stable error code. The full list lives on the errors reference.