Migrating from personal access tokens

A personal access token (PAT) is a credential for the dashboard API — the routes the Agentency dashboard itself calls, at the root of api.agentency.com (/chatbots, /knowledge, …). An API key is the credential for the public API under /v1. They are different surfaces: different paths, scopes, error codes, pagination and account handling. A PAT is not accepted on /v1, and an API key is not accepted on the dashboard routes.

Moving an integration means moving its calls to /v1, not just swapping the secret. The /v1 surface is the one that is versioned, documented and kept stable; the dashboard routes change with the dashboard.

The official WordPress plugin connects with a personal access token and calls
the dashboard's plugin routes. Keep its token; nothing here applies to it.

What changes

Topic	Personal access token	API key
Paths	Host root: `/chatbots`, `/knowledge`, …	Under `/v1`: `/v1/chatbots`, `/v1/knowledge`, …
Secret	A dashboard bearer token	`agy_live_…` or `agy_test_…`
Header	`Authorization: Bearer <token>`	`Authorization: Bearer <YOUR_KEY>`
Scopes	Seven coarse scopes, e.g. `chatbots:read`	One scope per resource and verb, e.g. `conversations:read`
Account	Acts for whichever account `X-Account-Id` selects	Bound to the account it was minted in; no selector
Error codes	Mixed casing, e.g. `insufficient_scope`, `knowledge_name_taken`	Always `SCREAMING_SNAKE`, e.g. `INSUFFICIENT_SCOPE`
Error body	Often carries `success: false`	Never a `success` field; carries `request_id`
Lists	`page` / `per_page` with a `pagination` block	Cursors: `limit`, `starting_after`, `ending_before`
Ids in paths	Some routes take an id or a handle	Integer ids; handles through `/v1/chatbots/by_handle/{handle}`
Retries	Only a few creates accept `Idempotency-Key`	Every mutation accepts `Idempotency-Key`

A few of these deserve a closer look.

Account selection. On the dashboard routes a PAT can act in a team account by sending X-Account-Id. An API key already is the account: it acts for the account (and workspace) it was minted in, and only the account owner can mint one. An X-Account-Id naming that same account is ignored; one naming any other account is refused with 400 ACCOUNT_SELECTOR_NOT_SUPPORTED. Where workspaces are enabled, an X-Workspace-Id naming another workspace is refused the same way. To work in several accounts, mint a key in each and drop the header.

Errors. Both surfaces put the code in error.code, but /v1 codes are always upper case and never change spelling. A missing scope is 403 INSUFFICIENT_SCOPE with error.details.required, missing and granted, where the PAT answered 403 insufficient_scope with error.details.required_any_of. Switch your error handling on the /v1 code list in Errors.

Lists. Every /v1 list is a cursor list: { object: "list", data, has_more, next_cursor, previous_cursor, url }. There are no page numbers; pass next_cursor back as starting_after. See Pagination.

Chat. The dashboard chat route is the owner's preview chat and answers with the agent's test model, if one is set. POST /v1/chat answers the way the live agent does, on its production model.

Route mapping

The dashboard routes integrations most often call, and where they live on /v1. Everything on /v1 takes integer ids. The API reference has the full request and response of each.

Dashboard route (PAT)	/v1 route (API key)
`GET /chatbots`	`GET /v1/chatbots`
`GET /chatbots/{identifier}`	`GET /v1/chatbots/{id}`, or `GET /v1/chatbots/by_handle/{handle}`
`POST /chatbots`	`POST /v1/chatbots`
`PUT /chatbots/{identifier}`	`PATCH /v1/chatbots/{id}`
`DELETE /chatbots/{identifier}`	`DELETE /v1/chatbots/{id}`
`PATCH /chatbots/{identifier}/toggle-status`	`POST /v1/chatbots/{id}/activate` and `POST /v1/chatbots/{id}/deactivate`
`POST /chatbots/{chatbotId}/chat`	`POST /v1/chat`, with `chatbot_id` in the body
`POST /chatbots/{chatbotId}/chat/stream`	`POST /v1/chat/stream`, with `chatbot_id` in the body
`GET /chatbots/{chatbotId}/conversations`	`GET /v1/conversations?chatbot_id={id}` (omit it for the whole account)
`GET /chatbots/{chatbotId}/conversations/{sessionId}`	`GET /v1/conversations/by_session/{sessionId}`
`PATCH /chatbots/{chatbotId}/conversations/{sessionId}/review`	`POST /v1/conversations/{id}/review`
`POST /chatbots/{chatbotId}/queries/{queryId}/feedback`	`POST /v1/messages/{id}/feedback`
`GET /knowledge`	`GET /v1/knowledge`
`POST /knowledge`	`POST /v1/knowledge`
`POST /knowledge/upload`	`POST /v1/files`, then `POST /v1/knowledge` with the returned `file_id`
`GET /knowledge/{id}`	`GET /v1/knowledge/{id}`
`PUT /knowledge/{id}` or `PATCH /knowledge/{id}`	`PATCH /v1/knowledge/{id}`
`DELETE /knowledge/{id}`	`DELETE /v1/knowledge/{id}`
`POST /knowledge/{id}/retry`	`POST /v1/knowledge/{id}/retry`
`POST /knowledge/{id}/replace-file`	`POST /v1/knowledge/{id}/replace_file`
`GET /job-status/dataset/{dataset_id}`	`GET /v1/knowledge/{id}/status`
`GET /knowledge/collections`	`GET /v1/knowledge/collections`
`POST /knowledge/remove-from-chatbot`	`POST /v1/knowledge/remove_from_chatbot`
`GET /crawlers` and `POST /crawlers`	`GET /v1/crawlers` and `POST /v1/crawlers`
`GET /sitemap-crawlers` and `POST /sitemap-crawlers`	`GET /v1/sitemap_crawlers` and `POST /v1/sitemap_crawlers`
`POST /search/semantic`	`POST /v1/search`
`GET /billing/plans`	`GET /v1/billing/plans`
`GET /billing/subscription`	`GET /v1/billing/subscription`
`GET /billing/invoices`	`GET /v1/billing/invoices`
`GET /chatbots/{chatbotId}/widget/settings`	`GET /v1/chatbots/{chatbotId}/widget`
`PUT /chatbots/{chatbotId}/widget/domains`	`PUT /v1/chatbots/{chatbotId}/widget/domains`

Multi-word path segments use underscores on /v1 (replace_file, sitemap_crawlers), where the dashboard uses hyphens. Request bodies are close but not identical — each /v1 operation pins its own fields — so check the reference for every call you move rather than replaying the old payload.

Scope mapping

PAT scopes are coarse: chatbots:read opens conversations, customers and analytics as well as chatbots. API-key scopes are split per resource, and on every /v1 route a read scope never allows a write. Grant the key the scopes on the right for each PAT scope your integration used.

PAT scope	What it covered on the dashboard routes	API-key scopes for the same calls
`chatbots:read`	Chatbots, conversations and chat history, customers, analytics, Call Actions, channels and widget settings (reads)	`chatbots:read` · `conversations:read` · `customers:read` · `analytics:read` · `actions:read` · `channels:read` · `widget:read`
`chatbots:write`	The matching writes: chatbots, conversation review and delete, answer feedback, Call Actions, channel connect and disconnect	`chatbots:write` · `conversations:write` · `customers:write` · `actions:write` · `channels:write`
`knowledge:read`	Knowledge and collections, crawlers, semantic search, training status	`knowledge:read` · `crawlers:read` · `search:read` · `files:read`
`knowledge:write`	Knowledge writes and uploads, crawler writes	`knowledge:write` · `crawlers:write` · `files:write`
`chat:send`	The dashboard preview chat	`chat:send`
`widget:manage`	Widget allowed domains, plugin installs	`widget:write` (includes `widget:read`)
`billing:read`	Plans, subscription, invoices	`billing:read`

A write scope includes its read scope on /v1 (knowledge:write covers knowledge:read), so you do not need to grant both. Three scope families have no PAT counterpart at all: webhooks:read / webhooks:write, keys:read / keys:write (the account's request logs and revoking the calling key) and profile:read / profile:write. profile:write is high-risk: only the account owner can grant it, and it is confirmed on its own rather than through "select all". The full list is on Scopes.

Cutover

List the dashboard routes your integration calls and find each one in the route mapping above. Anything without a /v1 row is in "No /v1 equivalent" below — decide what replaces it before you start.
As the account owner, mint a test key (agy_test_…) in the dashboard under Developers → API keys, with the scopes from the scope mapping.
Move the calls to /v1: new paths, integer ids, the /v1 request bodies, cursor pagination, and SCREAMING_SNAKE error handling. Drop X-Account-Id.
Send an Idempotency-Key on every write, so a retried request replays the first result instead of running twice.
Run the integration against the test key until it is clean, then mint a live key (agy_live_…) with the same scopes and deploy it.
Watch GET /v1/request_logs (scope keys:read) for a day for failing calls.
Revoke the personal access token in the dashboard's developer settings.

No `/v1` equivalent

Some dashboard capabilities are deliberately not on /v1. They either need a person in a browser or manage credentials and people, so they stay in the dashboard:

Password, two-factor authentication, phone verification, session revocation and account deletion.
Billing checkout, add-on checkout and the billing portal (reading plans, the subscription, usage and invoices is on /v1).
Team administration: members, invitations and workspaces.
Minting or rotating credentials. No credential can create another one; a key can only revoke itself with DELETE /v1/api_keys/{id}.

Other dashboard features have no /v1 operation today: choosing an agent's answer model, keyword links, suggested messages, conversation notes and custom review statuses (GET /v1/conversations can filter by review_status_id), conversation export, and knowledge gaps. The API reference lists everything /v1 does offer.

What's next

Authentication — sending a key, test versus live, rotation.
Scopes — every scope and what it grants.
Errors — the /v1 error codes to switch on.