API Key Auth

Use this page for Auto integrations on /v2/auto/*. If you still need to choose between API key and x402 models, start with Auto Overview.

Base URL

https://api.elfa.ai/v2/auto

Get an API Key

Get an API key from the Elfa Developer Portal.

There is no separate Auto enablement step in the portal. A new API key can call /v2/auto/* immediately. Elfa resolves the API key to the Auto user context needed to scope queries.

Required Header

All /v2/auto/* routes require:

x-elfa-api-key: <api_key>

Never Print Secrets

Never print or log ELFA_API_KEY or full auth headers.

Do not use debug commands like echo $ELFA_API_KEY, printenv, or console.log(process.env).

If you must debug auth, log only redacted metadata such as request path and status code.

Create Example

API_KEY="your_api_key"
BODY='{"query":{"conditions":{"AND":[{"source":"price","method":"current","args":{"symbol":"BTC"},"operator":">","value":80000}]},"actions":[{"stepId":"step_1","type":"notify","params":{"message":"BTC crossed 80k"}}],"expiresIn":"24h"}}'

curl -X POST https://api.elfa.ai/v2/auto/queries \
  -H "x-elfa-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${BODY}"

Action Types

API-key Auto supports these action types:

• notify
• telegram_bot
• webhook
• llm

Endpoint Matrix

Mounted endpoints below are the routes inside /v2/auto.

Queries and Drafts

Endpoint	Purpose
GET /queries	List queries
GET /queries/:id	Get a query
GET /queries/stream	Stream notifications for all active queries
GET /queries/:id/stream	Stream notifications for one query
GET /queries/:id/sessions	List query sessions
GET /queries/:id/sessions/:sessionId	Get one query session
POST /queries/validate	Validate query syntax and estimate cost
POST /queries	Create and activate a query
POST /queries/:id/cancel	Cancel an active query
DELETE /queries/:id	Delete a terminal query
GET /queries/drafts	List drafts
GET /queries/drafts/:id	Get a draft
POST /queries/drafts	Create or update a draft
DELETE /queries/drafts/:id	Delete a draft
POST /queries/drafts/:id/validate	Validate a draft
POST /queries/drafts/:id/convert	Convert a draft into an active query

Executions

Endpoint	Purpose
GET /executions	List executions
GET /executions/:id	Get one execution

Chat and Validation

Endpoint	Purpose
POST /chat	Build or refine Auto query drafts
GET /validate-symbol/:exchange/:symbol	Check symbol support

Common Errors

• 401: missing or invalid API key
• 403: key or user is not allowed to perform the requested Auto operation
• 409: active plan limit exceeded, or lifecycle state conflict
• 422: query validation failure

Related Docs

• Model selection: Auto Overview
• Keyless mode: x402 Instructions
• Cross-product auth: Authentication