Skip to main content

Agent Quickstart

This guide is the fastest deterministic path for agents to run Auto end-to-end.

Use this with:

1) Pick Access Mode​

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

2) Load Endpoint Metadata (Machine-Readable)​

Manifest URL:

/agent/endpoints.manifest.json

Each entry provides:

  • method/path
  • docs route
  • required headers
  • HMAC requirement and mounted signature path template
  • payment requirement
  • request and response examples

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.
  • On mutation routes, also send x-elfa-timestamp and x-elfa-signature.
  • Sign payload as:
timestamp + method + mounted_path + body

Mounted path example:

  • request URL: /v2/auto/queries
  • signed path: /queries

x402 mode​

  • Send payment header (PAYMENT-SIGNATURE preferred; X-PAYMENT legacy).
  • 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 execution.

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 enablement state.
  4. On x402 payment failure (402), re-price and retry with valid payment payload.