Create an agent

Create through the collection: the document carries no `id` and no `updated_at`.

PUT/api/build/agents

Authorization

bearerAuth

AuthorizationBearer <token>

OAuth access token whose grant carries Build authorization.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A whole agent as one JSON document.

kind*string

Document discriminator.

id?string

Server id. Omit when creating.

Match

^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Formatuuid

slug?string

URL slug. Cannot change after creation.

Length1 <= length <= 160

status?string

Read-only lifecycle status.

Value in

"draft"
"active"
"archived"

updated_at?string

Version stamp. Required on replace; travels as If-Match too.

Match

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$

Formatdate-time

name*string

Display name.

Length1 <= length <= 80

description*|

What the agent does.

icon*|

Icon preset.

space*

Where the agent lives.

folder*|

Folder path within the space.

instructions*string

The system instructions.

Lengthlength <= 8192

model*string

Model id, e.g. spinrun default or a named model.

Length1 <= length <= 120

max_steps*integer

Maximum tool steps per run.

Range1 <= value <= 40

reasoning_effort?|

Absent = the model default.

tools*

What the agent may touch.

skills*array<>

Marketplace skill slugs.

Itemsitems <= 50

workspace_skills*array<>

Workspace skill names.

Itemsitems <= 20

workflows*array<>

Workflow slugs the agent may run.

Itemsitems <= 20

schedule*

When the agent runs on its own.

email*

The email channel.

whatsapp*

The WhatsApp channel.

triggers*array<||>

Event triggers, at most 20.

Itemsitems <= 20

eval_criteria*|

How a run is judged.

Response Body

`application/json`

curl -X PUT "https://example.com/api/build/agents" \  -H "Content-Type: application/json" \  -d '{    "kind": "spinrun.agent/v1",    "name": "string",    "description": "string",    "icon": "string",    "space": {      "team": "string"    },    "folder": "string",    "instructions": "string",    "model": "string",    "max_steps": 1,    "tools": {      "apps": [        "string"      ],      "connections": "all",      "disabled_tools": [        "string"      ],      "approval": "destructive"    },    "skills": [      "string"    ],    "workspace_skills": [      "string"    ],    "workflows": [      "string"    ],    "schedule": {},    "email": {},    "whatsapp": {},    "triggers": [      {        "kind": "webhook",        "name": "string"      }    ],    "eval_criteria": "string"  }'

{  "data": {    "document": null,    "applied": [      "string"    ],    "changes": [      "string"    ],    "version": 0,    "webhook_urls": [      {        "trigger_id": "string",        "url": "string"      }    ]  }}

Authorization

Request Body

Response Body

201application/json

400application/json

401application/json

403application/json

404application/json

409application/json

413application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`