Authentication

All API requests require authentication via headers.

Required Headers

Every request to the Warm AI API must include the following headers:

Header	Type	Description
`x-access-key`	UUID	Your API key, generated from the platform dashboard
`x-idempotency-key`	UUID	A unique identifier for this request to prevent duplicate processing
`x-user-id`	UUID	The ID of the connected user on whose behalf the request is made

Example Headers


{
  "Content-Type": "application/json",
  "x-access-key": "550e8400-e29b-41d4-a716-446655440000",
  "x-idempotency-key": "6fa459ea-ee8a-3ca4-894e-db77e160355e",
  "x-user-id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Idempotency Keys

Idempotency keys prevent duplicate processing when you retry a request. If a request with the same idempotency key has already been processed, the API returns the existing result instead of creating a new one.

Best Practices

Generate a new UUID for each unique request
Reuse the same UUID when retrying a failed or timed-out request
Use UUID v4 format for maximum uniqueness

Examples

JavaScript:


const idempotencyKey = crypto.randomUUID();
// e.g. "3b241101-e2bb-4d52-8b45-6a8e9c7d3f01"

Python:


import uuid
 
idempotency_key = str(uuid.uuid4())
# e.g. "3b241101-e2bb-4d52-8b45-6a8e9c7d3f01"

Bash:


IDEMPOTENCY_KEY=$(uuidgen | tr '[:upper:]' '[:lower:]')
# e.g. "3b241101-e2bb-4d52-8b45-6a8e9c7d3f01"

API Validation

The API validates requests in the following order. If validation fails, the corresponding error is returned:

Validation	HTTP Status	Error Message
API Key	`401 Unauthorized`	Invalid or missing API key
Origin	`403 Forbidden`	Request origin not in allowlist
Balance	`402 Payment Required`	Insufficient credit balance
Localhost	`403 Forbidden`	Requests from localhost are never allowed

Origin Validation

API keys can be restricted to specific origins (domains). Wildcard support is available for subdomains:

Pattern	Matches
`https://app.example.com`	Exact match only
`https://*.example.com`	Any subdomain of example.com
`https://example.com`	Root domain only

Localhost is never allowed. Requests from localhost, 127.0.0.1, or any loopback address are always rejected, regardless of origin configuration. Use a tunnelling service (e.g. ngrok) for local development.

Credit Estimates

Each API operation consumes credits. Here are the approximate costs:

Operation	Credits (approx.)
Research Summary	~15
Message Generation	~15
Full Workflow	~30

100 credits = £1.00. A full end-to-end message costs approximately £0.30.