Headless API Reference Beta

All endpoints live under:

https://api.elfa.ai/widget-api/v1

Every route requires headless auth — X-Widget-Key + x-user-identifier — except GET /key, which needs only the key. Error codes are listed in the quickstart error contract.

Feature Flags

Widget keys carry a set of feature flags (chat, feed, auto, workspace) configured per key by the Elfa team. Each group below notes the flag it requires; calling a route your key isn't flagged for returns 403 WIDGET_FEATURE_NOT_ENABLED with a missingFeatures array. Markets endpoints are ungated.

Request Semantics

• userData / limits no-clobber: any request body may carry userData (personalization) and limits (per-user caps). Requests that omit them — including every bodyless GET — preserve the previously stored values for that end-user; they are only replaced when sent again.
• No per-IP rate limit by design: a partner backend fans out for many end-users from one server IP, so per-IP throttling would punish legitimate traffic. Usage is bounded instead by per-user quota (429 QUOTA_EXCEEDED) and the key's monthly credit budget (402 FREE_CREDITS_EXHAUSTED) on the metered routes, plus an invalid-key attempt limiter.
• Metered routes: POST /chat/stream and POST /auto/chat are the two routes that enforce per-user quota and the credit budget. POST /auto/chat deliberately counts toward the same chat/session quota buckets as chat/stream.

Key

No feature flag; no x-user-identifier required.

Method	Path	Purpose
GET	/key	Introspect your widget key: id, name, partnerName, status, allowedDomains, expiresAt, lastUsedAt. Useful as an auth smoke test. The secret itself is never returned.

Chat

Feature: chat. chat/stream and chat/trending-queries are gated by chat or auto depending on mode: when analysisType is athenaBuilder the auto flag is checked instead of chat.

Method	Path	Purpose
POST	/chat/stream	Stream a chat answer as SSE. Body: message, analysisType, optional sessionId, speed, attachments.imageIds, userData, limits. Metered (quota + credits). See the quickstart for the event format.
GET	/chat/trending-queries	Trending starter queries to seed a chat UI.
GET	/chat/token-questions/:chain/:contractAddress	Suggested questions for a specific token.
GET	/chat/candlestick-chart	Candlestick chart data for chat renders. Query: tradingPair or tokenMarketSlug (one required), plus optional timeRange, candlestickInterval, platform, marketType.
GET	/chat/sessions	List the end-user's chat sessions.
GET	/chat/sessions/favorites	List the end-user's favorited sessions.
GET	/chat/sessions/:sessionId	Fetch one session with its conversation history.
GET	/chat/sessions/:sessionId/conversations/:convId/renders	Fetch chart/trade renders attached to a conversation turn.
PATCH	/chat/sessions/:sessionId/favorite	Toggle a session's favorite flag.
PATCH	/chat/sessions/:sessionId/title	Rename a session.
POST	/chat/sessions/:sessionId/close	Close a session.
PATCH	/chat/conversations/:convId/vote	Up/down-vote a conversation turn.

Auto

Feature: auto. Condition queries ("plans") the end-user builds and runs — same query model as the Auto product. Drafts are unactivated queries; convert activates a draft.

Method	Path	Purpose
POST	/auto/chat	Builder chat — natural language to query draft. Metered (counts toward the chat quota buckets).
POST	/auto/queries/validate	Validate a query JSON without creating it.
POST	/auto/queries/preview	Preview what a query would match right now.
GET	/auto/queries/drafts	List the end-user's query drafts.
POST	/auto/queries/drafts	Create or update a draft.
GET	/auto/queries/drafts/:id	Fetch one draft.
DELETE	/auto/queries/drafts/:id	Delete a draft.
POST	/auto/queries/drafts/:id/validate	Validate a stored draft.
POST	/auto/queries/drafts/:id/preview	Preview a stored draft.
POST	/auto/queries/drafts/:id/convert	Convert (activate) a draft into a live query.
GET	/auto/queries	List the end-user's active queries.
POST	/auto/queries	Create a query directly from query JSON.
GET	/auto/queries/:id	Fetch one query.
GET	/auto/queries/:id/eql	Fetch the compiled EQL for a query.
GET	/auto/queries/:id/evaluations	List a query's evaluation history.
GET	/auto/queries/:id/sessions	List LLM sessions produced by a query's llm actions.
GET	/auto/queries/:id/sessions/:sessionId	Fetch one LLM session's details.
POST	/auto/queries/:id/cancel	Cancel a running query.
DELETE	/auto/queries/:id	Delete a query.
GET	/auto/executions	List trigger executions across the end-user's queries.
GET	/auto/executions/:id	Fetch one execution.

Feed

Feature: feed. Responses are cached for 60 seconds.

Method	Path	Purpose
GET	/insight	Curated market insight feed.
GET	/sentiment	Market sentiment data.
GET	/feed/:id/detail	Detail for one feed item.

Search

Feature: chat.

Method	Path	Purpose
GET	/search	Search tokens and accounts. Query: keyword, searchType (array of token, ondemandToken, account), optional compact.
GET	/search/unified	Unified search across types. Query: keyword.

Workspace

Feature: workspace. Per-end-user encrypted secret store and delivery artifacts for workspace (sandbox) tools. Secrets are scoped to the (widgetKey, endUser) identity.

Method	Path	Purpose
POST	/workspace/secrets	Set a named secret for the end-user.
GET	/workspace/secrets	List the end-user's secret names (values are never returned).
DELETE	/workspace/secrets/:name	Delete a secret.
GET	/workspace/delivery/:id	Download a delivery artifact produced by a workspace run.

Markets

No feature flag required.

Method	Path	Purpose
POST	/markets/info	Market info for a token. Body: either preference: "symbol" with symbol, or chain + address.