Create an agent
Creates an agent on this site and its first configuration version, V1 (empty instructions, stored with the status `champion` because it is the agent's current version). The new agent is offline: it answers no shopper and no live period starts. V1 can still change: save on it with `POST …/agents/{id}/versions` and `target` `{ "mode": "append", "lineId": …, "expectedHeadId": … }`, using the `lineId` and `id` returned here. Try it in the dashboard playground, then put it live with `POST …/agents/{id}/go-live`. Returns both.
Authorization
ApiKeyAuth A WorkOS org-scoped API key, created from the dashboard's organization settings page. Identifies the tenant every read and write is scoped to. Missing, malformed, unknown, revoked, expired, or non-organization-owned keys all return 401 (no distinction, so the response can't be used to probe which keys or org ids exist).
In: header
Path Parameters
The site id (prefixed site_). A site id that isn't yours is a 404, same as any other cross-tenant id.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
application/problem+json
curl -X POST "https://example.com/api/v1/sites/string/agents" \ -H "Content-Type: application/json" \ -d '{ "name": "Storefront assistant", "type": "shopping_assistant" }'{ "data": { "agent": { "id": "agt_01kvnwmagvf27rc9cze5rm9e1r", "siteId": "site_01kvnwmagvf27rc9cze5rm9e1r", "name": "Storefront assistant", "type": "shopping_assistant", "createdAt": "2026-06-28T09:24:00.000Z", "updatedAt": "2026-06-28T09:24:00.000Z", "deletedAt": null }, "version": { "id": "agtv_01kvnwmagwf27rc9d7zef4qksf", "agentId": "agt_01kvnwmagvf27rc9cze5rm9e1r", "lineId": "agvl_01kvnwmagwf27rc9d7zef4qksg", "version": 1, "label": "V1", "savedState": 0, "savedStateLabel": "V1.0", "status": "champion", "lifecycleStatus": "offline", "locked": false, "lockedReason": null, "engine": "AISA Standard 1.1", "startersAlignment": "left", "showStarterQuestions": true, "avatarUrl": null, "createdAt": "2026-06-28T09:24:00.000Z", "updatedAt": "2026-06-28T09:24:00.000Z" } }}