API
The ARAYA Public API covers projects, uploads, subtitle scenes, rendering, credits, webhooks, and API keys.
The OpenAPI source is maintained at apps/web/openapi/v1.yaml, and the VitePress API Reference is generated from that file at build time.
Webhook signatures and key rotation
Keep the raw HTTP body. Split X-Araya-Signature on commas and preserve all repeated v1 values in an array. Normally the header is t=<unix>,v1=<hex>; during the 24-hour rotation grace period it is t=<unix>,v1=<new>,v1=<previous>. A single-value map can retain only the previous signature, causing verification with the new key to fail.
Use TLS. Require signed t to match X-Araya-Timestamp and fall within five minutes of the current time. Compute HMAC-SHA256("<timestamp>.<raw body>", key) with your configured key. Compare every v1 candidate in constant time and accept when any candidate matches. The previous signature is no longer sent after 24 hours.
Keys are returned only in the initial creation or rotation response; idempotent replay cannot recover them. If lost, disable the endpoint with DELETE /v1/webhooks/{webhook_uuid}, create a replacement with POST /v1/webhooks, and configure its new key at your receiver. Delivery stops for the disabled endpoint. Rotation during the grace period or for a disabled endpoint returns 422 webhook_rotation_unavailable.