Glossary

• Account owner — the account a key belongs to and acts as. All data you can reach through the API belongs to this account.
• API key — an agy_live_… or agy_test_… secret bound to one account. It is sent as Authorization: Bearer <YOUR_KEY>.
• Live key / test key — the two key modes, named by the prefix. Both reach the same contract; test keys get a lower default per-minute budget.
• Chatbot — an AI agent on the account. The dashboard calls it an agent; the API calls it a chatbot.
• Dataset — one knowledge source: an uploaded file, inline text, a website or sitemap crawl, or a cloud import.
• Collection — a named group of datasets.
• Event — a record that something happened, delivered to your webhook endpoints and readable from GET /v1/events.
• Scope — a resource:verb grant on a key, such as chatbots:read. A write scope includes the matching read scope.
• High-risk scope — a scope that changes account-level settings rather than content. profile:write is the only one: owner-only at mint, excluded from select-all, and confirmed individually.
• Cursor — the opaque next_cursor / previous_cursor a list returns. Pass it back as starting_after / ending_before; it only works on the list and sort order that produced it.
• Idempotency key — the Idempotency-Key header on a write. Retrying with the same key and body replays the first successful response with Idempotency-Replayed: true; the same key with a different body is 422 IDEMPOTENCY_KEY_REUSED.
• Request ID — the X-Request-ID response header, repeated as request_id in every error body. Quote it when you report a problem.

Every resource in a response names its type in object. The table lists every object value the API returns, generated from the OpenAPI document.

• Scopes — every scope and what it grants.
• Errors — the error envelope and codes.
• Pagination — how cursors work.