Platform overview
Agentency turns your content into a chatbot that can answer questions about it, hold a conversation across channels, and call your own systems when talking is not enough.
The public API is how your servers drive that: create bots, feed them knowledge, send messages, read conversations, and get told when something happens.
The shortest useful description
- A chatbot is the unit. Knowledge, conversations and tools all belong to one.
- You give it content. Text, files, web pages, whole sites.
- It indexes that content, which takes a moment and happens in the background.
- You send messages. Answers come back grounded in your content, with citations.
- It tells you when things happen — training finished, a visitor wants a human, your tool failed.
If you want to see that end to end, Build your first bot is one page and about ten minutes.
Four surfaces, different jobs
Dashboard — the browser app. Humans manage bots, review conversations, handle billing, and mint API keys. Anything irreversible or credential-bearing lives here on purpose.
Public API (/v1) — server-to-server, authenticated with an
agy_live_ or agy_test_ key. Everything on this site documents this surface.
Widget and hosted agent — chat for your visitors, embeddable on your site or linkable as a page. Designed to be public: it carries no account credentials, so it is safe in a browser in a way an API key never is.
SDKs — TypeScript (Node.js 20 or later, server-side) and Python clients
over /v1, generated from the same spec these docs are rendered from.
Which one do I want
| I want to… | Use |
|---|---|
| Sync knowledge from my CMS | API — POST /v1/knowledge |
| Put a chat bubble on my marketing site | Widget |
| Mirror conversations into a warehouse | API — GET /v1/conversations |
| Answer questions inside my own product UI | API — POST /v1/chat from your server |
| Let the bot check an order in my system | API — Actions |
| Change a password or enable 2FA | Dashboard only |
| Invite a colleague, or pay an invoice | Dashboard only |
Bundled JavaScript, mobile binaries and public repositories are all readable. Call the API from your server; use the widget for anything in a page. The API does not answer cross-origin requests from your web pages, so a call from browser JavaScript fails with any key. The SDKs are server-side clients and ship no browser build.
What is deliberately not in the API
Some things are dashboard-only, and it is a decision rather than an omission:
- Credentials. No key can mint another key, so a leaked key cannot widen itself.
- Account security — passwords, two-factor, phone verification, session revocation, account deletion.
- Team administration — inviting and removing colleagues.
- Checkout and the billing portal — these produce hosted payment pages that only a human in a browser can complete.
Reading billing state is available: GET /v1/usage and
GET /v1/billing/subscription tell you where you stand on credits and
storage.
What the API is good at
- Getting content in. Text, uploads, single pages, whole sites via sitemap, and cloud imports — all through one dataset model.
- Chat. Blocking or streamed, with conversation continuity and citations.
- Reading conversations. Everything from every channel in one place.
- Tools. Let a bot call your endpoints mid-conversation, and see every run.
- Being told. Webhooks for the asynchronous things: training finished, crawl finished, tool failed, visitor wants a human, credits running low.
Conventions worth knowing before you start
- Base URL is
https://api.agentency.com, and paths already include/v1. There is no/apiprefix. - Auth is
Authorization: Bearer <key>, the form every example and SDK uses. Never put a key in a query string. - Errors all share one envelope; switch on
error.code. Errors. - Lists are cursor-paginated. No page numbers. Pagination.
- Writes take an
Idempotency-Keyso a retry is safe. Idempotency. - Versioning is by path: breaking changes ship under a new prefix
such as
/v2, and a deprecated path keeps working for 12 months after it starts sendingDeprecation: true. Versioning.
Where to go next
- Never used it before — Quickstart, then Build your first bot.
- Building an ingestion pipeline — Train a bot.
- Building a chat experience — Chat.
- Wiring up automation — Events and Webhooks.
- About to launch — Going live.
- Looking for one endpoint — the reference.