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 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 browser build of the TypeScript SDK refuses `agy_live_` keys outright.
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>. Nothing else is accepted. - 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 date and pinned per key. 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.