Agents - Crewship

An agent is an AI coding agent with a configurable role, CLI adapter, skills, and credentials. Agents belonging to the same crew share one Linux container. These endpoints cover the full agent lifecycle: creating and configuring permanent agents, hiring short-lived ephemeral “contractors”, managing their skills and credentials, driving chats and runs, inspecting workspace files, and tuning the persona and self-learning layers that shape each agent’s behavior.

All /api/v1/agents/* endpoints require authentication and workspace context. Workspace context may be supplied as workspace_id, a {workspaceId} path value, or the X-Workspace-ID header; the chat-message proxy (/api/v1/chats/{chatId}/messages) is the exception — it resolves the workspace from the chat row and takes no workspace context parameter.

Endpoints

Method	Endpoint	Purpose
GET	/api/v1/agents/crews-status	Lightweight agent counts by status for toolbar/dashboard widgets
GET	/api/v1/agent-load	Agent load metrics across the workspace
GET	/api/v1/models	Enumerate the models a provider can serve (live or curated)
GET	/api/v1/agents	List agents (optionally filtered by crew)
POST	/api/v1/agents	Create a new agent
GET	/api/v1/agents/	Get a single agent
PATCH	/api/v1/agents/	Partially update an agent
DELETE	/api/v1/agents/	Soft-delete an agent
POST	/api/v1/agents//webhook-secret/rotate	Rotate and return an agent webhook secret once
POST	/api/v1/agents/hire	Spawn a new ephemeral agent under a crew
POST	/api/v1/agents//rehire	Resurrect or extend an ephemeral agent
POST	/api/v1/agents//approve-hire	Approve a guided-autonomy pending hire
GET	/api/v1/agents//persona	Get the resolved persona
PUT	/api/v1/agents//persona	Operator-only direct persona write
DELETE	/api/v1/agents//persona	Remove the agent persona layer
GET	/api/v1/agents//persona/history	List persona version history
POST	/api/v1/agents//persona/suggest	Agent-initiated persona proposal
GET	/api/v1/agents//learning	Get the self-learning flag and audit triple
PATCH	/api/v1/agents//learning	Flip the self-learning flag
GET	/api/v1/agents//inbox	Consolidated “what’s waiting on this agent” payload
GET	/api/v1/agents//peers	List the agent’s peer-card index
GET	/api/v1/agents//peers/	Get one peer card’s full content
DELETE	/api/v1/agents//peers/	Delete one peer card
GET	/api/v1/agents//skills	List skill assignments
POST	/api/v1/agents//skills	Assign a skill
DELETE	/api/v1/agents//skills/	Remove a skill
GET	/api/v1/agents//credentials	List credential assignments
POST	/api/v1/agents//credentials	Assign a credential
DELETE	/api/v1/agents//credentials/	Remove a credential
GET	/api/v1/agents//chats	List chat sessions
POST	/api/v1/agents//chats	Create a new chat session
PUT	/api/v1/agents//chats//read	Mark a chat read
PATCH	/api/v1/agents//chats/	Rename a chat session
DELETE	/api/v1/agents//chats/	Delete a chat session
POST	/api/v1/agents//chats//attachments	Upload a chat attachment
GET	/api/v1/agents//chats//attachments	List a chat’s attachments
DELETE	/api/v1/agents//chats//attachments/	Delete one chat attachment
GET	/api/v1/agents//runs	List execution history
GET	/api/v1/agents//credential-bindings	List MCP credential bindings
GET, POST, PATCH, DELETE	/api/v1/agents//integrations	Manage agent MCP integrations
GET	/api/v1/agents//integrations/resolved	Resolve effective MCP integrations
GET	/api/v1/agents//notification-channels	List notification channels available to an agent
GET	/api/v1/agents//debug	Debug information for a running agent
GET	/api/v1/agents//files	List files in agent workspace
GET	/api/v1/agents//files/download	Download a file
PUT	/api/v1/agents//files/save	Save/upload a file
GET	/api/v1/agents//container-files	List files inside the running container
GET	/api/v1/agents//git-log	Recent git commits from the container workspace
GET	/api/v1/agents//logs	Get agent logs
POST	/api/v1/agents//stop	Stop a running agent
GET	/api/v1/chats//messages	Get messages for a chat session

Status & Metrics

Lightweight, read-only aggregates that power toolbar and dashboard widgets.

Crews Status

GET /api/v1/agents/crews-status?workspace_id={workspaceId}

# Response is a per-workspace aggregate counting agents by status
# (IDLE/RUNNING/ERROR — no STOPPED bucket). Drives the 'Crews idle/online'
# badge in the top toolbar.

Returns lightweight agent counts by status for toolbar/dashboard widgets. Auth: Authenticated session or CLI token with resolved workspace context; the router applies the workspace-scoped authenticated middleware. Request: No body. Supply workspace context with X-Workspace-ID (or the equivalent workspace context accepted by the API). Response: 200 OK

{
  "total": 12,
  "running": 3,
  "error": 1,
  "idle": 8,
  "queued": 0
}

Status: 400 for invalid workspace context, 401 when unauthenticated, 403 when the caller cannot access the workspace, and 500 when the status query fails.

Contract: `GET /api/v1/agents/crews-status`

Auth: Authenticated request with workspace context. Request: no body; the workspace is supplied through the workspace context/header. Response: 200 OK with the status-count object above. Status: 400, 401, 403, or 500 as described above. The agent status buckets (total, running, error, idle) are always present — zero counts are not omitted. Any status that is not RUNNING or ERROR (including IDLE and PENDING_REVIEW) folds into the idle bucket; there is no stopped bucket. The queued field counts admission-queue assignments (not agents) currently in the QUEUED state — independent of the agent buckets, and 0 on servers that pre-date the queue migration (internal/api/agents.go:111-151).

Agent Load

GET /api/v1/agent-load?workspace_id={workspaceId}

Returns agent load metrics across the workspace. Auth: Authenticated session or CLI token with resolved workspace context. Request: No body. Supply workspace context with X-Workspace-ID (or the equivalent workspace context accepted by the API). Response: 200 OK — an array (never null) of entries with agent_id, agent_name, agent_slug, agent_status, active_tasks, pending_tasks, completed_today, tokens_used_today, and token_budget. Active tasks include IN_PROGRESS; pending tasks include PENDING and BLOCKED; token usage and completed counts are calculated over the current UTC day/24-hour reporting window used by the handler. Status: 400 for invalid workspace context, 401 when unauthenticated, and 403 when the caller cannot access the workspace.

Model Discovery

Enumerate the models an LLM provider can serve, so an operator (or an agent building a POST/PATCH /api/v1/agents request) doesn’t have to guess a model identifier. Discovery is live when possible, curated when not (internal/api/models.go:84): if the workspace has an active API_KEY credential for the provider, Crewship queries the provider’s own models API; otherwise it returns a hand-maintained curated fallback. The source field reports which path was taken. See the Model discovery guide for the CLI equivalent (crewship model list) and the llm_model validation this same resolver drives on agent update.

List Models

GET /api/v1/models?provider={PROVIDER}&workspace_id={workspaceId}

Auth: Any authenticated workspace member (authed + workspace context; the active provider credential is read from the resolved workspace) (internal/api/router_crews.go:230). Query Parameters:

Parameter	Type	Required	Description
`provider`	string	Yes	Provider to enumerate. Case-insensitive; upper-cased server-side. One of `ANTHROPIC`, `OPENAI`, `GOOGLE`, `OLLAMA` (`internal/api/models.go:45-50`).
`workspace_id`	string	Yes	Workspace whose provider credential is used for live listing.

Response: 200 OK

{
  "provider": "ANTHROPIC",
  "source": "live",
  "models": [
    { "id": "claude-opus-4-8", "display_name": "Claude Opus 4.8", "provider": "anthropic" },
    { "id": "claude-sonnet-4-6", "display_name": "Claude Sonnet 4.6", "provider": "anthropic" }
  ]
}

Field	Type	Description
`provider`	string	Echo of the resolved (upper-cased) provider (`internal/api/models.go:36`).
`source`	string	`"live"` when the provider’s own API answered, `"curated"` when the static fallback was used (`internal/api/models.go:37`).
`models`	array	Always a JSON array (never `null`), even when empty (`internal/api/models.go:120`).
`models[].id`	string	Model identifier to pass as `llm_model` (`internal/llm/provider.go:100`).
`models[].display_name`	string	Human-readable name; omitted when the provider gives none (`internal/llm/provider.go:101`).
`models[].provider`	string	Lower-case provider tag on the model (`internal/llm/provider.go:102`).

OLLAMA has no curated fallback. Its model set is whatever the local daemon has pulled, so there is no sensible static list. When the daemon can’t be reached the endpoint returns 502 rather than an empty list, so “daemon unreachable” is never mistaken for “no models installed” (internal/api/models.go:103-107). GOOGLE has no live lister yet and always resolves to its curated set (internal/api/models.go:78).

Status	Condition
`200`	Model set returned (`source` reports live vs curated).
`400`	`provider` missing, or not one of `ANTHROPIC`/`OPENAI`/`GOOGLE`/`OLLAMA` (`internal/api/models.go:88-96`).
`502`	`OLLAMA` daemon unreachable and no curated fallback exists (`internal/api/models.go:104`).

Lifecycle & CRUD

Create, read, update, and soft-delete permanent agents.

List Agents

GET /api/v1/agents?workspace_id={workspaceId}

Query Parameters:

Parameter	Type	Description
`workspace_id`	string	Required. Workspace ID
`crew_id`	string	Optional. Filter by crew

Response: 200 OK

[
  {
    "id": "agent_abc",
    "crew_id": "crew_123",
    "workspace_id": "ws_456",
    "name": "Backend Dev",
    "slug": "backend-dev",
    "description": "Go backend developer",
    "role_title": "Senior Developer",
    "agent_role": "AGENT",
    "lead_mode": null,
    "status": "IDLE",
    "cli_adapter": "CLAUDE_CODE",
    "llm_provider": "ANTHROPIC",
    "llm_model": "claude-sonnet-4-20250514",
    "system_prompt": "You are a Go backend developer...",
    "avatar_seed": "backend-dev",
    "avatar_style": "bottts",
    "timeout_seconds": 1800,
    "tool_profile": "CODING",
    "memory_enabled": true,
    "cli_tools": null,
    "schedule_cron": null,
    "schedule_prompt": null,
    "schedule_enabled": false,
    "schedule_last_run": null,
    "schedule_next_run": null,
    "mcp_config_json": null,
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "crew": {
      "name": "Engineering",
      "slug": "engineering",
      "color": "blue",
      "avatar_style": "bottts"
    },
    "_count": {
      "skills": 2,
      "credentials": 1,
      "chats": 5
    },
    "created_by_user_id": "user_789",
    "ephemeral": false,
    "expires_at": null,
    "expired_at": null,
    "parent_lead_id": null,
    "hire_reason": null
  }
]

mcp_config_json and created_by_user_id carry omitempty — they are dropped from the JSON entirely when null/empty rather than serialized as null.

Response Fields

Field	Type	Description
`id`	string	Agent ID
`crew_id`	string	Parent crew ID
`workspace_id`	string	Workspace ID
`name`	string	Display name
`slug`	string	URL-safe identifier
`description`	string?	Agent description
`role_title`	string?	Human-readable role title
`agent_role`	string	`AGENT` or `LEAD`
`lead_mode`	string?	`"active"` or `"passive"` (LEAD agents only)
`status`	string	`IDLE`, `RUNNING`, or `ERROR`
`cli_adapter`	string	CLI tool used to run the agent
`llm_provider`	string?	LLM provider name
`llm_model`	string?	LLM model identifier
`system_prompt`	string?	System prompt for the agent
`avatar_seed`	string?	Seed for avatar generation
`avatar_style`	string?	Avatar style (e.g., `"bottts"`, `"pixel-art"`)
`avatar_url`	string?	Serve URL for the agent’s stored avatar, or `null` when it has none and is still generated from the seed. See Agent avatars.
`timeout_seconds`	integer	Maximum execution time
`tool_profile`	string	Tool access profile
`memory_enabled`	boolean	Whether agent memory is enabled
`suggested_prompts`	string?	Chat suggestions offered under an empty conversation, one per line (max 8, max 120 chars each). `null` when unconfigured — the chat then shows the built-in defaults
`ask_forms`	string?	The agent’s questionnaires: a JSON array of form definitions, canonical as stored (max 4 forms, max 6 fields each). `null` when unconfigured — see Ask forms under Update Agent
`cli_tools`	string?	Comma-separated list of allowed CLI tools
`schedule_cron`	string?	Cron expression for scheduled runs
`schedule_prompt`	string?	Prompt used for scheduled runs
`schedule_enabled`	boolean	Whether schedule is active
`schedule_last_run`	string?	ISO 8601 timestamp of last scheduled run
`schedule_next_run`	string?	ISO 8601 timestamp of next scheduled run
`mcp_config_json`	string?	Agent-level MCP server config (omitted when empty)
`crew`	object?	Embedded crew info (name, slug, color, avatar_style)
`_count`	object	Counts: skills, credentials, chats
`created_by_user_id`	string	Creator user ID; omitted for legacy rows with no creator
`ephemeral`	boolean	`true` for hired contractor agents, `false` for permanent agents
`expires_at`	string?	RFC3339 TTL deadline (ephemeral agents only)
`expired_at`	string?	RFC3339 ghost timestamp once the TTL elapses
`parent_lead_id`	string?	LEAD agent that parented this ephemeral
`hire_reason`	string?	Timestamped hire/rehire reason log

Create Agent

POST /api/v1/agents?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Default	Description
`name`	string	Yes	—	Display name (2-100 characters)
`slug`	string	Yes	—	URL-safe identifier (2-50 chars, lowercase letters/digits/hyphens)
`crew_id`	string	Conditional	`null`	Parent crew ID. Required when `agent_role` is `LEAD`; optional for `AGENT` (`internal/api/agents_create.go:73`). Must belong to the caller’s own workspace — a crew from another workspace is rejected with `400`.
`description`	string	No	`null`	Agent description
`role_title`	string	No	`null`	Human-readable role title
`agent_role`	string	No	`"AGENT"`	`AGENT` or `LEAD`
`lead_mode`	string	No	`"active"`	`"active"` or `"passive"` (LEAD agents only)
`cli_adapter`	string	No	`"CLAUDE_CODE"`	CLI adapter
`llm_provider`	string	No	`null`	LLM provider
`llm_model`	string	No	`null`	LLM model
`system_prompt`	string	No	`null`	System prompt
`avatar_seed`	string	No	`null`	Avatar seed
`avatar_style`	string	No	`null`	Avatar style
`timeout_seconds`	integer	No	`1800`	Max execution time in seconds
`tool_profile`	string	No	`"CODING"`	Tool profile
`memory_enabled`	boolean	No	`false`	Enable agent memory

{
  "name": "Backend Dev",
  "slug": "backend-dev",
  "crew_id": "crew_123",
  "agent_role": "AGENT",
  "cli_adapter": "CLAUDE_CODE",
  "system_prompt": "You are a Go backend developer...",
  "memory_enabled": true,
  "tool_profile": "CODING"
}

Agent Roles:

Role	Description	Crew Required
`AGENT`	Worker that executes tasks	Yes
`LEAD`	Crew leader that plans and delegates	Yes (max 1 per crew)

CLI Adapters: CLAUDE_CODE, CODEX_CLI, GEMINI_CLI, OPENCODE, CURSOR_CLI, FACTORY_DROID Tool Profiles: MINIMAL, CODING, FULL Response: 201 Created — returns the created agent object.

Status	Condition
`400`	Invalid name, slug, role, missing required crew_id, or crew_id belongs to another workspace
`402`	License agent limit exceeded
`403`	Insufficient role
`409`	Slug already taken, or crew already has a LEAD agent

Get Agent

GET /api/v1/agents/{agentId}?workspace_id={workspaceId}

Response: 200 OK — full agent object.

Status	Condition
`404`	Agent not found

Update Agent

PATCH /api/v1/agents/{agentId}?workspace_id={workspaceId}

Partial update — only provided fields are changed. Auth: Per-agent edit gate (canEditAgent in internal/api/agents_update.go:27, defined at internal/api/rbac.go:151). OWNER / ADMIN may edit any agent; MANAGER may edit only agents they created or agents in crews where they hold per-crew ADMIN/OWNER; MEMBER / VIEWER are refused. Request Body: Same fields as Create, all optional. status is not mutable through this endpoint. Additionally supports:

Field	Type	Description
`cli_tools`	string	Comma-separated CLI tools
`schedule_cron`	string	Cron expression
`schedule_prompt`	string	Schedule prompt
`schedule_enabled`	boolean	Enable/disable schedule
`mcp_config_json`	string	Agent MCP config JSON (must contain an `mcpServers` object)
`suggested_prompts`	string	Chat suggestions, one per line (see below)
`ask_forms`	string	Ask forms as a JSON array, given as a string (see below)

Suggested prompts. suggested_prompts holds the questions this agent offers as buttons under an empty conversation, one per line — at most 8 lines, at most 120 characters each. The server normalises on write: CRLF becomes LF, each line is trimmed, blank lines are dropped, and a value that ends up empty is stored as null. An agent with null here is not misconfigured; it simply shows the built-in defaults, which is what every agent did before the field existed. Rejections name the offending line — "at most 8 prompts are allowed (got 9)", "prompt 3 exceeds 120 characters (it has 154)" — so a caller can fix the entry rather than the whole list. Set it from the console under an agent’s Config -> Chat suggestions, or with crewship agent update <agent> --suggested-prompts @questions.txt. Ask forms. ask_forms holds the questionnaires this agent offers: a chip that opens a short form, whose answers are rendered into an ordinary user message and sent. The value is a JSON array given as a string — the column is TEXT, the console edits it in a textarea and the CLI reads it from a file, and accepting a nested array as well would put two encodings of one value on one endpoint.

[{
  "id": "receipt",
  "label": "Add a receipt",
  "template": "Please file this receipt.\n\nSupplier: {{supplier}}\nAmount: {{amount}} {{amount_currency}}\nPeriod: {{month}}\nCategory: {{category}}\nDocument: {{document}}",
  "attachment": "required",
  "fields": [
    {"name": "supplier", "label": "Supplier", "type": "text", "required": true, "placeholder": "Vodafone"},
    {"name": "amount", "label": "Amount", "type": "money", "required": true, "currency": ["CZK", "EUR", "USD"]},
    {"name": "month", "label": "Period", "type": "month", "default": "2026-08"},
    {"name": "category", "label": "Category", "type": "select", "options": ["Telco", "Hosting"]},
    {"name": "document", "label": "Document", "type": "file"}
  ]
}]

id is a slug and must be unique; label is the chip’s text (max 48 characters); attachment is none | optional | required and defaults to none; template is at most 2000 characters. Field types are text, textarea, number, money, date, month, select, multiselect, checkbox, file and photo — an unrecognised type is accepted and falls back to a text input, which is what lets a new type ship without a coordinated frontend release. select and multiselect must carry options. A JSON Schema for authoring lives at schemas/ask-form.v1.json. Money fields answer to two placeholders. A money field named amount renders as {{amount}} for the number and {{amount_currency}} for the chosen currency. The second name is derived so that two money fields on one form cannot fight over a single {{currency}}. Template rendering. {{field}} substitution only — no conditionals, no loops, no expressions. Three rules decide what gets sent:

Every placeholder must name a field on its own form, and this is checked when the form is saved, not when it is rendered. The author finds out while authoring; the person talking to the agent never meets a broken template.
An empty optional value drops the whole line it sits on, static label and all, unless another placeholder on that line produced something. So a receipt with no category sends no Category: line rather than a dangling one. This is the only rule that is not obvious from reading a template.
Values are inserted verbatim — the result is a user message, so nothing is markdown-escaped — but control characters are stripped, each value is capped at 2000 characters and the finished message at 32000. file and photo values render as the agent-visible path attachments/<chatId>/<name>, one per line when there are several.

Rejections name the form and the placeholder, because the caller is mid-edit: form "receipt": template names {{suplier}}, which is not a field on that form, form "receipt": has no fields, two forms share the id "receipt", at most 4 forms are allowed per agent (got 5). Nothing is written when a definition is refused. A value that normalises to nothing — "", whitespace, [], or null — clears the column. The stored value is canonical: parsed, validated and re-encoded with defaults spelled out and a stable key order, so what a caller reads back is stable rather than showing a diff nobody made. Set it from the console under an agent’s Config -> Ask forms, or with crewship agent update <agent> --ask-forms @forms.json, and render one without a browser with crewship agent ask-preview <agent> <form-id> --var k=v. Response: 200 OK — updated agent object.

Delete Agent

DELETE /api/v1/agents/{agentId}?workspace_id={workspaceId}

Soft-deletes the agent (sets deleted_at). Request: No body; agentId is a required path parameter and workspace context scopes the lookup.

This is a destructive operation. Same per-agent edit gate as Update (canEditAgent in internal/api/agents_query.go:266, defined at internal/api/rbac.go:151). OWNER / ADMIN delete any agent; MANAGER deletes only agents they created or agents in crews where they hold per-crew ADMIN/OWNER.

Response: 200 OK

{ "success": true }

Rotate Webhook Secret

POST /api/v1/agents/{agentId}/webhook-secret/rotate

Uses the same per-agent edit gate as Update. The new signing secret is returned exactly once; Crewship stores only its protected form and does not provide a read endpoint. Response: 200 OK

{
  "webhook_secret": "whsec_…",
  "rotated_at": "2026-06-04T12:00:00Z"
}

Status	Condition
`403`	Caller lacks edit rights for this agent.
`404`	Agent not found in this workspace.
`500`	Secret storage is not configured or failed.

Hire / Rehire / Approve

Ephemeral agents (“contractors”) are short-lived agents spawned against a crew with a TTL. When the TTL elapses the agent becomes a ghost (the row is preserved for audit but no longer counts against the crew’s quota). The hire flow is gated by the crew’s autonomy policy (strict / guided / trusted / full) and bounded by the crew’s max_ephemeral_agents quota (ghosts excluded).

All three endpoints require OWNER, ADMIN, or MANAGER role (canRole(role, "create")).

Hire Agent

POST /api/v1/agents/hire?workspace_id={workspaceId}

Spawns a new ephemeral agent under a crew. The crew’s autonomy policy decides the outcome:

Autonomy	Outcome
`strict`	`403` — the hire is rejected with a structured reason.
`guided`	`202` — the agent row is created in `PENDING_REVIEW`, a blocking inbox waitpoint is dropped, and the agent will not start until approved.
`trusted`	`201` — the agent goes live immediately; a non-blocking inbox visibility item is recorded.
`full`	`201` — the agent goes live immediately; journal-only, no inbox row.

Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Description
`crew_id`	string	Conditional	Target crew by id. Provide exactly one of `crew_id` / `crew_slug`.
`crew_slug`	string	Conditional	Target crew by slug. Mutually exclusive with `crew_id`.
`template_slug`	string	Yes	Crew template the ephemeral is built from (built-in or workspace-owned).
`ttl_minutes`	integer	No	Lifetime in minutes. Clamped to `1–1440`; a value of `0`/negative falls back to the server floor of 30.
`reason`	string	Yes	Audit/history trail for the hire.
`model`	string	No	LLM model override. Empty falls back to the template default at provisioning time.
`parent_lead_id`	string	No	A `LEAD` agent in the same crew + workspace that parents this ephemeral.

{
  "crew_slug": "engineering",
  "template_slug": "backend-dev",
  "ttl_minutes": 60,
  "reason": "Spike: investigate the flaky deploy script",
  "model": "claude-sonnet-4-20250514"
}

Response: 201 Created (live) or 202 Accepted (pending review).

{
  "id": "agent_abc",
  "crew_id": "crew_123",
  "workspace_id": "ws_456",
  "slug": "backend-dev-eph-1a2b3c",
  "name": "Backend Dev",
  "status": "IDLE",
  "ephemeral": true,
  "expires_at": "2026-06-04T13:00:00Z",
  "expired_at": null,
  "parent_lead_id": null,
  "hire_reason": "[2026-06-04T12:00:00Z] hire: Spike: investigate the flaky deploy script",
  "pending_review": false,
  "inbox_item_id": "ib-cuid",
  "decision": "auto_log_journal"
}

Field	Type	Description
`id`	string	New agent id.
`crew_id`	string?	Resolved crew id.
`workspace_id`	string	Workspace id.
`slug`	string	Generated ephemeral slug (`<template>-eph-<hex>`).
`name`	string	Template name.
`status`	string	`IDLE` on a live hire, `PENDING_REVIEW` when the policy is `guided`.
`ephemeral`	boolean	Always `true`.
`expires_at`	string?	RFC3339 TTL deadline.
`expired_at`	string?	RFC3339 ghost timestamp (always `null` on a fresh hire).
`parent_lead_id`	string?	Echo of the parenting LEAD, when supplied.
`hire_reason`	string?	Timestamped reason log (rehires append to this).
`pending_review`	boolean	`true` only on the `guided` → `202` path.
`inbox_item_id`	string	Inbox row id (blocking waitpoint on `guided`, visibility item on `trusted`). Omitted when empty (`full`).
`decision`	string	The policy decision that produced this outcome.

Status	Condition
`201`	Live ephemeral (`trusted` / `full`).
`202`	`PENDING_REVIEW` + blocking inbox item (`guided`).
`400`	Missing/invalid `template_slug`, `reason`, or `crew_id`/`crew_slug` (neither, or both).
`403`	`strict` autonomy rejected the hire, or caller lacks MANAGER+.
`404`	Crew or template not found in this workspace.
`429`	Crew quota (`max_ephemeral_agents`) reached — rehire a ghost or raise the quota.

Credential assignment

On a successful hire (201/202), Crewship auto-assigns the available workspace Anthropic credentials (API_KEY / AI_CLI_TOKEN, first-created wins) to the new agent so it can authenticate on first run. This is best-effort and runs after the agent row is committed: assignment failures are journaled as credential.auto_assign_failed and never fail the hire, and a workspace with no Anthropic credential journals credential.auto_assign_empty. Assign manually later via POST /api/v1/agents/{agentId}/credentials if needed.

Rehire Agent

POST /api/v1/agents/{agentId}/rehire?workspace_id={workspaceId}

Resurrects an expired ephemeral (“ghost”): clears expired_at, pushes expires_at forward by the new TTL, and appends a new reason line to the hire_reason history. The container is not rebuilt here — the chatbridge auto-provisions a fresh one on the next message. Rehiring a still-live ephemeral (extending its TTL before it ghosts) is free and does not consume an extra quota slot. Auth: OWNER, ADMIN, or MANAGER role Request Body:

Field	Type	Required	Description
`ttl_minutes`	integer	No	New lifetime in minutes. Same `1–1440` clamp / 30-minute floor as Hire.
`reason`	string	Yes	Appended to the `hire_reason` history trail.

{
  "ttl_minutes": 90,
  "reason": "Deploy script needs another pass"
}

Response: 200 OK — same shape as the Hire response, echoing the agent’s persisted status (rehire does not change it) and the updated expires_at / hire_reason.

Status	Condition
`200`	Rehire succeeded; agent is live again.
`400`	Missing `reason`, or invalid JSON.
`403`	Caller lacks MANAGER+, or `strict` autonomy rejected the rehire.
`404`	Agent not found in this workspace, or the agent is not ephemeral.
`429`	Crew quota reached (only when rehiring a ghost).

Approve Hire

POST /api/v1/agents/{agentId}/approve-hire?workspace_id={workspaceId}

The guided-autonomy approval step. Flips a PENDING_REVIEW ephemeral to IDLE (an atomic conditional UPDATE, so two concurrent approvals can’t both win), resolves the blocking inbox waitpoint addressed to the agent, and writes an agent.hire_approved audit entry. The chatbridge refuses to start a PENDING_REVIEW agent, so this is what actually releases the gate. Auth: OWNER, ADMIN, or MANAGER role Request Body: empty. Response: 200 OK

{
  "id": "agent_abc",
  "status": "IDLE",
  "crew_id": "crew_123"
}

Status	Condition
`200`	Agent flipped to `IDLE`; chatbridge will now serve messages.
`403`	Caller lacks MANAGER+.
`404`	Agent not found in this workspace.
`409`	Agent is not in `PENDING_REVIEW` (already approved, hired under non-guided autonomy, or a permanent agent).

Agent Persona

The persona layer is per-agent PERSONA.md markdown that the orchestrator injects into every system prompt. Resolution is layered: the agent layer (if a file exists on disk) wins; otherwise the crew default layer; otherwise the synthesized default built from the agent’s role + role title. Direct writes are operator-only; agents edit only via the suggest endpoint, which the policy resolver gates per crew-autonomy level (see Autonomy & self-learning).

Get Persona

GET /api/v1/agents/{agentId}/persona

Returns the resolved persona — agent layer if a file is present, crew default otherwise, synthesised default if neither layer is configured. Auth: Authenticated workspace member. Request: No body; agentId is required and workspace context scopes the agent lookup. Response: 200 OK

{
  "agent_id": "agent-uuid",
  "layer": "agent",
  "from_default": false,
  "content": "# PERSONA.md...\n",
  "bytes": 1842,
  "cap_bytes": 1500
}

Field	Type	Description
`layer`	`string`	`agent` or `crew` — which layer the response came from. The synthesised default is reported as `crew` with `from_default = true`.
`from_default`	`bool`	`true` when no file exists on either layer and the synthesised “You are the …” stub was returned
`cap_bytes`	`integer`	Max accepted size on `PUT` / `POST suggest` (`memory.PersonaCapBytes` = 1500 bytes)

Status: 400 for invalid request/workspace context, 401 when unauthenticated, 403 when access is denied, and 500 when persona storage cannot be read.

Set Persona

PUT /api/v1/agents/{agentId}/persona
Content-Type: application/json

Operator-only direct write of the agent layer. Records a row in memory_versions so Get Persona History can replay the chain. Request:

{ "content": "# Engineer\n\nFocus on backend services...\n" }

Response: 200 OK

{ "layer": "agent", "bytes": 1842, "updated": "2026-05-27T18:42:11Z" }

Status	Condition
`413`	`content` exceeds `cap_bytes`
`400`	Invalid JSON or missing storage configuration
`500`	Storage write/fsync failure

Agents cannot use this endpoint to mutate their own persona — ActionPersonaDirectWrite is DecisionRejected across every autonomy level in Phase 1. Agent edits flow exclusively through Suggest Persona.

Reset Persona

DELETE /api/v1/agents/{agentId}/persona

Removes the agent layer file. The next GET falls through to the crew layer (or the synthesised default).

Auth: Authenticated caller with the operator edit permission used by the persona mutation routes. Request: No body; agentId is required. Response: 204 No Content Status: 401 unauthenticated, 403 when the caller lacks the mutation permission, and 500 when the persona cannot be reset.

Get Persona History

GET /api/v1/agents/{agentId}/persona/history?limit=20

Lists rows from memory_versions filtered to this agent’s PERSONA.md path. Pairs with GET /api/v1/admin/memory/versions/{id}/content for content drill-down — the history endpoint deliberately omits content to keep responses small. Query Parameters:

Param	Default	Max	Description
`limit`	`20`	`100`	Page size, clamped server-side.

Response: 200 OK

{
  "entries": [
    {
      "id": "mv-cuid",
      "sha256": "deadbeef…",
      "bytes": 1842,
      "written_at": "2026-05-27T18:42:11Z",
      "written_by": "user-uuid",
      "parent_sha": "cafef00d…"
    }
  ]
}

parent_sha is omitted on the first version (when the chain starts).

Suggest Persona

POST /api/v1/agents/{agentId}/persona/suggest
Content-Type: application/json

Agent-initiated persona proposal. The crew’s autonomy policy decides the outcome:

Crew autonomy	Outcome
`strict` / `guided` / `trusted`	Inbox approval item created. Agent learns `pending` so it can reference the proposal in subsequent runs.
`full`	Auto-apply + journal entry — unless the agent’s `self_learning_enabled = 0`, which demotes auto-apply back to inbox approval.

ActionPersonaDirectWrite is rejected across every autonomy level — this endpoint is the only path an agent can use to write a persona. Request:

{
  "content": "# Engineer\n\nFocus on backend services...\n",
  "rationale": "Operator briefly emphasised the on-call rotation; reflecting that in the persona."
}

Response: 200 OK (proposal queued or applied) / 403 (policy rejected)

{
  "agent_id": "agent-uuid",
  "decision": "inbox_approve",
  "bytes": 1842,
  "rationale": "...",
  "timestamp": "2026-05-27T18:42:11Z",
  "applied": false,
  "pending": true
}

Field	Type	Description
`decision`	`string`	Policy decision that drove the outcome (e.g. `inbox_approve`, `auto_journal`, `rejected`).
`applied`	`bool`	`true` only when the suggestion was auto-applied to disk (`full` autonomy + `self_learning_enabled = 1`).
`pending`	`bool`	`true` when the proposal was queued for operator approval (present on the inbox path).
`self_learning_gate`	`string?`	`"off"` only when a per-agent `self_learning_enabled = 0` demoted an auto-apply decision back to inbox approval.

There is no inbox_id in this response — the proposal is recorded as an audit_logs row (persona.suggest_pending), not returned to the caller.

Status	Condition
`400`	Missing / empty `content` field
`403`	Policy rejected the suggestion (autonomy floor)
`413`	`content` exceeds `cap_bytes`
`503`	Server built without storage configuration (`outputBasePath` empty)

Agent Self-Learning Posture

Per-agent flag controlling whether ALLOW decisions from the Keeper evaluators auto-apply (enabled = true) or queue for operator approval in the inbox (enabled = false). Orthogonal to the crew’s autonomy_level: the per-action policy gate (policy.DecideAction) is the upstream authority — this flag only decides what happens to already-ALLOWed decisions. See Autonomy & self-learning.

Get Self-Learning

GET /api/v1/agents/{agentId}/learning

Returns the current flag plus the audit triple (who flipped it, when, why). Any authenticated workspace member can read — the value is non-secret diagnostic state. Auth: Authenticated workspace member. Request: no body; agentId is a required path parameter. Status: 400 for invalid request context, 401 when unauthenticated, 403 when access is denied, and 500 for a read failure. Response: 200 OK

{
  "agent_id": "agent-uuid",
  "enabled": true,
  "set_by_user_id": "user-uuid",
  "set_at": "2026-05-26T09:14:22Z",
  "reason": "Trusted crew, agent has cleared 50+ approvals without an override"
}

Field	Type	Notes
`enabled`	`bool`	Persisted as `0` / `1` on `agents.self_learning_enabled`.
`set_by_user_id`	`string?`	Omitted on agents that have never had the flag flipped.
`set_at`	`string?`	RFC3339; omitted when never set.
`reason`	`string?`	Operator-supplied rationale from the most recent `PATCH`; omitted when never set.

Set Self-Learning

PATCH /api/v1/agents/{agentId}/learning
Content-Type: application/json

Flip the flag. Requires OWNER / ADMIN (canRole(role, "manage")) — self-learning weakens the inbox-approval invariant, so the operator who turns it on must be senior enough to own the consequences. Request:

{
  "enabled": true,
  "reason": "Trusted crew, agent has cleared 50+ approvals without an override"
}

Field	Type	Required	Notes
`enabled`	`bool`	yes	Decoded as `bool` server-side — a missing or `null` field returns `400`, not* a silent flip to `false`. Be explicit about direction.
`reason`	`string`	yes	Non-empty after trim. Persisted on the row so a later audit can answer “who turned this on, when, and why”.

Response: 200 OK — same shape as GET, reflecting the new state and the freshly-recorded audit triple.

Status	Condition
`400`	`enabled` field missing / null, or `reason` empty
`403`	Caller is not OWNER / ADMIN
`404`	Agent not found in the current workspace

Agent Inbox Summary

GET /api/v1/agents/{agentId}/inbox

Consolidated “what’s waiting on this agent” payload used by the Crews preview panel — one round-trip instead of four parallel fetches across approvals, assignments, escalations, and peer messages. UI is the primary consumer; operators can poll the endpoint for an at-a-glance load check. Auth: Authenticated workspace member. Request: no body; agentId is a required path parameter and workspace context scopes the lookup. Response: 200 OK

{
  "approvals_pending": 2,
  "assignments_open": 5,
  "escalations_open": 0,
  "peer_messages": [
    {
      "id": "pm-uuid",
      "from_agent_name": "Martin",
      "from_agent_slug": "martin",
      "question": "What's the latest on the deploy script?",
      "response": null,
      "escalated": false,
      "status": "open",
      "created_at": "2026-05-27T12:30:00Z",
      "direction": "incoming"
    }
  ],
  "cost_usd_this_month": 4.21,
  "llm_calls_this_month": 312,
  "tokens_used_this_month": 184221
}

Field	Type	Description
`approvals_pending`	`int`	Inbox waitpoint items awaiting this agent’s decision.
`assignments_open`	`int`	Tasks routed to this agent that have not reached a terminal state.
`escalations_open`	`int`	Peer conversations escalated up the lead chain that still target this agent.
`peer_messages`	`array`	Last N peer messages (both directions). `direction` is `"incoming"` or `"outgoing"`; `response` and `duration_ms` are populated only for resolved exchanges.
`cost_usd_this_month`	`float`	Sum of `cost_ledger.cost_usd` for this agent in the current calendar month. `0` when the `cost_ledger` table is absent (older workspaces).
`llm_calls_this_month`	`int`	Count of `cost_ledger` rows for this agent in the current month.
`tokens_used_this_month`	`int64`	Sum of `input_tokens + output_tokens` from `cost_ledger` in the current month.

Status	Condition
`401`	Workspace context missing
`404`	Agent not found in the current workspace

Agent Peer Cards

Per-(agent, user) markdown notes produced by the PeerCardSync routine — the agent’s own “what I know about this person” file. These endpoints are operator-facing: the cards live on disk under {outputBase}/crews/{crewID}/agents/{slug}/.memory/peers/, and every read/write/delete writes a peer_card_audit row for GDPR SAR coverage. The user-facing surface (view-mine / opt-out / delete-mine) lives under /api/v1/users/me/peer-cards and shares the same disk + DB primitives — these agent-flavor endpoints exist so an operator can clean up cards on behalf of a user (compliance ticket, leaver workflow) or inspect what an agent has been writing about people. The {userId} path parameter is the raw user_id; the server derives the user_slug via memory.UserSlug so the URL stays debuggable.

List Agent Peers

GET /api/v1/agents/{agentId}/peers

Returns the agent’s peer-card index (no card content — fetch via the single-card endpoint below). Workspace-scoped; agents in other workspaces return 404. Auth: Authenticated workspace member. Request: No body; agentId is required and workspace context scopes the lookup. Response: 200 OK

{
  "agent_id": "agent-uuid",
  "peers": [
    {
      "id": "pc-uuid",
      "user_id": "user-uuid",
      "user_slug": "alice",
      "bytes": 412,
      "created_at": "2026-05-10T...",
      "updated_at": "2026-05-26T..."
    }
  ]
}

Status	Condition
`404`	Agent not found in the current workspace
`409`	Agent has no `crew_id` — peer cards require a crew-scoped path

Get Agent Peer Card

GET /api/v1/agents/{agentId}/peers/{userId}

Returns one card’s full content (markdown). Writes a read row to peer_card_audit. Auth: Authenticated workspace member. Request: No body; agentId and userId are required path parameters and workspace context scopes the lookup. Response: 200 OK

{
  "agent_id": "agent-uuid",
  "user_id": "user-uuid",
  "user_slug": "alice",
  "content": "# Alice Chen\n\n- Prefers async over sync...\n",
  "bytes": 412
}

Status	Condition
`404`	Agent not found, or no card exists for this `(agent, user)`
`409`	Agent has no `crew_id`
`503`	`outputBasePath` not configured server-side

Delete Agent Peer Card

DELETE /api/v1/agents/{agentId}/peers/{userId}

Removes the card from disk and the peer_cards row, then writes a delete audit row. Idempotent — deleting a non-existent card returns 204 rather than 404 so an operator script can retry safely.

Auth: Authenticated caller with the self/mutation permission used by this route. Request: No body; agentId and userId are required path parameters. Response: 204 No Content

The GDPR cascade endpoint DELETE /api/v1/admin/users/{userId}/data deletes peer cards across all agents in the workspace for a single user — that’s the right path for a full SAR. This per-agent endpoint is for the narrower “clean up just this agent’s notes about this user” case.

These workspace-admin routes are listed here because the GDPR cross-reference above uses the same admin-user path prefix.

List workspace users

GET /api/v1/admin/users

Auth: Authenticated workspace OWNER or ADMIN (manage role). Request / parameters: No request body. Workspace context is supplied by the authenticated request; there are no path or query parameters. Response: 200 OK with a JSON array of workspace members and their user, workspace, and role fields.

Status	Condition
`401`	Missing authentication or workspace context
`403`	Caller is not an `OWNER` or `ADMIN`
`500`	User query failed

Export one user’s data

GET /api/v1/admin/users/{userId}/data

Auth: Authenticated workspace OWNER or ADMIN (manage role). Request / parameters: No request body. userId is the required path parameter for the data subject; the request is scoped to the authenticated workspace. Response: 200 OK with the GDPR export bundle for that user, including peer cards, memory versions, inbox items, user models, and an audit action_id.

Status	Condition
`400`	Missing workspace context or `userId`
`401`	Missing authentication
`403`	Caller is not an `OWNER` or `ADMIN`
`500`	Export audit, query, or data-read failure

Agent avatars

An agent’s avatar is drawn from its avatar_seed and avatar_style by a generator that runs in the browser. That makes the rendered face a function of the installed generator version: upgrading the avatar library redraws every existing agent, and the roster your team recognises changes overnight. To stop that, an agent can carry a stored render. Once stored, that exact image is served instead of being redrawn, so the agent’s face survives generator upgrades. Both states are normal:

`avatar_url`	Meaning
a URL	The agent has a stored render; fetch it from that URL as given.
`null`	No stored render — generate from `avatar_seed` + `avatar_style`, as before.

Use the string verbatim. It already carries both ?v= and workspace_id, the latter because this route resolves its workspace the same way every other endpoint does, and an <img> tag cannot send the X-Workspace-ID header. Rebuilding the URL by hand and dropping that parameter yields a 400.

The server never draws an avatar (the generator is JavaScript-only). The client renders the image and stores it — at creation, or the first time someone with edit rights views an agent that has none. Agents created through the CLI or crew templates therefore start with avatar_url: null and get filled in later.

Get stored avatar

GET /api/v1/agents/{agentId}/avatar?v={hash}&workspace_id={workspaceId}

Returns image/svg+xml. Readable by any workspace member. workspace_id is required — it scopes the lookup to your workspace, so one workspace can never read another’s avatars. Returns 404 when the agent has no stored render — which is not an error, it just means the client should generate from the seed. The ?v= parameter carries a content hash and is ignored by the server; it exists so the response can be cached immutably and still refresh when the image actually changes. Auth: Authenticated workspace member. Request: No body. agentId is required; v is an optional cache-busting query value and workspace context is required. Response: 200 OK with an SVG body (image/svg+xml). Status: 400 for invalid request/workspace context, 401 when unauthenticated, 403 when the caller cannot access the workspace, and 404 when the agent or stored avatar is not found. Responses are served with Content-Security-Policy: default-src 'none'; sandbox and X-Content-Type-Options: nosniff, so the SVG cannot load subresources or execute script even if opened directly.

Store an avatar

PUT /api/v1/agents/{agentId}/avatar

{ "svg": "<svg xmlns=\"http://www.w3.org/2000/svg\">…</svg>" }

Requires the same per-agent edit rights as PATCH /api/v1/agents/{agentId}. Auth: Authenticated caller with the same per-agent edit rights as PATCH /api/v1/agents/{agentId}. Request: JSON object with required string field svg. Response: 200 OK with the stored avatar representation. The SVG is validated against an allowlist of inert drawing, gradient and metadata elements. Anything capable of loading or executing something — <script>, <foreignObject>, <use>, <image>, any href, any on* handler, any external url(…) — is rejected with 400. Maximum 64 KiB. Storing is write-once. An agent that already has a stored avatar returns 409; clear it first to replace it. Without that rule, an endpoint that fires automatically on page view would double as a way to silently swap a teammate’s agent portrait.

Status	Meaning
`200`	Stored. Returns `{ "avatar_url": "…" }`.
`400`	The SVG failed validation or exceeded the size cap.
`403`	Caller lacks edit rights on this agent.
`404`	No such agent in this workspace.
`409`	The agent already has a stored avatar.

Clear a stored avatar

DELETE /api/v1/agents/{agentId}/avatar

Returns 204. The agent reverts to generate-from-seed — which also means the next generator upgrade will change its face again. Returns 404 for an agent that does not exist in this workspace, and 403 without edit rights. Auth: Authenticated caller with per-agent edit rights. Request: No body; agentId is required. Workspace context is resolved by the authenticated route. Response: 204 No Content on success. Status: 401 unauthenticated, 403 insufficient edit rights, and 404 when the agent is not found.

When a stored render is dropped automatically

A stored render depicts one specific (avatar_seed, avatar_style) pair, so it is discarded whenever something changes what the agent is supposed to look like:

Change	Effect
`PATCH /api/v1/agents/{agentId}` that changes `avatar_seed` or `avatar_style`	that agent’s render is dropped
`PATCH /api/v1/agents/{agentId}` that resubmits them unchanged	render kept
Any unrelated field (rename, model swap)	render kept
`POST /api/v1/crews/{crewId}/apply-avatar-style`	every agent in the crew
`PATCH /api/v1/crews/{crewId}` changing `avatar_style`	only agents that inherit the crew style (`avatar_style` is null); agents with their own style keep theirs

The comparison is on values, not on which keys the request contains. Clients that resubmit the whole agent on every save — the dashboard’s settings page does — would otherwise discard the stored render on every unrelated edit.

Agent Skills

Assign, list, and remove the skills available to an agent.

List Skills

GET /api/v1/agents/{agentId}/skills?workspace_id={workspaceId}

Response: 200 OK — array of skill assignment objects.

Add Skill

POST /api/v1/agents/{agentId}/skills?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role (canRole(role, "create")) Request Body:

Field	Type	Required	Description
`skill_id`	string	Yes	Skill to assign
`config`	string	No	Per-assignment config blob (stored as-is)

{
  "skill_id": "skill_abc"
}

Response: 201 Created — { "id": "<assignment_id>" } on a fresh assign. The assign is idempotent: re-assigning an already-installed skill returns 200 OK with { "id": "<existing_id>", "already_assigned": true } rather than a 409.

Remove Skill

DELETE /api/v1/agents/{agentId}/skills/{skillId}?workspace_id={workspaceId}

Response: 204 No Content

Agent Credentials

Assign, list, and remove the credentials injected into an agent’s container.

List Credentials

GET /api/v1/agents/{agentId}/credentials?workspace_id={workspaceId}

Response: 200 OK — array of the credentials this agent receives. This answers “what does this agent get?”, not “what rows exist in the assignment table”. A credential linked to the agent’s crew is delivered to that agent and therefore appears here, even though no assignment row exists for it.

Field	Type	Description
`grant_source`	string	`explicit` — assigned to this agent, revocable by `id`. `crew` — inherited from a crew the credential is linked to; `id` is empty because there is nothing to revoke, and it is removed by unlinking the credential from the crew.

An explicit assignment always wins over a crew link for the same credential: it appears once, as explicit, carrying the env var name, priority and lease that were chosen for it. Each object also carries the grant’s lease state (see Short-lived leases). Note that lease_source and grant_source answer different questions — the first says why a grant expires, the second says where it came from:

Field	Type	Description
`expires_at`	string	Lease expiry (RFC3339 UTC). Omitted for a standing grant.
`expired`	boolean	Whether that lease has already lapsed. An expired grant is refused at every injection point, so `true` means the credential no longer works.
`lease_source`	string	What minted the lease: `manual` (an explicit `ttl_seconds`), `keeper_allow` (auto-issued on a Keeper ALLOW), `escalation_approve` (auto-issued when a human approved an agent-proposed credential). Omitted for a standing grant and for leases predating migration v165.
`lease_issued_at`	string	When the lease was minted (RFC3339 UTC). Omitted when unset.

Assign Credential

POST /api/v1/agents/{agentId}/credentials?workspace_id={workspaceId}

Auth: OWNER or ADMIN role (canRole(role, "manage") in internal/api/agent_credentials.go:89) Request Body:

Field	Type	Required	Description
`credential_id`	string	Yes	Credential to assign (must exist in this workspace)
`env_var_name`	string	Yes	Environment variable name to inject into the agent container
`priority`	integer	No	Resolution priority when multiple credentials share an `env_var_name`
`ttl_seconds`	integer	No	Issue the grant as a short-lived lease expiring this many seconds from now, instead of a standing grant. Capped at 30 days (`2592000`). Recorded with `lease_source: "manual"`. Omit or `0` for a standing grant.

{
  "credential_id": "cred_abc",
  "env_var_name": "ANTHROPIC_API_KEY",
  "priority": 0,
  "ttl_seconds": 1800
}

Response: 201 Created

{ "id": "<assignment_id>" }

Status	Condition
`400`	Missing `credential_id` or `env_var_name`; negative `ttl_seconds`; `ttl_seconds` over 30 days
`403`	Insufficient role
`404`	Agent or credential not found
`409`	Credential already assigned to this agent

Remove Credential

DELETE /api/v1/agents/{agentId}/credentials/{assignmentId}?workspace_id={workspaceId}

The path segment is the assignment ID (agent_credentials.id), not the credential id. Auth: OWNER or ADMIN role (canRole(role, "manage") in internal/api/agent_credentials.go:146) Response: 200 OK

{ "success": true }

Agent Chats & Runs

List and create interactive chat sessions, and review execution history.

List Chats

GET /api/v1/agents/{agentId}/chats?workspace_id={workspaceId}

Response: 200 OK — array of chat session objects. Auth: Authenticated workspace member. Request: No body; agentId is required and workspace context scopes the list. Status: 400 for invalid request/workspace context, 401 when unauthenticated, and 403 when the caller cannot access the workspace.

Create Chat

POST /api/v1/agents/{agentId}/chats?workspace_id={workspaceId}

Creates a new interactive chat session with the agent. Response: 201 Created The optional request body is { "session_id": "…", "origin": "UI" }. origin may be UI, CLI, WEBHOOK, CRON, or AGENT; unknown values are stored as empty. The response is { "id": "<chatId>" }. Auth: Authenticated caller permitted to create a chat for the agent. Request: Optional JSON object with session_id and origin. origin is one of UI, CLI, WEBHOOK, CRON, or AGENT. Status: 200 or 201 with the created chat id; 400 invalid JSON or origin, 401 unauthenticated, 403 denied, 404 agent not found, and 409 when the requested session conflicts.

Mark Chat Read

PUT /api/v1/agents/{agentId}/chats/{chatId}/read

Advances the caller’s read cursor and clears the paired agent-replied inbox notification. Returns 200 OK with { "success": true }; a chat that is not nested under the supplied agent or workspace returns 404. Auth: Authenticated chat participant/caller with access to the chat. Request: Empty JSON object ({}); agentId and chatId are required path parameters. Response: 200 OK with the chat read-cursor payload (chat_id and last_read_at). Status: 401 unauthenticated, 403 denied, and 404 when the chat is not nested under the supplied agent and workspace.

Rename Chat

PATCH /api/v1/agents/{agentId}/chats/{chatId}

Sets chats.title — the name the session list, the chat sidebar and the agent-replied notification display. A session with no title reads “Untitled session” everywhere, so this is what makes a list of conversations navigable. Auth: The chat creator may rename their own chat; an agent editor may rename any chat for that agent — the same gate as Delete Chat. Request: { "title": "Refactor the queue worker" }. title is required and must be a string; an absent key, null, a non-string and a title that is empty after normalisation are all 400. Normalisation (server-side, before storage): whitespace runs — including newlines and tabs — collapse to a single space, because a title is one line by definition; control characters and invisible formatting characters (zero-width padding, the right-to-left override used for label spoofing) are stripped, with the ZERO WIDTH JOINER exempted so emoji sequences survive; the result is trimmed and capped at 200 characters. The cap counts characters, not bytes, so a Czech or Japanese title gets the same length as an English one. Over the cap is 400, never a silent truncation. The stored title is text, not HTML: markup is preserved verbatim (<Draft> plan stays <Draft> plan), and every consumer is responsible for escaping it when rendering. Response: 200 OK with the updated chat row — the same object shape one element of List Chats has, including unread_count, so a client can replace the row it already holds without refetching the list. Renaming does not touch last_activity_at: fixing a name must not reorder the list. Status: 400 invalid or empty/over-long title, 401 unauthenticated, 403 when the caller is neither the creator nor an agent editor, 404 when the chat is not nested under the supplied agent and workspace (cross-tenant included), and 500 on a storage failure.

Delete Chat

DELETE /api/v1/agents/{agentId}/chats/{chatId}

The chat creator may delete their own chat; an agent editor may delete any chat for that agent. Chats with assignments cannot be deleted (409). A successful deletion returns 204 No Content. Auth: The chat creator may delete their own chat; an agent editor may delete any chat for that agent. Request: No body; agentId and chatId are required path parameters. Response: 204 No Content on deletion (the handler may also return the documented JSON deletion result). Status: 401 unauthenticated, 403 denied, 404 for an unknown or mis-nested chat, 409 when assignments prevent deletion, and 500 for cleanup failure.

Chat Attachments

POST /api/v1/agents/{agentId}/chats/{chatId}/attachments

Uploads an attachment for the chat through the sidecar. The multipart/form data field is file; the agent and chat must belong to the caller’s workspace. The endpoint returns the sidecar’s attachment metadata and uses 400 for an invalid upload, 404 for an unknown or mis-nested chat, and 502 when the sidecar cannot be reached. The blob is written to <crewID>/<agentSlug>/attachments/<chatId>/<attachmentId>/<filename>, which the agent sees at /output/<agentSlug>/attachments/<chatId>/<attachmentId>/<filename>. A provisioned crew owns that tree as uid 1001, so the server cannot create the directory host-side; the write is replayed through the running crew container as that uid. A stopped crew therefore returns 409, with the remedy in the message. One upload is one identity at one location. The attachment id segment is what makes that true. Uploading two different files under the same name — say evidence.pdf twice — produces two attachments, two directories and two blobs, each resolving to its own recorded checksum; neither overwrites the other. Re-uploading the same bytes under the same name in the same chat is a retry, not a second attachment: it resolves to the attachment that already exists and returns its path. Chat attachment blobs are deliberately not content-addressed, because the path is what the agent is told to open. They therefore live outside <root>/attachments/ and outside the content-addressed reclaim sweep; the delete endpoint below is how their bytes are recovered. Metadata is written before the bytes, not after. The row is inserted first in an unpublished state, the blob is written second, and the row is promoted last, so 201 means both exist: a success response can never mean “the bytes landed and nobody recorded it”. Every failure leaves an unpublished row, which is never listed and never returned, and which a background collector removes along with any bytes it names once it is more than an hour old (the sweep runs hourly, so within about two hours). Attachments uploaded before this scheme keep their original two-segment path (attachments/<chatId>/<filename>) and keep working unchanged — the stored key is the authority on where an attachment lives, so they list, resolve and delete exactly like new ones. Errors from the storage layer are forwarded as a single sentence prefixed with failed to save attachment: , not as a nested JSON document. Auth: Authenticated caller with create/write access to the agent chat. Request: multipart/form-data with required binary file field; no JSON body. Response: 201 Created with {filename, size, path, agent_path}. path is the agent-relative attachments/<chatId>/<attachmentId>/<filename>; agent_path is the same location as an absolute in-container path. Status: 400 invalid upload, 401 unauthenticated, 403 denied or the chat is not this agent’s, 404 unknown agent/chat, 409 the crew container is not running (start the crew and retry), 413 too large to write through the crew container, 503 no container runtime is configured, and 502 sidecar failure.

List Chat Attachments

GET /api/v1/agents/{agentId}/chats/{chatId}/attachments?workspace_id={workspaceId}

Every published attachment on one chat, newest first. Unpublished reservations (an upload that did not finish) are never included. Auth: Any authenticated member of the workspace that owns the chat. Response: 200 OK with an array. Each element carries id, workspace_id, owner_type (chat), owner_id (the chat id), filename, content_type, size_bytes, sha256, uploaded_by_user_id, uploaded_by_agent_id, uploaded_by_name, created_at, path and agent_path. id is the durable identity — it is what the delete below takes, and it is the segment inside path. Status: 400 when a path id is missing, 401 unauthenticated, 404 for an unknown, mis-nested or cross-tenant chat (the three are indistinguishable by design), 500 on a read failure.

Delete Chat Attachment

DELETE /api/v1/agents/{agentId}/chats/{chatId}/attachments/{attachmentId}?workspace_id={workspaceId}

Removes the attachment: the stored file first, then the metadata row. Idempotent. Deleting an attachment that is already gone answers 204 — what the caller asked for is already true. Cross-tenant access is refused one step earlier: an attachment in another workspace is reachable only through a chat in that workspace, and that chat is a 404 here. If the unlink fails (most often a stopped crew, which owns the tree) the row is kept and the error is forwarded as failed to delete attachment: …; retrying the same call completes the deletion. The order is deliberate — a row that outlives its bytes is visible and repairable, whereas bytes that outlive their row are unreachable for ever, since no sweep walks this tree. Auth: Authenticated caller with create/write access to the agent chat. Request: No body. Response: 204 No Content. Status: 400 when a path id is missing, 401 unauthenticated, 403 denied, 404 for an unknown, mis-nested or cross-tenant chat, 409/5xx forwarded from the storage layer when the bytes cannot be removed, 502 sidecar failure.

Credential Bindings

GET /api/v1/agents/{agentId}/credential-bindings?workspace_id={workspaceId}

Lists the agent’s MCP server bindings. Each item includes id, agent_id, mcp_server_id, mcp_server_scope (workspace or crew), optional credential/type/header fields, enabled, optional config_override_json, timestamps, server names, and optional credential_name. Returns 404 when the agent is not in the workspace.

Agent Integrations

GET    /api/v1/agents/{agentId}/integrations?workspace_id={workspaceId}
POST   /api/v1/agents/{agentId}/integrations?workspace_id={workspaceId}
PATCH  /api/v1/agents/{agentId}/integrations/{integrationId}?workspace_id={workspaceId}
DELETE /api/v1/agents/{agentId}/integrations/{integrationId}?workspace_id={workspaceId}
GET    /api/v1/agents/{agentId}/integrations/resolved?workspace_id={workspaceId}

These are the agent MCP-binding routes. POST requires mcp_server_id and mcp_server_scope (workspace or crew); writes require MANAGER+ and reads require workspace membership. The resolved route returns the effective workspace → crew → agent integration cascade. Auth: Authenticated workspace member. Request: No body; agentId is required and workspace context scopes the resolution. Response: 200 OK with an integrations array containing the effective workspace/crew configuration. Status: 400 for invalid request/workspace context, 401 when unauthenticated, 403 when denied, and 404 when the agent is not found.

Agent Notification Channels

GET /api/v1/agents/{agentId}/notification-channels?workspace_id={workspaceId}

Returns { "channels": [...] }, where each channel contains id, type, optional provider, and enabled. It is readable by any workspace member; unknown or cross-workspace agents return 404. Auth: Any authenticated workspace member. Request: No body; agentId is required and workspace context is required. Response: 200 OK with { "channels": [...] }. Status: 400 when agentId is missing or request context is invalid, 401 when workspace context is missing, 403 when access is denied, and 500 when the channel lookup fails.

Agent Runs

GET /api/v1/agents/{agentId}/runs?workspace_id={workspaceId}

List execution history for an agent. Response: 200 OK — array of run objects.

Agent Proxy Endpoints

These endpoints proxy requests through the crewshipd sidecar to the agent’s container.

POST /api/v1/agents/{agentId}/stop halts a running agent.

Endpoint	Method	Description
`GET /api/v1/agents/{agentId}/debug`	GET	Debug information for a running agent
`GET /api/v1/agents/{agentId}/files`	GET	List files in agent workspace
`GET /api/v1/agents/{agentId}/files/download?path=...`	GET	Download a file
`PUT /api/v1/agents/{agentId}/files/save`	PUT	Save/upload a file
`GET /api/v1/agents/{agentId}/container-files`	GET	List files inside the running container (see below)
`GET /api/v1/agents/{agentId}/git-log`	GET	Recent git commits from the container workspace (see below)
`GET /api/v1/agents/{agentId}/logs`	GET	Get agent logs
`POST /api/v1/agents/{agentId}/stop`	POST	Stop a running agent

Container Files

GET /api/v1/agents/{agentId}/container-files?subdir={path}

Lists files inside the agent’s running container (as opposed to /files, which lists the persistent workspace mount). Proxied through crewshipd; the request is rejected before the IPC hop if the agent is not assigned to a crew. (internal/api/proxy_files.go:350) Auth: Session or CLI token + workspace membership with at least read-tier role (canRole(role, "read")) Query Parameters:

Parameter	Type	Description
`subdir`	string	Optional sub-path within the container’s working directory (normalized to reject `..` traversal)

Response: 200 OK — JSON array of file entries (unwrapped from the IPC layer’s {files: [...]} envelope). Returns [] when the sidecar response is unparseable or empty.

Status	Condition
`400`	`subdir` path is invalid (traversal or absolute)
`403`	Caller lacks `read`-tier role
`404`	Agent not found, or agent not assigned to a crew
`502`	Sidecar IPC call failed

Git Log

GET /api/v1/agents/{agentId}/git-log

Fetches recent git commits from the agent’s container workspace. Proxied through crewshipd; the agent’s slug is forwarded as agent_slug so the sidecar can scope the log to that agent’s directory inside the shared crew container. (internal/api/proxy.go:312) Auth: Session or CLI token + workspace membership with at least read-tier role (canRole(role, "read")) Response: 200 OK — JSON array of commit entries (unwrapped from the IPC layer’s {commits: [...]} envelope). Returns [] when the sidecar response is unparseable or empty.

Status	Condition
`403`	Caller lacks `read`-tier role
`404`	Agent not found, or agent not assigned to a crew
`502`	Sidecar IPC call failed

Chat Messages

This page links the agent lifecycle to the crew that owns it. The canonical crew reference has the full schemas; these endpoint-local notes preserve the request contract for the route references used on this page.

Get Crew

GET /api/v1/crews/{crewId}?workspace_id={workspaceId}

Auth: Session or CLI token plus workspace membership. Request: no body; crewId is required and workspace_id supplies workspace context. Response: 200 OK with the full crew object. Status: 404 when the crew is missing or outside the workspace.

Delete Crew

DELETE /api/v1/crews/{crewId}?workspace_id={workspaceId}

Auth: Session or CLI token plus OWNER or ADMIN role. Request: no body; crewId is required and workspace_id supplies workspace context. Response: 200 OK with { "success": true }. Status: 403 for an insufficient role and 404 when the crew is not found.

GET /api/v1/chats/{chatId}/messages

Get messages for a specific chat session. Proxied through crewshipd. Supports ?offset= and ?limit= (default 50, max 500). Auth: Session or CLI token with read-tier role, plus membership of the chat’s workspace. The workspace is resolved from the chat row (no workspace_id query param needed); the caller must appear in workspace_members for that workspace or the call returns 403. (internal/api/proxy.go:258) Response: 200 OK — proxied message payload. A chat that doesn’t exist yet (new session before its first message) returns { "messages": [] } rather than 404.

Status	Condition
`403`	Caller lacks `read`-tier role, or is not a member of the chat’s workspace
`502`	Sidecar IPC call failed

​Endpoints

​Status & Metrics

​Crews Status

​Contract: GET /api/v1/agents/crews-status

​Agent Load

​Model Discovery

​List Models

​Lifecycle & CRUD

​List Agents

​Response Fields

​Create Agent

​Get Agent

​Update Agent

​Delete Agent

​Rotate Webhook Secret

​Hire / Rehire / Approve

​Hire Agent

​Credential assignment

​Rehire Agent

​Approve Hire

​Agent Persona

​Get Persona

​Set Persona

​Reset Persona

​Get Persona History

​Suggest Persona

​Agent Self-Learning Posture

​Get Self-Learning

​Set Self-Learning

​Agent Inbox Summary

​Agent Peer Cards

​List Agent Peers

​Get Agent Peer Card

​Delete Agent Peer Card

​Related admin user routes

​List workspace users

​Export one user’s data

​Agent avatars

​Get stored avatar

​Store an avatar

​Clear a stored avatar

​When a stored render is dropped automatically

​Agent Skills

​List Skills

​Add Skill

​Remove Skill

​Agent Credentials

​List Credentials

​Assign Credential

​Remove Credential

​Agent Chats & Runs

​List Chats

​Create Chat

​Mark Chat Read

​Rename Chat

​Delete Chat

​Chat Attachments

​List Chat Attachments

​Delete Chat Attachment

​Credential Bindings

​Agent Integrations

​Agent Notification Channels

​Agent Runs

​Agent Proxy Endpoints

​Container Files

​Git Log

​Chat Messages

​Related crew routes

​Get Crew

​Delete Crew

Endpoints

Status & Metrics

Crews Status

Contract: `GET /api/v1/agents/crews-status`

Agent Load

Model Discovery

List Models

Lifecycle & CRUD

List Agents

Response Fields

Create Agent

Get Agent

Update Agent

Delete Agent

Rotate Webhook Secret

Hire / Rehire / Approve

Hire Agent

Credential assignment

Rehire Agent

Approve Hire

Agent Persona

Get Persona

Set Persona

Reset Persona

Get Persona History

Suggest Persona

Agent Self-Learning Posture

Get Self-Learning

Set Self-Learning

Agent Inbox Summary

Agent Peer Cards

List Agent Peers

Get Agent Peer Card

Delete Agent Peer Card

Related admin user routes

List workspace users

Export one user’s data

Agent avatars

Get stored avatar

Store an avatar

Clear a stored avatar

When a stored render is dropped automatically

Agent Skills

List Skills

Add Skill

Remove Skill

Agent Credentials

List Credentials

Assign Credential

Remove Credential

Agent Chats & Runs

List Chats

Create Chat

Mark Chat Read

Rename Chat

Delete Chat

Chat Attachments

List Chat Attachments

Delete Chat Attachment

Credential Bindings

Agent Integrations

Agent Notification Channels

Agent Runs

Agent Proxy Endpoints

Container Files

Git Log

Chat Messages

Related crew routes

Get Crew

Delete Crew