Skip to content

API quickstart

This quickstart makes one authenticated call against the Agent API and then points your agent's webhook at your own endpoint. It takes about ten minutes and needs nothing but curl.

Anychat has two API surfaces. This page starts on the management plane, https://api.anychat.ai/v1.

Before you begin

  • An Anychat workspace with at least one agent.
  • The admin role, which is what minting a key requires. See Manage access.

1. Mint an API key

In the console, open Workspace ยท API Keys, create a key, and give it agents:read for now. Copy the value when it is shown: Anychat stores only a hash and cannot show it again.

export ANYCHAT_API_KEY=sk-any-...

2. Check the key

GET /v1/me introspects the token and needs no ids, which makes it the smallest end-to-end test of your setup.

curl -s -H "Authorization: Bearer $ANYCHAT_API_KEY" \
  https://api.anychat.ai/v1/me

{
  "caller": { "kind": "user", "id": "..." },
  "org": { "id": "acme", "name": "Acme", "role": "admin" },
  "isSysop": false,
  "scopes": ["agents:read"],
  "rateLimit": null
}

The org.id is your workspace id, and every management path is scoped to it. Keep it to hand:

export ANYCHAT_ORG=acme

A 401 means the key is missing, mistyped, or revoked. A 403 naming a scope means the key is valid and lacks that scope. See Responses and errors.

3. List your agents

curl -s -H "Authorization: Bearer $ANYCHAT_API_KEY" \
  "https://api.anychat.ai/v1/orgs/$ANYCHAT_ORG/agents"

Note the id of the agent you want to work with. Agent ids look like agent-acme-sdr-pj7r2qx4 and are stable.

4. Read the agent's Behavior

Everything the console shows on the Behavior page is readable through the API. The /v1 resource is still named definition.

curl -s -H "Authorization: Bearer $ANYCHAT_API_KEY" \
  "https://api.anychat.ai/v1/orgs/$ANYCHAT_ORG/agents/$AGENT/export"

Export returns the whole portable document, which is the fastest way to see the shape of an agent before you write anything. See Export and import.

5. Receive messages

Sending and receiving messages is the other surface: the Messaging API at https://gateway.anychat.ai/v4, which authenticates with a per-agent access token rather than your API key.

Point it at your endpoint:

curl -s -X PATCH \
  -H "Authorization: bearer $AGENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://example.com/anychat-events"}' \
  https://gateway.anychat.ai/v4/webhook

Anychat signs every delivery, and your endpoint verifies the signature with the agent's signing secret. Both values live under the agent's Settings in the console.

To reply, return text/anychat-aml from your endpoint and write AML: plain text plus [[...]] markers that render as cards, chips, and pickers on whatever channel the person is using.

What's next