Auto Beta

This page covers the API-key + HMAC auth model for /v2/auto/*.

The external Auto API is exposed at:

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

Auth Model

All /v2/auto/* routes require:

x-elfa-api-key

For mutation endpoints, also require:

x-elfa-signature
x-elfa-timestamp

HMAC Signing

Headers:

x-elfa-signature: <hex_hmac_sha256>
x-elfa-timestamp: <unix_seconds>

Payload format:

timestamp + method + path + body

Where:

timestamp: unix seconds
method: uppercase HTTP method
path: route path verified by Auto router
body: exact JSON string body, or empty string

Replay window: ±30 seconds.

Important mounted-router detail:

Request URL may be /v2/auto/queries
Signature path must be /queries (the mounted router path)

Using /v2/auto/queries in the signed payload will fail verification.

Concrete Signing Example

Example target endpoint: POST /v2/auto/queries

import crypto from "crypto";

const hmacSecret = process.env.ELFA_HMAC_SECRET!;
const timestamp = Math.floor(Date.now() / 1000).toString();
const method = "POST";
const path = "/queries"; // mounted path (NOT /v2/auto/queries)

const bodyObj = {
  title: "BTC Alert",
  query: {
    conditions: {
      AND: [
        {
          source: "price",
          method: "current",
          args: { symbol: "BTC" },
          operator: ">",
          value: 100000,
        },
      ],
    },
    actions: [
      {
        stepId: "step_1",
        type: "notify",
        params: { message: "BTC crossed target" },
      },
    ],
    expiresIn: "24h",
  },
};

const body = JSON.stringify(bodyObj);
const payload = `${timestamp}${method}${path}${body}`;
const signature = crypto
  .createHmac("sha256", hmacSecret)
  .update(payload)
  .digest("hex");

console.log({ timestamp, signature, body });

Then send:

POST /v2/auto/queries
x-elfa-api-key: <api_key>
x-elfa-timestamp: <timestamp>
x-elfa-signature: <signature>
content-type: application/json

<body exactly as signed>

No-body example (DELETE /v2/auto/queries/{id}): sign with path = "/queries/{id}" and body = "".

Enablement Requirements

API keys must be Auto-enabled and linked to a user identity in the Developer Portal. If not enabled/linked, /v2/auto/* returns 403.

Endpoint Matrix

Queries and Drafts

Endpoint	HMAC
`GET /queries`	No
`GET /queries/:id`	No
`GET /queries/:id/evaluations`	No
`GET /queries/:id/stream`	No
`GET /queries/:id/sessions`	No
`GET /queries/:id/sessions/:sessionId`	No
`POST /queries/validate`	No
`POST /queries/preview`	No
`POST /queries`	Yes
`DELETE /queries/:id`	Yes
`GET /queries/drafts`	No
`GET /queries/drafts/:id`	No
`POST /queries/drafts`	No
`DELETE /queries/drafts/:id`	No
`POST /queries/drafts/:id/preview`	No
`POST /queries/drafts/:id/convert`	Yes

Executions

Endpoint	HMAC
`GET /executions`	No
`GET /executions/:id`	No

Chat

Endpoint	HMAC
`POST /chat`	Yes

Exchange Connections

Endpoint	HMAC
`GET /exchanges`	No
`POST /exchanges`	Yes
`DELETE /exchanges/:exchange`	Yes

Common Errors

401: missing/invalid key, signature, timestamp, or clock skew
403: Auto not enabled for the API key or no linked user
422: validation failure (query content)

Reusable Implementation Guides

Use the guides below for query design, notifications, and runner architecture:

For keyless pay-per-request usage, see x402 Instructions.

Auth Model​

HMAC Signing​

Concrete Signing Example​

Enablement Requirements​

Endpoint Matrix​

Queries and Drafts​

Executions​

Chat​

Exchange Connections​

Common Errors​

Reusable Implementation Guides​