REST API

The Consuela API lets you start crawls, retrieve findings, and export results programmatically. Every endpoint lives under /v1 and speaks JSON over HTTPS.

Authentication

Create an API key from the Settings > API keys panel in the Consuela app. The full key is displayed once at creation time; after that only a SHA-256 digest is stored. Copy it immediately — there is no way to retrieve it later.

Pass the key in the Authorization header as a Bearer token:

curl https://api.consuela.io/v1/ping \
  -H "Authorization: Bearer csl_live_abc123..."

Requests without a valid key receive a 401 with the error code unauthenticated.

Errors

Every non-2xx response returns a JSON envelope with three fields:

{
  "error": "validation_error",
  "message": "url must be an absolute HTTP or HTTPS URL",
  "details": { "field": "url" }
}

Branch on error — it is a stable, machine-readable code. The message field is human-readable prose that may change between releases and must not be parsed. details is present when extra context is available and omitted otherwise.

Error codes

HTTP status	Error code	Meaning
`400`	`validation_error`	The request body or query parameters failed validation.
`401`	`unauthenticated`	Missing or invalid API key.
`402`	`payment_required`	The account's plan does not cover this action, or billing is past due.
`404`	`not_found`	The requested resource does not exist or is not visible to this key.
`409`	`conflict`	The resource has been modified since you last read it. Re-fetch and retry.
`429`	`rate_limited`	Too many requests. Back off and respect the `Retry-After` header.
`500`	`internal_error`	An unexpected server error. Retry with backoff; if it persists, contact support.

Pagination

List endpoints return cursor-based pages. Each response wraps the result set in a standard envelope:

{
  "data": [ ... ],
  "nextCursor": "eyJpZCI6MTIzfQ"
}

When nextCursor is null, you have reached the end. To fetch the next page, pass the cursor as a query parameter:

GET /v1/findings?cursor=eyJpZCI6MTIzfQ&limit=100

limit defaults to 50 and accepts a maximum of 200. Cursors are opaque strings — do not parse, construct, or store them beyond the current pagination run.

Rate limits

Each API key has two independent rate limits:

Operation	Limit
Read requests (GET)	60 per minute per key
Crawl starts (POST `/v1/crawls`)	10 per minute per key

When a limit is exceeded the API returns 429 rate_limited with a Retry-After header indicating the number of seconds to wait before retrying.