API reference

Base URL

Every route on this page lives under https://api.arapulse.com/api/v1. Requests are JSON over HTTPS; responses are JSON, or the audio file itself on the synthesis endpoints. The one exception to the prefix is GET /health, the bare liveness probe.

Authentication

Two credential types. A sk_live_ or sk_test_ secret key authenticates server-to-server calls and must never reach a browser. For client-side use, mint a short-lived st_ session token from your own backend and hand that over instead.

# Server to server — a secret key.
curl https://api.arapulse.com/api/v1/characters \
  -H "Authorization: Bearer sk_live_..."

# Browser — a short-lived session token you minted server-side.
curl https://api.arapulse.com/api/v1/avatars/abc/chat \
  -H "Authorization: Bearer st_..."

Errors and limits

Errors come back with a consistent envelope and a meaningful status code. Quota exhaustion is a 429 and is refused rather than silently billed.

{
  "success": false,
  "error": {
    "message": "Daily quota exceeded for this API key",
    "statusCode": 429,
    "timestamp": "2026-08-01T19:14:08.508Z"
  }
}

• 401 — missing or invalid credential.
• 403 — the key is valid but lacks the scope.
• 429 — rate limit or daily quota exhausted.
• 501 — the capability exists but is not connected yet, such as adding a payment method.
• 503 — an upstream model container is unavailable. Check status.

Rate limiting is applied per key across the whole /api/v1 surface, and daily quotas are enforced on every key-authenticated route rather than only at the edge.

Webhooks

Register an endpoint and subscribe it to any of the seven events. Deliveries retry with backoff on failure, and recent attempts are visible on the webhook record.

Verifying a delivery

Each request carries an X-AraPulse-Signature-V2 header of the form t=<timestamp>,v1=<signature>. The signature is an HMAC-SHA256 over `${timestamp}.${rawBody}` using your webhook secret.

import crypto from "crypto";

export function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(
    header.split(",").map(p => p.split("="))
  );

  // Reject replays before spending time on the digest.
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!(age < 300)) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  // Constant time — a plain === leaks the digest byte by byte.
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(parts.v1)
  );
}

Spec coverage