AiConva API keys and endpoints
Generate campaign and project API keys, understand scopes, and see which REST endpoints power every screen in the product.
API keys
- Open Developer → Generate key.
- Name the key and pick scopes: campaigns:write for sending, projects:* for multi-workspace agency automation.
- Copy the full key (wsy_ prefix) immediately — it is shown once and only a hash is stored.
- Rotate keys by generating a replacement and deleting the old one; the table shows each key's prefix and last-used time.
The REST surface
Everything the UI does goes through JSON endpoints under /api/v1 — the same contract your integrations use. The main resources: contacts (with /import for CSV), templates (with /sync), campaigns (with /estimate and /actions for start, pause, cancel), conversations (with /messages), segments (with /preview), billing/wallet, billing/ledger, and exports.
Browser sessions authenticate with an HTTP-only cookie today; header-based key authentication for server-to-server calls is the next developer milestone — generate and scope your keys now so the cutover is a header change.
A draft OpenAPI 3.1 specification ships in the repository at openapi/mvp-api.yaml and mirrors these endpoints.
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.
This guide maps directly to a screen in AiConva.