Create an agent
Creates an agent on this site, and its first configuration version (v1, champion, empty instructions) so the agent is usable immediately. 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", "version": 1, "status": "champion", "createdAt": "2026-06-28T09:24:00.000Z", "updatedAt": "2026-06-28T09:24:00.000Z" } }}