Documentation

API reference

Documentation

The Aitelier REST API lets you trigger outbound calls, run batch campaigns, read sessions and inspect webhook subscriptions programmatically. This page is a quick reference — the interactive, always-current reference with full request/response schemas is served by the API itself at /v1/docs, and the OpenAPI document at /v1/openapi.json.

Base URL

https://public-api.beta.aitelier.org/v1

All endpoints require HTTPS.

Authentication

Every request needs a project-scoped API key:

Authorization: Bearer avp_live_…

(X-API-Key: avp_live_… works too.)

API keys are issued in the project's API keys tab, scoped per key, and revocable at any time. Keys are shown once at creation; we hash them at rest and cannot recover the plaintext. The UI identifies keys by their prefix.

Available scopes:

  • outbound:trigger — trigger outbound calls and batches
  • sessions:read — read session metadata, outcomes, slot values
  • webhooks:read — inspect webhook subscriptions and send test deliveries

The scopes you grant become the only operations the key can perform. Dashboard login (email code + JWT) is separate; API keys are the only way to talk to the API from your own code.

Idempotency

POST /v1/calls accepts an Idempotency-Key header. We dedupe identical keys for 24 hours from first receipt: retrying with the same key returns the original response, and reusing a key with a different body returns 409. Use it for safe retries on network failures.

Rate limits

Defaults per API key, per minute:

  • 100 requests for mutations (POST/PUT/PATCH/DELETE)
  • 1000 requests for reads (GET)

Every response carries the limit state:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Window: 60

When you hit a limit, you get 429 Too Many Requests and a Retry-After header. Back off and retry.

Endpoints

Outbound calls

  • POST /v1/calls — trigger one outbound call. See Outbound for the full body schema.

Outbound batches

  • POST /v1/calls/bulk — start a batch (multipart: scenarioId, optional callerIdNumber, the CSV file).
  • GET /v1/calls/batches — list batches.
  • GET /v1/calls/batches/{id} — batch status and per-state counts.
  • POST /v1/calls/batches/{id}/cancel — cancel the remaining rows.

Sessions

  • GET /v1/sessions — list, with filters scenarioId, status, from, to, plus limit/cursor pagination.
  • GET /v1/sessions/{id} — full session detail: status, outcome, slot values, goal achievement.

Session statuses: pending, live, completed, failed, abandoned.

Webhooks

  • GET /v1/webhooks — list the project's subscriptions.
  • GET /v1/webhooks/{id} — one subscription.
  • POST /v1/webhooks/{id}/test — send a test delivery to your endpoint.

Subscriptions are created and edited in the web UI — see Webhooks.

Error format

Every error response is JSON:

{
  "error": {
    "code": "VALIDATION",
    "message": "phone must be a valid E.164 number",
    "details": { … }
  }
}

Common HTTP codes:

  • 400 — invalid input (VALIDATION; the message has details)
  • 401 — missing / invalid auth (UNAUTHENTICATED)
  • 402 — wallet balance or credit limit does not cover the call (PAYMENT_REQUIRED)
  • 403 — auth ok but missing scope (FORBIDDEN)
  • 404 — resource does not exist or you cannot see it (NOT_FOUND)
  • 409 — conflict, e.g. idempotency-key reuse with a different body (CONFLICT)
  • 429 — rate limit hit (RATE_LIMIT)
  • 500 — platform bug (INTERNAL); we get alerted on these

Versioning

The current version is v1. Additive changes — new fields, new endpoints — ship without notice and are non-breaking by convention: ignore fields you do not recognise. Breaking changes get a new major version with a sunset window announced to every active integrator.