**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](/en/api/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](/en/guides/claves-api/)** 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](/en/api/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:

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

```json
{
  "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:

```bash
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](/api/reference/operations/tags/conversaciones/)** reference group.

## Where to go next

- **[Authentication](/en/api/authentication/)** — the `X-API-Key` header, the full permission catalog.
- **[Plans and limits](/en/api/plans-and-limits/)** — which plan you need and how many calls you can make.
- **[Errors](/en/api/errors/)** — the error envelope and the full error-code catalog.
- **[Use cases](/en/api/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**.