Skip to main content
Get API Key

Agent Quickstart

This Auto-specific guide is the fastest deterministic path for agents to create, monitor, and debug Auto plans end-to-end.

For cross-product agent setup — skills, llms.txt, endpoint manifest, and surface selection — start with Agent Quickstart.

Use this page after the agent has chosen Auto:

Required Sequence (Enforced)

For API key lifecycle calls, use this order exactly:

  1. POST /v2/auto/queries/validate
  2. POST /v2/auto/queries
  3. POST /v2/auto/queries/{queryId}/cancel only when status is active or recurring
  4. DELETE /v2/auto/queries/{queryId} only when status is terminal (triggered, expired, cancelled, failed)

Intent Routing (Strict)​

IntentRoute toMinimum payload contract
Account-anchored post intentsource: "tweet"args.username (no @), args.text, args.minConfidence: 80
Telegram-channel post intentsource: "telegram"one of args.chatUsername or args.chatId, plus args.text, args.minConfidence: 80
News or world-event intentsource: "events"at least one filter (args.entity, args.eventType, args.implication, …) or args.text + args.minConfidence — see Events
Official SEC filing intentsource: "sec"method, args.ticker as issuer CIK, operator/value per SEC Filings
Fuzzy world-state predicate (not naturally tweet/telegram/events)source: "llm"method: "athena_condition", args.query, args.period >= "1h"

1) Pick Access Mode​

ModeRoute PrefixPrimary Auth
API key/v2/auto/*x-elfa-api-key
x402/x402/v2/auto/*x402 payment header (+ x-elfa-agent-secret on query lifecycle routes)

2) Confirm Auto Endpoint Metadata​

For exact method, path, auth, payment, and example metadata, use the Endpoint manifest or OpenAPI.

Manifest URL:

/agent/endpoints.manifest.json

Each entry provides:

  • method/path
  • docs route
  • required headers
  • payment requirement
  • request and response examples

For runtime data, distinguish:

  • latestEvaluation.conditionStates[]: latest current-state values.
  • Auto Trigger Context on executions (triggerTime, conditionsMet, trigger): what fired.
  • trigger.matchedConditions[].match.observedValue: value observed at trigger time.

API key mode (/v2/auto/*)​

  1. POST /chat
  2. POST /queries/validate
  3. POST /queries
  4. GET /queries/{queryId}/stream (or GET /queries/{queryId} polling)
  5. GET /queries/{queryId}/sessions and GET /queries/{queryId}/sessions/{sessionId} when using llm action

x402 mode (/x402/v2/auto/*)​

  1. POST /chat
  2. POST /queries/validate
  3. POST /queries
  4. GET /queries/{queryId}/stream (or POST /queries/{queryId} polling)
  5. POST /queries/{queryId}/sessions and POST /queries/{queryId}/sessions/{sessionId} when using llm action

4) Auth Rules You Must Enforce​

API key mode​

  • Always send x-elfa-api-key.

x402 mode​

  • Send the payment header PAYMENT-SIGNATURE. x402 v2 only — X-PAYMENT is an alias for the header name, not an offer of protocol v1.
  • Persist one stable x-elfa-agent-secret per agent identity.
  • Do not rotate agent secret per request/session.

5) Runtime Pattern (Production)​

  1. Validate before create.
  2. Prefer webhook/SSE for real-time delivery.
  3. Deduplicate by event ID.
  4. Hand off to a background runner for policy and follow-up work.

Runtime Monitoring​

  • Poll GET /queries/{queryId} to inspect the latest executions array and error payloads.
  • Use GET /executions (or GET /executions/{executionId}) for action-run views and debugging.
  • Treat failed execution entries as actionable operational events for your runner.

For implementation details:

6) Failure Handling Order​

  1. Retry transient network errors with backoff.
  2. On validation failure (400/422), repair query and re-validate.
  3. On auth failures (401/403), refresh credentials or re-check key permissions.
  4. On x402 payment failure (402), re-price and retry with valid payment payload.