Test mode
Test keys let you exercise the entire API — every endpoint, every error, every webhook — without spending message credits.
Mint one from the same place as a live key; the prefix tells you which you are holding.
What changes
agy_test_ | agy_live_ | |
|---|---|---|
| Message credits | Not debited | Debited |
| Default rate limit | 60 requests/minute | 600 requests/minute |
Webhook mode | test endpoints allowed | live endpoints, HTTPS required |
The lower rate limit is deliberate: development traffic is bursty and
accidental, and a tighter limit turns a runaway loop into a 429 instead of a
surprise.
What does not change
Everything else. Scopes, the error envelope, idempotency, version headers, pagination, webhook signing — identical. That is the point: an integration that works against a test key works against a live one, with no code differences.
A test key reads and writes your **real account**. It does not spend live credits; it will happily delete a real chatbot. If you want somewhere disposable, create a chatbot for the purpose rather than assuming the key protects you.
A development setup that works
- Create a chatbot named something obvious like "Dev — do not use", and do your experimenting there.
- Use a test key locally and in CI. Keep the live key out of both.
- Register a `test`-mode webhook endpoint pointing at a tunnel to your machine.
- Seed one small knowledge source. A short text dataset trains in seconds, where a large PDF makes every test slow.
- Point staging at its own test key, so revoking a developer's key does not break the shared environment.
Webhooks in development
Webhook URLs go through the same safety checks in both modes: internal addresses and private ranges are refused, because a URL that looks harmless in development is a way into the network in production.
For local work, use a tunnelling service so your machine has a real public
HTTPS URL. Register that as a test endpoint. Signature verification behaves
exactly as it will in production, which is what you want — the failure mode you
most need to rehearse is a verifier that rejects valid deliveries.
POST /v1/webhook_endpoints/{id}/test sends a ping through the real
pipeline, so you can confirm the whole path without waiting for something to
happen.
Moving to live
- Mint a separate live key. Do not promote the test key you have been pasting into terminals.
- Grant the same scopes — no more, and check whether any were only needed for experimenting.
- Register a live webhook endpoint. Test endpoints are not promoted automatically.
- Re-check your rate handling: the live limit is higher, so a bug that showed up as 429s in development may not show up until production load.
See Going live for the full checklist.
Common mistakes
- Assuming test data is isolated. It is your real account.
- Testing with an unrealistically small dataset. Training time and answer quality both change with volume; a one-paragraph source teaches you little.
- Only ever seeing the happy path. Force a
429, an expired key, and a webhook signature failure at least once before launch. - Forgetting the live webhook endpoint. A common launch-day surprise: the integration works, but nothing is being delivered anywhere.
What's next
- Authentication — key formats and rotation.
- Webhooks — receiving events locally.
- Going live — the switch to a live key.