Getting started with the API

Aymar Agents’s public API is a curated REST surface — leads, contacts, conversations, appointments, and tickets on your account — built so you can integrate your own code, your CRM, or your automation with your account without going through the web interface. It’s not a mirror of everything the Platform does: only these 5 resources have routes, no matter what your key’s permission is.

Available on the Pro and Enterprise plans. On the Starter plan, any call returns 403 PLAN_NOT_ELIGIBLE even if the key and permission are correct — see Plans and limits.

1. Create your key

API keys are created and managed from Profile → My API keys (or Settings → API keys for a company-owned key) — the full step-by-step, with screenshots, is in the API keys guide. When creating it:

• Under “What this key can do”, click “Customize” and check only the resources your integration needs — see the full list in Authentication. A key missing a resource’s permission gets 403 PERMISSION_DENIED on its routes, even if the rest of the key works fine.
• The full key is shown once: copy it into a secrets manager before closing the dialog.

2. Check your key

GET /me requires no permission of its own — just a valid key on a plan-eligible tenant — so it’s the fastest way to confirm everything is in order:

curl https://api.aymaragents.com/public/v1/me \
  -H "X-API-Key: aa_YOUR_FULL_KEY"

{
  "tenantId": "b3f5b6b0-...",
  "keyPrefix": "aa_1b2e1ebd",
  "scopes": ["tenant:leads.read", "tenant:leads.manage"],
  "plan": "pro",
  "rateLimit": { "perMinute": 180, "perDay": 50000 }
}

If scopes doesn’t include what you expected, check your key’s “Customize” selection (API keys guide, section 7) — it’s sealed at creation time, it never updates on its own.

3. Make your first business call

With a key that has tenant:leads.read, list the most recent leads:

curl "https://api.aymaragents.com/public/v1/leads?dateFrom=2026-01-01" \
  -H "X-API-Key: aa_YOUR_FULL_KEY"

Every list response uses the same pagination shape as the rest of the API — check the response’s meta field to request the next page.

Before you automate sending messages

POST /public/v1/conversations/{id}/messages and POST /public/v1/conversations/start deliver the message to the real channel, but they do not show up instantly in the Platform inbox or the visitor’s widget — a human operator sees them on their screen’s next refresh/reconnect, not in real time. If your integration needs an operator to react quickly, notify them another way (your own system, a ticket…) in addition to sending the message. Full detail in the Conversations reference group.

Where to go next

• Authentication — the X-API-Key header, the full permission catalog.
• Plans and limits — which plan you need and how many calls you can make.
• Errors — the error envelope and the full error-code catalog.
• Use cases — 5 real integrations with short code examples.
• Reference, in the sidebar — one page per operation, generated from the real OpenAPI definition.

Questions while integrating? Write to soporte@aymaragents.com.