# Agent API

> Run the Waslo agent from your own code: one REST endpoint for replies, plus knowledge base, catalogue, memory and calendar — no dashboard required.

Source: https://waslo.io/docs/agent-api · Last updated: 2026-10-12

Everything the agent's answering engine does, your code can do too — including its knowledge base, memory, catalogue, calendar, configuration and usage. The Agent API exposes the same engine that answers on WhatsApp and Instagram — the same knowledge base, the same per-customer memory, the same calendar and catalogue tools — as a REST API you can call from your own product.

Full reference and key management live in the [developer portal](/developers).

## When you'd use it

- You already have an app or a website and want Waslo answering inside it, not on a channel.
- You are an agency and want to run the agent for clients under your own brand.
- You want the classification, memory or knowledge-base retrieval on their own, without the messaging layer.

If you just want an AI agent on WhatsApp or Instagram, you don't need this — connect the channel from [Integrations](/docs/connecting-channels) instead.

## One call

Send a message and a user id; get back a reply that already has memory, knowledge-base citations and tool actions applied.

```bash
curl https://api.waslo.io/v1/agent/reply \
  -H "Authorization: Bearer wsk_live_..." \
  -d '{
    "message": "Do you have a morning slot Thursday?",
    "userId": "customer_8842",
    "tools": ["calendar"]
  }'
```

The `userId` is yours to choose — it is how the agent remembers a person between calls. Reuse it and the conversation continues; change it and you get a fresh one.

## What else the API covers

| Area | What you can do |
| --- | --- |
| Replies | Text, media (image, audio, video, PDF) and voice output |
| Classification | Score a message HOT / WARM / COLD on its own |
| Memory | Read or delete what the agent remembers about a user |
| Knowledge base | Upload, list and delete documents — shared with the dashboard |
| Catalogue | Full CRUD over products — shared with the dashboard |
| Calendar | Connect Google Calendar or Cal.com without opening the dashboard |
| Config | Set the system prompt and behaviour per request or persistently |
| Usage | Credits consumed, current balance, spend cap |

Anything you upload through the API shows up in the dashboard, and anything you add in the dashboard is visible to the API. It is one workspace, not two.

## API keys

Keys are created in the [developer portal](/developers) and shown **once** — they are stored hashed, so we cannot recover one for you. Each key carries scopes — `agent`, `memory`, `kb`, `catalog`, `config`, `usage`, and `tenants` (tenants only for White-label keys) — and a key can only do what its scopes allow. You can hold up to 10 active keys per organisation; revoke one at any time.

Treat a key like a password: server-side only, never in a browser bundle or a mobile app.

## Credits and rate limits

The API always bills credits, on every plan — it is a separate product from your channel subscription, so a Growth subscription does not make API calls free. Rates are higher than channel replies because each call carries more work:

| Event | Credits |
| --- | --- |
| Text reply | 2 |
| Reply that used a tool | 3 |
| Reply that read media (image, audio, video or PDF) | 5 |
| Voice output | +2 |
| Classification | 1 |

Developer plans set your rate limit and grant a monthly credit allowance on top of what you buy. Without a plan you fall back to the default per-minute and per-day limits. You can also set a monthly spend cap so a runaway loop cannot drain your balance — requests are refused with `spend_cap_reached` once you hit it.

## Errors

Every error comes back in the same envelope, with a `request_id` worth quoting if you contact support.

| Code | Meaning |
| --- | --- |
| 400 | The request body failed validation |
| 401 | Missing or invalid API key |
| 402 | Not enough credits, or the spend cap is reached |
| 403 | The key's scopes don't cover this endpoint |
| 413 | Payload too large |
| 429 | Rate limit — retry after the interval in the header |

Pass an `Idempotency-Key` header on replies and a repeated call within 24 hours returns the original response instead of charging twice.

## Your API users stay out of the operator inbox

Conversations created through the API belong to your app's users, not to the person watching the Waslo inbox — so they are hidden from the Leads and Inbox screens by default. Add `?includeApi=true` when you want to see them.

## White-label

Tenants exist only on the White-label plan. On that plan a master key can create isolated tenant workspaces, each with its own key, knowledge base and catalogue. The parent account pays for all usage and gets a per-tenant meter for re-billing; a tenant never sees the parent's balance. Tenants have no dashboard access by design — the API is their whole surface, including [connecting a calendar](/docs/integrations).

## Next steps

- [Developer portal](/developers) — create a key, read the full reference, pick a plan
- [Knowledge base](/docs/knowledge-base) — what the agent reads before it answers
- [Product catalogue](/docs/product-catalog) — what it can sell from
- [Why this reply](/docs/why-this-reply) — the reasoning trace behind every answer

## Topics

Once your organization defines topic labels (2–8), `POST /v1/agent/reply` and `POST /v1/agent/classify` include a `topic` field, and `GET/PUT /v1/config` reads and writes `topicLabels` — fully headless, white-label included. See [Topics & Team Routing](/docs/team-routing).

`GET/PUT /v1/config` also reads and writes `replyLanguage`: `"auto"` replies in each end user's language, a language code (`"es"`, `"ar"`, `"zh-Hans"`…) always replies in that language, and `null` follows the organization's dashboard setting (the end user's language unless one is fixed).
