ReferenceHTTP APIAgents
Create an agent and its first card version
POST
Without runtime_profile_id nothing is released or activated. With it the save makes the first release on that profile and activates it, as PATCH /v1/agents/{id} does; model_source defaults to profile, which runs the profile's default model. The agent and its card are kept when the release is refused: release.status is then failed with the reason, and the agent's draft holds the request until a new save. The creator administers the agent. managing_team_id is required (400 BAD_REQUEST with a details.issues entry at managing_team_id when absent): an owner or admin names any live team (404 when there is none by that id), anyone else only a team they are in (403 FORBIDDEN, details.reason_code team_not_allowed). A slug already used in the workspace answers 409 ALREADY_EXISTS. API keys are refused.
Auth: cookie session only; no scope. Idempotency-Key: ignored.
cookieSessioncookie
__Host-werft_session<token>For the web console: the browser session cookie set by POST /v1/auth/login. It holds the scopes of the user's workspace role (owner: all; admin and member: all but sessions:recover). Requests other than GET must also send X-Requested-With: werft-web.
X-Requested-With?"werft-web"Required with a cookie session: the literal werft-web.
Value in
"werft-web"application/json- body
slug*stringMatch
^[a-z0-9][a-z0-9-]*$Length
1 <= length <= 64name*stringLength
1 <= length <= 120description?stringLength
length <= 2000managing_team_id*stringMatch
^([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)$Format
uuidcard*runtime_profile_id?stringLength
1 <= length <= 128model_source?stringValue in
"fixed""profile"Success
application/json- response
agent*versions*array<>releases*array<>active_release*|nullbehavior_revision*integerRange
0 <= value <= 2147483647model_source*stringValue in
"fixed""profile"draft*|nulleffective_behavior*profile_tracking?stringValue in
"follow""pinned"profile_rollout?|nullrelease*curl -X POST 'https://example.com/v1/agents' \ -H 'Content-Type: application/json' \ -d '{ "slug": "string", "name": "string", "managing_team_id": "911b0313-617e-40f5-9150-864225bf0223", "card": { "model": "string", "capabilities": { "mcp": [ { "server": "string" } ] } }}'Example Response
{ "agent": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "workspace_id": "0967198e-ec7b-4c6b-b4d3-f71244cadbe9", "slug": "string", "name": "string", "description": "string", "managing_team_id": "911b0313-617e-40f5-9150-864225bf0223", "managing_team_name": "string", "status": "active", "active_release_id": "string", "activation_revision": -1, "auto_model_migration": true, "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "created_at": "2019-08-24T14:15:22Z", "updated_at": "2019-08-24T14:15:22Z" }, "versions": [ { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "version_no": 1, "card": { "role": "string", "instructions": "string", "language": "follow-user", "model": "string", "capabilities": { "mcp": [ { "server": "string" } ], "forbidden": [], "tool_policy": { "per_tool": { "property1": "allow", "property2": "allow" } }, "credential_refs": [ "string" ], "env": [ { "name": "string" } ] }, "rules": [] }, "content_sha256": "string", "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "created_at": "2019-08-24T14:15:22Z" } ], "releases": [ { "id": "string", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c", "card_sha256": "string", "runtime_profile_id": "string", "repository_id": "string", "profile_digest": "string", "runtime_config_snapshot": { "property1": null, "property2": null }, "effective_tools": { "tools": [ "string" ], "mcp": [ "string" ] }, "policy_pins": { "tools": { "default": { "builtin": "allow", "mcp": "allow" }, "per_tool": { "property1": "allow", "property2": "allow" } }, "github": { "repositories": [ "string" ], "push_approval": true, "features": { "workflows": true, "actions": true, "checks": true, "issues": true, "review": true }, "actions_allow": [ { "workflow": "string", "ref": "string" } ] } }, "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "created_at": "2019-08-24T14:15:22Z", "approved_by": "02030314-b162-4b4d-8af1-88eabdcc615d", "approved_at": "2019-08-24T14:15:22Z", "note": "string", "label": "string", "activated_at": "2019-08-24T14:15:22Z", "deactivated_at": "2019-08-24T14:15:22Z" } ], "active_release": { "id": "string", "agent_id": "2b1e3b65-2c04-4fa2-a2d7-467901e98978", "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c", "card_sha256": "string", "runtime_profile_id": "string", "repository_id": "string", "profile_digest": "string", "runtime_config_snapshot": { "property1": null, "property2": null }, "effective_tools": { "tools": [ "string" ], "mcp": [ "string" ] }, "policy_pins": { "tools": { "default": { "builtin": "allow", "mcp": "allow" }, "per_tool": { "property1": "allow", "property2": "allow" } }, "github": { "repositories": [ "string" ], "push_approval": true, "features": { "workflows": true, "actions": true, "checks": true, "issues": true, "review": true }, "actions_allow": [ { "workflow": "string", "ref": "string" } ] } }, "created_by": "ee824cad-d7a6-4f48-87dc-e8461a9201c4", "created_at": "2019-08-24T14:15:22Z", "approved_by": "02030314-b162-4b4d-8af1-88eabdcc615d", "approved_at": "2019-08-24T14:15:22Z", "note": "string", "label": "string", "activated_at": "2019-08-24T14:15:22Z", "deactivated_at": "2019-08-24T14:15:22Z" }, "behavior_revision": 0, "model_source": "fixed", "draft": { "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c", "runtime_profile_id": "string", "model_source": "fixed", "failure": "string" }, "effective_behavior": { "applied": { "runtime_profile_id": "string", "model": "string", "model_source": "fixed", "title_model": "string" }, "draft": { "runtime_profile_id": "string", "model": "string", "model_source": "fixed", "title_model": "string" } }, "profile_tracking": "follow", "profile_rollout": { "status": "pending", "reason": "string", "target_profile_id": "string" }, "release": { "status": "applied", "reason": "string", "release_id": "string", "version_id": "9e94c502-ca41-4342-a7f7-af96b444512c" }}