REST APIAgents
Replace an agent document
Whole-document replace. `If-Match` and the body's `updated_at` must both equal the agent's current `updated_at`; `id` and `slug`, when present, must match the URL.
PUT
/api/build/agents/{ref}Authorization
bearerAuth AuthorizationBearer <token>
OAuth access token whose grant carries Build authorization.
In: header
Path Parameters
ref*string
Agent or workflow id or slug.
Query Parameters
force?"true"
Set to true to drop webhook triggers the new document no longer names.
Value in
- "true"
Header Parameters
If-Match*string
The document's current updated_at as an entity tag, e.g. "2026-09-01T10:00:00.000Z", or *.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
A whole agent as one JSON document.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PUT "https://example.com/api/build/agents/string" \ -H "If-Match: string" \ -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" } ] }}