Authentication

All Aigeon API calls authenticate with an API key passed in the X-Api-Token header. Keys are issued per organization and can be scoped to specific permissions — see API keys & permissions.

Base URL

https://api.aigeon.ai

Every endpoint in this reference sits under that host. For development, point at the staging environment via https://api-stage.aigeon.ai.

Minimal request

curl -X POST https://api.aigeon.ai/public/api/v1/contacts/add-group-members \
  -H "X-Api-Token: sk_<your_key>" \
  -H "Content-Type: application/json" \
  -d '{ "group_id": "sg_abc", "members": [{ "email": "alice@example.com" }] }'

Response envelope

Every response has a standard shape:

{
  "code": 0,
  "status": "success",
  "message": "",
  "data": { ... }
}

code: 0 means success; any non-zero value indicates an error (see Errors & rate limits).
data carries the actual payload — varies per endpoint.

Route classes

Aigeon groups endpoints by authentication scheme:

| Prefix | Who can call | Auth | | --- | --- | --- | | /public/api/v1/* | External integrations | X-Api-Token (API key) or JWT | | /api/v1/* | Web console (your own users) | JWT cookie | | /internal/api/v1/* | Service-to-service within VPC | Internal only | | /webhook/* | Inbound from Stripe, SES, etc. | Upstream-specific signatures |

When automating your own org, stick to /public/api/v1/* — every endpoint you'll use is documented there.

Swagger / OpenAPI

The full endpoint list with request/response schemas is served from each Aigeon deployment:

Production: https://api.aigeon.ai/public/swagger/index.html
Staging: https://api-stage.aigeon.ai/public/swagger/index.html

Import the /public/swagger/doc.json file into Postman, Insomnia, or any OpenAPI tooling.