Create an agent (draft)

Creates a new agent as an unpublished draft. Requires the agents:write scope; a personal key also needs the member role or above. Edits change the DRAFT only: nothing reaches end users until POST …/publish.

Authorization

apiKey

AuthorizationBearer <token>

An organization API key, created from a Portal's Webhooks page (Provisioning API card). The secret is shown once at creation and stored only as a hash. Keys are organization-wide and carry scopes (end_users:read, end_users:write). Rate limit: 120 requests per minute per key (sliding 60-second window).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

name*string

Length1 <= length <= 200

description?string

Lengthlength <= 1000

identity?

systemInstruction?string

Lengthlength <= 60000

model?string

A model id from GET /models.

builtIns?

flows?array<>

Ids of this organization's Flows the Agent may run as tools. Agents and Apps cannot be linked; combine Agents in an App. Replaces the set.

outputTemplateIds?array<>

expectedUpdatedAt?string

The updatedAt you last read; the write is refused with 409 when the Agent changed since.

Formatdate-time

systemInstructionPatch?array<|||>

Edit the current system prompt in place instead of re-sending it (400 when combined with systemInstruction). Read it from GET /agents/{agentId}/draft first. Anchors (oldString, anchor, from, to) must appear exactly once in the current text, or the whole patch is refused and nothing changes. Ops apply in order, each against the result of the previous. Quote the exact text you read, including whitespace; widen an anchor with surrounding words when it is ambiguous. Up to 50 ops per request. When expectedUpdatedAt is omitted the write is fenced to the draft as it was read for the patch.

Items1 <= items <= 50

Response Body

`application/json`

curl -X POST "https://example.com/agents" \  -H "Content-Type: application/json" \  -d '{    "name": "string"  }'

{  "agent": {    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",    "name": "string",    "slug": "string",    "description": "string",    "identity": {      "role": "string",      "summary": "string",      "goals": [        "string"      ],      "outOfScope": [        "string"      ],      "personaTraits": [        "string"      ],      "guardrails": [        "string"      ]    },    "systemInstruction": "string",    "model": "string",    "builtIns": {      "webSearch": true,      "webScrape": true,      "deepResearch": true,      "artifacts": true,      "voice": true    },    "knowledge": [      {        "knowledgebaseId": "2eaa043e-18a5-42f0-bbe8-1ad77d6f870c",        "title": "string"      }    ],    "flows": [      "296be27b-8940-42a8-afe0-671ad4f98a49"    ],    "integrations": [      {        "toolkit": "string",        "name": "string",        "selectedTools": [          "string"        ]      }    ],    "outputTemplateIds": [      "5831a25f-4029-4bf0-a840-00b3a08a5179"    ],    "conversationStarters": [      "string"    ],    "questions": [      {        "id": "string",        "label": "string"      }    ],    "published": true,    "productionVersionId": "a45124a6-f1ae-495a-9d4c-946315091da1",    "versionCount": 0,    "lastChange": {      "at": "2019-08-24T14:15:22Z",      "by": "string",      "source": "ui",      "action": "string",      "summary": "string"    },    "createdAt": "2019-08-24T14:15:22Z",    "updatedAt": "2019-08-24T14:15:22Z"  }}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

422application/json

429application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`