Documentation

API reference

All docs

The Aitelier REST API lets you trigger calls, read sessions, manage subscriptions, and pull usage metrics programmatically. This page is a quick reference — the full per-endpoint documentation with request/response schemas lives in the platform UI under Connections → API → Reference.

Base URL

https://api.aitelier.org/v1

All endpoints use HTTPS with TLS 1.3 minimum. Non-TLS requests are refused.

Authentication

Every request needs a project-scoped API key:

Authorization: Bearer avp_live_…

API keys are issued in Connections → API keys, scoped per key (the scopes you grant become the only operations the key can perform), and revocable at any time. Keys are shown once at creation; we hash them at rest and cannot recover the plaintext.

Available scopes:

  • outbound:trigger — trigger outbound calls
  • sessions:read — read session metadata, outcomes, slot values
  • sessions:read:transcript — read the full transcript and recording URL (separate scope so you can audit minimum-disclosure)
  • webhooks:manage — create/update/delete webhook subscriptions
  • knowledge:manage — upload, re-index, delete knowledge base entries

Magic-link auth and JWT live behind the dashboard; API keys are the only way to talk to the API from your own code.

Idempotency

Every state-changing endpoint accepts (and on outbound, requires) an Idempotency-Key header. We dedupe identical keys for 24 hours from first receipt. Retrying with the same key returns the original response — important for safe retries on network failures.

Rate limits

Defaults per project:

  • 60 requests per minute per API key
  • 1000 requests per hour per API key
  • 5 outbound calls per minute per project

Higher limits available on request — contact sales@aitelier.org.

Every response carries the limit state:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 2026-05-13T18:42:30Z

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.
  • GET /v1/calls/{id} — fetch one call's status and full session detail.
  • GET /v1/calls?status=queued&since=2026-05-13 — list with filters.

Outbound batches

  • POST /v1/batches — start a new batch (multipart with the CSV file).
  • GET /v1/batches/{id} — batch status, progress, summary metrics.
  • GET /v1/batches/{id}/rows — paginated per-row results.

Sessions

  • GET /v1/sessions/{id} — full session detail (metadata, slot values, outcome, costs).
  • GET /v1/sessions/{id}/transcript — transcript as structured turns (requires sessions:read:transcript).
  • GET /v1/sessions/{id}/recording — short-lived signed URL to the audio file.
  • GET /v1/sessions?goal_achieved=true&since=… — list with filters.

Webhooks

  • GET /v1/webhooks — list project's subscriptions.
  • POST /v1/webhooks — create a subscription. Response carries the signing secret once.
  • PUT /v1/webhooks/{id} — update a subscription.
  • DELETE /v1/webhooks/{id} — delete a subscription.
  • POST /v1/projects/{project_id}/webhooks/{name} — inbound webhook fan-out to active sessions.

Knowledge base

  • POST /v1/knowledge/crawl — trigger a website re-crawl.
  • POST /v1/knowledge/files — upload a file (PDF, plain text).
  • GET /v1/knowledge/files — list files.
  • DELETE /v1/knowledge/files/{id} — remove a file.

Usage & billing

  • GET /v1/usage?period=2026-05 — aggregated usage for a period (minutes, tool calls, outcomes).
  • GET /v1/wallet — current wallet balance and recent transactions.
  • GET /v1/invoices — list invoices (PDFs available for download).

Error format

Every error response is JSON:

{
  "error": {
    "code": "invalid_argument",
    "message": "phone must be a valid E.164 number",
    "field": "phone",
    "request_id": "req_2c4f8a…"
  }
}

Include the request_id when you reach out to support — it lets us trace the exact request through our logs.

Common HTTP codes:

  • 400 — invalid input (the body has details)
  • 401 — missing / invalid auth header
  • 403 — auth ok but missing scope
  • 404 — resource does not exist or you cannot see it
  • 409 — conflict (e.g. idempotency-key reuse with different body)
  • 422 — semantically invalid (e.g. scenario does not exist)
  • 429 — rate limit hit
  • 500 — platform bug, we are paged on these

Versioning

The current version is v1. We follow stability-first versioning — additive changes are non-breaking, breaking changes get a new major version with a sunset window. If we introduce v2, v1 stays available for at least 12 months and we email every active integrator at least 90 days before sunset.

You opt in to pre-release behaviour with X-AVP-API-Version: v1.preview-2026-05-13 on a per-request basis. Useful for testing upcoming changes without committing.