AiConva API keys and endpoints

API keys

1. Open Developer → API keys and name the key after the system that will use it.
2. Tick only the permissions it needs: messages:send, messages:read, contacts:read, contacts:write, templates:read.
3. Copy the full key (wsy_live_ prefix) immediately — it is shown once and only a hash is stored.
4. Rotate by creating a replacement, switching your system over, then revoking the old key; the table shows each key's prefix and last-used time. Revoking takes effect instantly.

Calling the API

Send the key as a header: Authorization: Bearer wsy_live_… . Keys are tied to one workspace, limited to the permissions you ticked, and rate-limited to 120 requests a minute.

The public endpoints are: POST /api/v1/messages (send an approved template to one number; body: to, template, params), GET /api/v1/messages/{id} (delivery status), GET and POST /api/v1/contacts, and GET /api/v1/templates. Billing, settings, team and flow endpoints are never available to a key.

Consent is enforced by the API itself: marketing templates only reach contacts who are opted in, and nothing reaches a contact who opted out. Every send is charged to your wallet at the template category rate and refunded automatically if it fails.

Add an Idempotency-Key header (up to 200 characters) to any send. Repeating the request with the same key returns the original result and never sends or bills twice, which makes retries safe.

The Developer page has a full API reference with copy-ready curl examples, and a draft OpenAPI file ships in the repository at openapi/mvp-api.yaml.

Error handling

Errors return a consistent envelope: { "error": { "code", "message", "details" } } with conventional HTTP status codes (400 validation, 401 auth, 403 role, 404 missing, 502 upstream Meta errors). Validation failures list the exact offending fields in details.