Crews - Crewship

Crews are isolated agent teams, each with its own container resources, network policy, and members. A crew bundles the runtime sandbox (memory/CPU/TTL, runtime image, devcontainer/mise config), the egress posture (free vs restricted with an allowed-domain list), an autonomy policy, an optional shared persona, and cross-crew connections that gate agent-to-agent messaging. All crew endpoints require authentication and workspace context. The workspace may be supplied as workspace_id (query), {workspaceId} (path), or the X-Workspace-ID header; query/path values take precedence and may be a workspace ID or slug.

Endpoints

Method	Endpoint	Purpose
GET	`/api/v1/crews`	List a paginated set of crews in a workspace
POST	`/api/v1/crews`	Create a crew
GET	`/api/v1/crews/{crewId}`	Get a single crew
PATCH / PUT	`/api/v1/crews/{crewId}`	Update a crew
DELETE	`/api/v1/crews/{crewId}`	Soft-delete a crew
GET	`/api/v1/crews/{crewId}/members`	List crew members
POST	`/api/v1/crews/{crewId}/members`	Add a crew member
PATCH	`/api/v1/crews/{crewId}/members/{memberId}`	Update a member’s per-crew role
DELETE	`/api/v1/crews/{crewId}/members/{memberId}`	Remove a crew member
GET	`/api/v1/crews/{crewId}/persona`	Get the crew persona
PUT	`/api/v1/crews/{crewId}/persona`	Set the crew persona
DELETE	`/api/v1/crews/{crewId}/persona`	Reset the crew persona
GET	`/api/v1/crews/{crewId}/policy`	Get the crew autonomy policy
PUT	`/api/v1/crews/{crewId}/policy`	Set the crew autonomy policy
POST	`/api/v1/crews/{crewId}/apply-avatar-style`	Apply an avatar style across agents
POST	`/api/v1/crews/{crewId}/container-start`	Start the crew’s runtime container
POST	`/api/v1/crews/{crewId}/container-stop`	Stop the crew’s runtime container and sidecars
GET	`/api/v1/crews/{crewId}/container-status`	Get the crew’s runtime container status
GET	`/api/v1/crews/{crewId}/credential-readiness`	Report credentials whose CLI is missing from the container
GET	`/api/v1/crews/{crewId}/capabilities`	Return the crew’s authoring capabilities bundle
GET	`/api/v1/crew-connections`	List crew connections
POST	`/api/v1/crew-connections`	Create a crew connection
DELETE	`/api/v1/crew-connections/{connectionId}`	Delete a crew connection
GET	`/api/v1/crews/{crewId}/files`	List files in the crew workspace
GET	`/api/v1/crews/{crewId}/files/download`	Download a file
PUT	`/api/v1/crews/{crewId}/files/save`	Save/upload a file
DELETE	`/api/v1/crews/{crewId}/files/delete`	Delete a file
GET	`/api/v1/crews/{crewId}/git-diff`	Read the crew’s base-branch diff
GET	`/api/v1/crews/{crewId}/services`	List live sidecar services
GET	`/api/v1/crews/{crewId}/containers`	List the crew’s live containers
GET	`/api/v1/crews/{crewId}/assignments`	List task assignments
GET	`/api/v1/crews/{crewId}/peer-conversations`	List peer conversations
GET	`/api/v1/crews/{crewId}/standup`	Get the crew standup summary
GET	`/api/v1/crews/{crewId}/escalations`	List crew escalations
PATCH	`/api/v1/escalations/{escalationId}/resolve`	Resolve an escalation
POST	`/api/v1/escalations/{escalationId}/cancel`	Withdraw an escalation without deciding it
POST	`/api/v1/escalations/sweep-expired`	Expire every past-deadline escalation
GET	`/api/v1/escalations/pending-count`	Count pending escalations

Crew CRUD

Create, read, update, and soft-delete crews and their container/network configuration.

List Crews

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

Returns up to 100 crews in the workspace, ordered by created_at DESC, id DESC. Use limit (maximum 500) and offset for pagination. Auth: Session or CLI token + workspace membership Request: No path parameters or request body. Workspace context is required; provide it using the workspace_id query parameter, {workspaceId} path context where supported, or X-Workspace-ID as described above. Response: 200 OK

[
  {
    "id": "cm1abc123",
    "workspace_id": "ws_123",
    "name": "Engineering",
    "slug": "engineering",
    "description": "Core engineering team",
    "color": "blue",
    "icon": "code",
    "avatar_style": "bottts",
    "container_memory_mb": 4096,
    "container_cpus": 2.0,
    "container_ttl_hours": 24,
    "network_mode": "restricted",
    "allowed_domains": ["api.github.com", "registry.npmjs.org"],
    "mcp_config_json": null,
    "escalation_config": null,
    "issue_prefix": "ENG",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z",
    "_count": {
      "agents": 3,
      "members": 2
    }
  }
]

Response Fields

Field	Type	Description
`id`	string	Crew ID
`workspace_id`	string	Parent workspace ID
`name`	string	Display name
`slug`	string	URL-safe identifier
`description`	string?	Crew description
`color`	string?	Palette color ID
`icon`	string?	Lucide icon name
`avatar_style`	string?	Avatar style for agents (e.g., `"bottts"`)
`container_memory_mb`	integer	Container memory limit in MB
`container_cpus`	number	Container CPU limit
`container_ttl_hours`	integer?	Container idle TTL in hours. `null` = never configured, so the server default (4 hours) applies; `0` = never stop
`network_mode`	string	`"free"` or `"restricted"`
`network_mode_enforced`	boolean	Whether the current container provider enforces `network_mode`.
`network_mode_unenforced_reason`	string	Provider explanation when enforcement is unavailable; omitted when enforced.
`allowed_domains`	string[]	Allowed domains (restricted mode only)
`allow_private_endpoints`	boolean	Whether private/LAN model endpoints are allowed; metadata and link-local addresses remain blocked.
`mcp_config_json`	string?	Raw MCP server config JSON
`escalation_config`	string?	Escalation policy config JSON
`runtime_image`	string?	Custom runtime image (e.g., `ghcr.io/org/runtime:1.0`)
`devcontainer_config`	string?	Raw devcontainer.json (max 100 KB)
`mise_config`	string?	Raw mise config TOML (max 10 KB)
`services_json`	string?	Sidecar services JSON (max 64 KB)
`cached_image`	string?	Locally built image tag (set by provisioner)
`config_hash`	string?	Hash of devcontainer/mise/runtime inputs used for `cached_image`
`max_ephemeral_agents`	integer	Per-crew quota enforced by the hire flow; always present on List/Get/Update responses
`issue_prefix`	string?	Issue identifier prefix (e.g., `"ENG"`); always `null` on List (only populated by Get)
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp
`_count.agents`	integer	Number of active agents
`_count.members`	integer	Number of crew members

Create Crew

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

Auth: Session or CLI token + 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, `^[a-z0-9][a-z0-9_-]*$`)
`description`	string	No	`null`	Crew description
`color`	string	No	`null`	Palette ID (`blue`, `emerald`, `violet`, `amber`, `rose`, `cyan`, `lime`, `fuchsia`)
`icon`	string	No	`null`	Lucide icon name (`code`, `rocket`, `clipboard`, etc.)
`container_memory_mb`	integer	No	`4096`	Container memory limit in MB; must be between `6` and `262144` (`0` uses the server default, `4096`). Below `2048` succeeds with a `warnings` entry
`container_cpus`	number	No	`2.0`	Container CPU limit; must be between `0.01` and `512` (`0` uses the server default, `2.0`). Below `0.5` succeeds with a `warnings` entry
`container_ttl_hours`	integer	No	`null`	Idle hours before the crew container is stopped. Omit it (`null`) to take the server default of `4`; send `0` to never stop it. Negative is rejected
`network_mode`	string	No	`"restricted"`	`"free"` or `"restricted"` (new crews default to `restricted` with an empty allowlist — LLM/CLI providers stay reachable; arbitrary egress is denied)
`allowed_domains`	string[]	No	`[]`	Allowed domains when `network_mode` is `"restricted"` (ignored otherwise)
`runtime_image`	string	No	`null`	Custom runtime image; existence is validated against the registry before insert
`devcontainer_config`	string	No	`null`	Raw devcontainer.json (max 100 KB; parsed for syntax)
`mise_config`	string	No	`null`	Raw mise config TOML (max 10 KB; parsed for syntax)
`services_json`	string	No	`null`	Sidecar services JSON (max 64 KB; structurally validated)

Two floors. container_memory_mb and container_cpus are rejected with a 400 only below Docker’s own minimums (6 MB, 0.01 CPU) — the daemon refuses to create a container there, so the request could never have worked.Between that and the usable floor (2048 MB, 0.5 CPU by default) the crew is created, and the response carries a warnings array explaining what will break: a warmed agent CLI holds 1.5–2 GiB, so a smaller crew is created successfully and then OOM-killed (exit 137) on start. A small crew can be deliberate, and refusing it would not make it bigger — so this is advice, not a veto. Memory is a cgroup ceiling rather than a reservation, so sizing at the floor costs an idle host nothing.The usable floor is settable per instance via the runtime.agent_min_memory_mb and runtime.agent_min_cpus instance settings. runtime.agent_min_memory_mb is also the divisor behind a crew’s concurrent-run budget.0 on either field means “use the server default”, and it resolves to the same size on POST and on PATCH — the stored row never holds 0.

warnings (array of strings, POST and PATCH responses only) is present only when there is something to say and is otherwise omitted. It is additive — a client that ignores it sees an unchanged crew object.

{
  "id": "c...",
  "slug": "tiny",
  "container_memory_mb": 512,
  "warnings": [
    "container_memory_mb 512 is below 2048, the memory one agent needs: the container will be created, but the agent CLI is likely to be OOM-killed (exit 137) on start. Raise the crew's memory, or lower the floor with `crewship instance settings set runtime.agent_min_memory_mb <mb>`."
  ]
}

{
  "name": "Engineering",
  "slug": "engineering",
  "description": "Core engineering team",
  "color": "blue",
  "icon": "code",
  "container_memory_mb": 4096,
  "container_cpus": 2.0,
  "network_mode": "restricted",
  "allowed_domains": ["api.github.com", "registry.npmjs.org"]
}

Response: 201 Created — returns the created crew object (same shape as List response item). Error Responses:

Status	Condition
`400`	Invalid name/slug length or format, invalid `network_mode`, invalid domain entry, `runtime_image` not found in registry, oversize or invalid `devcontainer_config`/`mise_config`/`services_json`
`402`	License crew limit exceeded
`403`	Insufficient role
`409`	Slug already taken in this workspace

Get Crew

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

Auth: Session or CLI token + workspace membership Request: crewId is a required path parameter and workspace_id selects the workspace. No request body.

Path Parameter	Description
`crewId`	Crew ID

Response: 200 OK — full crew object including _count, issue_prefix, mcp_config_json, and escalation_config.

Status	Condition
`404`	Crew not found or does not belong to workspace

Update Crew

PATCH /api/v1/crews/{crewId}?workspace_id={workspaceId}
PUT /api/v1/crews/{crewId}?workspace_id={workspaceId}

Both PATCH and PUT are supported and behave identically (partial update — only provided fields are changed). Auth: Session or CLI token + OWNER or ADMIN role Request Body: All fields are optional.

Field	Type	Description
`name`	string	Display name (2-100 characters)
`slug`	string	URL-safe identifier (2-50 characters)
`description`	string	Crew description
`color`	string	Palette ID
`icon`	string	Lucide icon name
`avatar_style`	string	Avatar style for agents
`container_memory_mb`	integer	Container memory limit in MB; must be between `6` and `262144` (`0` resets to the server default, `4096`). Shrinking below `2048` succeeds with a `warnings` entry
`container_cpus`	number	Container CPU limit; must be between `0.01` and `512` (`0` resets to the server default, `2.0`). Shrinking below `0.5` succeeds with a `warnings` entry
`container_ttl_hours`	integer	Idle hours before the crew container is stopped (`0` = never stop, stored as `0`; negative is rejected)
`max_ephemeral_agents`	integer	Per-crew hire-flow quota; must be between `0` and `100`
`network_mode`	string	`"free"` or `"restricted"`
`allowed_domains`	string[]	Allowed domains (restricted mode)
`mcp_config_json`	string	Raw MCP server config JSON (must contain `mcpServers` object)
`escalation_config`	string	Escalation policy config JSON (thresholds 0-1, `auto_approve_threshold` > `require_approval_below`)
`issue_prefix`	string	Issue identifier prefix (e.g., `"ENG"`); empty string clears
`runtime_image`	string	Custom runtime image (empty string clears; existence validated)
`devcontainer_config`	string	Raw devcontainer.json (empty string clears; max 100 KB)
`mise_config`	string	Raw mise config TOML (empty string clears; max 10 KB)
`services_json`	string	Sidecar services JSON (empty/whitespace clears; max 64 KB)

Response: 200 OK — updated crew object.

Changing network_mode, allowed_domains, or services_json triggers a container restart so the docker provider picks up the new policy / sidecar set on the next agent run. Changing runtime_image, devcontainer_config, or mise_config invalidates cached_image + config_hash to force a rebuild.

container_memory_mb / container_cpus do not restart the container, and do not reach a running one. They are cgroup limits, fixed when the container is created — a running crew keeps the limits it was created with while this response, and every later GET, reports the new ones. The container is deliberately not stopped for them: unlike a stale network policy, a stale memory limit is not a live exposure, and killing whatever the crew is executing costs more than the delay does.When the crew’s container is running, the response carries a warnings entry saying so. A stopped one is rebuilt with the new limits on its next wake and gets no warning, because nothing is pending on the operator. GET /container-status reports the configured and effective figures side by side.

Status	Condition
`400`	Invalid field values (name/slug length, slug format, `network_mode`, domain entry, `container_ttl_hours` negative, `max_ephemeral_agents` outside 0-100, MCP JSON missing `mcpServers`, escalation thresholds out of range, oversize or invalid `devcontainer_config`/`mise_config`/`services_json`, `runtime_image` not found)
`403`	Insufficient role
`404`	Crew not found
`409`	Slug already taken

Delete Crew

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

Soft-deletes the crew (sets deleted_at) and cascade-deletes its missions, mission tasks, and crew members so identifier prefixes can be reused. The slug is rewritten to {slug}_deleted_{id} on next Create reuse.

The crew’s agents are soft-deleted with it, which releases their slugs too: re-applying the manifest that created them succeeds without a manual DELETE /api/v1/agents/{agentId} first. Each agent’s slug is rewritten to {slug}_deleted_{id} when a new agent claims it, exactly as the crew’s is.

Auth: Session or CLI token + OWNER or ADMIN role Request: crewId is a required path parameter and workspace_id selects the workspace. No request body. Response: 200 OK

{ "success": true }

Status	Condition
`403`	Insufficient role
`404`	Crew not found

WebSocket event: crew.deleted broadcast to workspace:{workspaceId}

Members

Manage the per-crew membership roster and optional per-crew role overrides that win over the workspace role for crew-scoped permissions.

List Members

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

Request: crewId is a required path parameter and workspace_id is the workspace query parameter. No request body. Response: 200 OK — array of member objects.

Add Member

POST /api/v1/crews/{crewId}/members?workspace_id={workspaceId}

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

Field	Type	Required	Description
`user_id`	string	Yes	Target user’s ID (must already be a workspace member)
`role`	string	No	Optional per-crew role override — one of `OWNER`, `ADMIN`, `MANAGER`, `MEMBER`, `VIEWER`. Omit to inherit the workspace role.

{
  "user_id": "user_abc123",
  "role": "MANAGER"
}

Response: 201 Created — member object with nested user (id/email/full_name/avatar_url). The role override is not echoed on the Add response (it is only included by List Members).

Status	Condition
`400`	Missing `user_id`, invalid `role`, or user is not a workspace member
`404`	Crew not found
`409`	User is already a member of this crew

Update Member Role

PATCH /api/v1/crews/{crewId}/members/{memberId}?workspace_id={workspaceId}
Content-Type: application/json

Elevate or clear the per-crew role override. The crew-member row carries an optional role column that, when set, wins over the workspace-level role for permissions scoped to this crew. Clearing it (empty or omitted role) drops the member back to inheriting their workspace role. Auth: OWNER or ADMIN role on the workspace. A per-crew ADMIN is not allowed to reshape membership — that could ladder a MEMBER straight to OWNER and bypass the workspace gate. Request Body:

Field	Type	Required	Description
`role`	string	No	One of `OWNER`, `ADMIN`, `MANAGER`, `MEMBER`, `VIEWER`. Omit or pass `""` to clear the override (member inherits workspace role).

{ "role": "ADMIN" }

Response: 200 OK — a status envelope echoing the applied role (an empty role means the override was cleared):

{ "status": "updated", "role": "ADMIN" }

Status	Condition
`400`	`role` is not in the enum set
`403`	Caller is not workspace OWNER / ADMIN
`404`	Crew or member not found

Remove Member

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

Auth: OWNER or ADMIN role Request: crewId and memberId are required path parameters; workspace_id is the workspace query parameter. No request body. Response: 200 OK

{ "success": true }

Status	Condition
`404`	Crew or member not found

Persona

The crew layer of the persona stack — PERSONA.md markdown that the orchestrator injects into every agent in the crew, used as the default when an agent has no agent-layer file. Resolution is layered: the agent layer wins if present; otherwise crew default; otherwise the synthesised “You are the …” stub. See the Agent Persona section in the agents reference for the cross-layer model and cap_bytes (1500). All three endpoints are operator-only; there is no crew-flavoured suggest analog (agents propose into their own layer, not the crew default).

Get Crew Persona

GET /api/v1/crews/{crewId}/persona

Request: crewId is a required path parameter. No request body. Response: 200 OK

{
  "crew_id": "crew-uuid",
  "layer": "crew",
  "content": "# Default persona for this crew...\n",
  "bytes": 412,
  "cap_bytes": 1500
}

Unlike GET /agents/{id}/persona, this endpoint does not report a from_default flag — the crew layer either has a file or it doesn’t. When empty, content is "" and clients fall through to the per-agent synthesised default.

Set Crew Persona

PUT /api/v1/crews/{crewId}/persona
Content-Type: application/json

Writes the crew layer file. Records a row in memory_versions keyed to the crew-layer path so the history endpoint can replay the chain. Request:

{ "content": "# Default persona for this crew\n\n..." }

Response: 200 OK — { "layer": "crew", "bytes": N, "updated": "<rfc3339>" }

Status	Condition
`413`	`content` exceeds `cap_bytes` (1500)
`404`	Crew not found
`500`	Storage write / fsync failure

Reset Crew Persona

DELETE /api/v1/crews/{crewId}/persona

Request: crewId is a required path parameter. No request body. Removes the crew layer file. Subsequent reads return empty content and agents fall back to their per-role synthesised default. Response: 204 No Content

Policy

Each crew carries an autonomy posture that gates every HITL-relevant decision the orchestrator makes — memory writes, skill creation, behavior-monitor escalations, persona suggestions, ephemeral spawns. The dial is read by every PR-B / PR-C subsystem via the shared policy.Resolver. The CLI counterpart is crewship policy get/set.

Field	Values	Meaning
`autonomy_level`	`strict` / `guided` / `trusted` / `full`	How much an agent can do without operator approval. `strict` queues everything; `full` auto-applies most decisions.
`behavior_mode`	`warn` / `block`	What the behavior monitor does on a flagged action — `warn` lets it through with a journal entry, `block` rejects.

Get Crew Policy

GET /api/v1/crews/{crewId}/policy

Response: 200 OK

{
  "crew_id": "crew-uuid",
  "autonomy_level": "guided",
  "behavior_mode": "warn",
  "set_by_user_id": "user-uuid",
  "set_at": "2026-05-26T14:22:10Z",
  "reason": "Default for newly-onboarded crews"
}

set_by_user_id / set_at / reason are omitted on crews whose policy still matches the seed defaults (no operator has ever flipped it). On crews that have been touched at least once, the audit triple records who, when, why.

Set Crew Policy

PUT /api/v1/crews/{crewId}/policy
Content-Type: application/json

Replaces the policy. Records the audit triple (set_by_user_id, set_at, reason) atomically with the value change and invalidates the resolver cache so the next decision sees the new state. Auth: Session or CLI token + workspace membership (no additional role gate) Request:

{
  "autonomy_level": "trusted",
  "behavior_mode": "block",
  "reason": "Crew has cleared 30 days of approvals without an override"
}

Field	Required	Notes
`autonomy_level`	yes	Must be one of the four enum values; other strings return `400`.
`behavior_mode`	yes	`warn` or `block`. Missing field returns `400` (no silent default).
`reason`	conditional	Required only when `autonomy_level=full` — non-empty, persisted on the audit triple. Optional for `strict` / `guided` / `trusted`.

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

Status	Condition
`400`	Invalid enum value, the forbidden `full` + `block` combination, or `reason` missing when `autonomy_level=full`
`404`	Crew not found

Avatar

Bulk-apply an avatar style across a crew’s agents, or clear per-agent overrides.

Apply Avatar Style

POST /api/v1/crews/{crewId}/apply-avatar-style?workspace_id={workspaceId}

Applies an avatar_style to all non-deleted agents in the crew, or clears per-agent overrides. This also clears any stored avatar renders on those agents, because a stored render depicts the previous style — leaving it would make this call a no-op for every agent that has one. Affected agents revert to avatar_url: null and are re-stored on next view. PATCH /api/v1/crews/{crewId} with a new avatar_style does the same for the narrower set of agents that inherit the crew default (their own avatar_style is null). Agents with an explicit style of their own are unaffected by the crew default, so they keep their stored render. Auth: OWNER or ADMIN role Request Body:

Field	Type	Required	Description
`avatar_style`	string	Conditional	Style to apply (required unless `reset_overrides` is `true`)
`reset_overrides`	boolean	No	When `true`, clears `avatar_style` on every agent (ignores `avatar_style`)

Response: 200 OK

{ "updated": 3, "style": "bottts" }

When reset_overrides is true, the response is { "updated": N, "reset": true }.

Status	Condition
`400`	`avatar_style` missing and `reset_overrides` not set
`404`	Crew not found

Container

Start Container

POST /api/v1/crews/{crewId}/container-start?workspace_id={workspaceId}

Starts the crew’s runtime container and returns once it is running. This is not provisioning. Provision builds the container image; this creates and starts the container itself, running the same sequence an agent run performs — the crew’s provisioned image, its mounts, containerEnv, capabilities and resource limits, and any sidecar services declared in services_json. A crew with no image yet is provisioned first, so the call works on a cold crew (that build can take minutes). Idempotent. Starting a running crew returns its existing container and 200, so a caller can start-then-write without branching on current state. Auth: MANAGER+ (role create) — starting a container spends host memory and CPU, so it sits with provision / rebuild / restart-agents rather than with the reads. Request: crewId is a required path parameter and workspace_id selects the workspace. No request body. Response: 200 OK

{
  "crew_id": "ccrew0123456789abcdefghij",
  "slug": "uctarna",
  "container_id": "3f9a1c02b7de...",
  "status": "running",
  "notices": ["sidecar services are not supported by this container provider"]
}

Response Fields:

Field	Type	Description
`crew_id`	string	The crew’s ID
`slug`	string	The crew’s slug
`container_id`	string	The runtime container’s ID
`status`	string	Always `running` on a `200`
`notices`	array?	Degradation the start survived — e.g. a container provider with no sidecar support, so a crew that declares `services:` came up without them. Absent when the crew started exactly as declared

Status	Condition
`400`	`crewId` missing
`403`	Insufficient role
`404`	Crew not found in this workspace
`502`	The image build failed, or the container failed to start
`503`	No container runtime is configured on this server (`--no-docker`, or a daemon unreachable at boot)

Why this exists. Files under /crew/shared are owned by the container user (uid 1001), so the server can only overwrite one by replaying the write inside the container — which has to be running. Against a stopped crew, PUT /files/save answers 409 file is owned by the crew runtime. Before this endpoint the only way to clear that was to run an agent at the crew with a throwaway prompt, spending tokens for a side effect.notices is returned rather than logged deliberately: the caller asked for this crew to be up, and “up, but without its declared postgres” changes what they do next.

CLI: crewship crew start

Stop Container

POST /api/v1/crews/{crewId}/container-stop?workspace_id={workspaceId}

Stops the crew’s runtime container and any sidecar services it declared. Proxied to crewshipd, which owns both halves of the operation. Idempotent. Stopping an already-stopped crew answers 200 — that is the state the caller asked for. Auth: MANAGER+ (role create). Not a lower bar than starting: stopping a crew somebody is working in interrupts them, so it is not read-shaped just because it frees memory rather than spending it. Request: crewId is a required path parameter and workspace_id selects the workspace. No request body. Response: 200 OK

{
  "crew_id": "ccrew0123456789abcdefghij",
  "slug": "uctarna",
  "status": "stopped"
}

No container_id: the container it would name is gone by the time the caller reads the answer, and returning one invites a follow-up call against a dead id.

Status	Condition
`400`	`crewId` missing
`403`	Insufficient role
`404`	Crew not found in this workspace
`502`	crewshipd refused or could not be reached
`503`	No container runtime is configured on this server

Named volumes are not removed, so sidecar data survives a stop. Only crewship crew delete removes them (see the crew-delete teardown report).Container memory and CPU limits are applied at container-create time, so stop-then-start is how a resize takes effect on a crew that is already running.

CLI: crewship crew stop

Container Status

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

Returns the crew’s runtime container state, proxied from crewshipd over the internal IPC socket. Useful for confirming a crew’s container came back up after a network-policy change (which stops the container so it is recreated with the new policy on the next agent run). Auth: any workspace member Request: crewId is a required path parameter and workspace_id selects the workspace. No request body. Response: 200 OK

{
  "crew_id": "ccrew0123456789abcdefghij",
  "status": "running",
  "uptime": "2026-07-13T00:00:00Z",
  "runtime_contract": "current",
  "configured_memory_mb": 8192,
  "configured_cpus": 2,
  "effective_memory_mb": 4096,
  "effective_cpus": 2,
  "config_drift": [
    { "field": "container_memory_mb", "configured": 8192, "effective": 4096 }
  ]
}

Response Fields:

Field	Type	Description
`crew_id`	string	The crew’s ID (always the caller’s ID, echoed back)
`status`	string	`running`, `creating`, `stopped`, `error`, `not_configured`, or `unknown`
`uptime`	string?	RFC 3339 container start time (present when running)
`runtime_contract`	string?	`current` or `stale` — whether this container was created with the container configuration the running server applies today. Absent when the provider does not track it; absent is not `current`
`configured_memory_mb`	int	The crew’s configured memory limit (the `crews` row)
`configured_cpus`	number	The crew’s configured CPU limit
`effective_memory_mb`	int?	The memory limit the RUNNING container was created with, read off the container. Absent when the container declares none or the provider does not report it — absent is not `0`
`effective_cpus`	number?	Same, for CPUs
`config_drift`	array?	One `{field, configured, effective}` entry per limit the container disagrees with. Absent when they agree, or when there was nothing to compare

Why config_drift exists. runtime_contract asks whether this container is older than the BUILD; config_drift asks whether it is older than this CREW’s own settings. container_memory_mb and container_cpus are cgroup limits, fixed at container-create and unchangeable on a running container, so updating a crew moves the row and this endpoint’s configured_* fields while effective_* stays where it was.Same response as for a stale runtime contract, for the same reasons: a stopped container whose limits no longer match its crew is rebuilt on the next wake, and a running one is reported rather than killed. PATCH /api/v1/crews/{crewId} warns on the spot when it resizes a crew that is currently running.

Why runtime_contract exists. A crew container is created once and reused for as long as it keeps running, and the settings that harden it — the init process that reaps orphans, the core: 0 limit that stops a crashing agent writing its credential environment to disk, supplementary groups, swap, the /dev/shm size — are applied at container-create time and nowhere else. Upgrade the server and a crew that was already running keeps the OLD configuration indefinitely.stale means exactly that: this container predates the current configuration and does not carry what has been added since. Nothing is broken and no run fails; the container picks the new settings up the next time it is recreated — an idle-TTL stop, or crewship crew restart-agents <slug>. A container found stopped with a stale contract is rebuilt automatically on the next wake, because at that moment the rebuild costs nothing. A running one is never torn down for it: that would kill whatever the crew is executing.

Status values are deliberately coarse and the endpoint answers 200 even when the runtime is unavailable, so a polling UI/CLI can treat them as transient states rather than errors:

`status`	Meaning
`running`	Container is up
`creating`	Container is (re)starting
`stopped`	Container is not running
`not_configured`	No container runtime / IPC socket is configured on the server
`unknown`	`crewshipd` was unreachable or returned an unparseable response
`error`	Container is in a dead/OOM-killed state

Status	Condition
`400`	`crewId` missing
`404`	Crew not found in this workspace

CLI:

crewship crew container-status <slug-or-id>

Credential Readiness

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

Reports which of the credentials this crew can use are for a CLI the crew’s container does not have. The sandbox runtime image ships git, curl and jq. Tools like gh, aws, az, gcloud, kubectl, docker, terraform, npm and ansible exist in the container only when the crew’s devcontainer_config declares the matching feature (or mise installs the tool). A valid credential and a working agent are therefore two different things: a healthy GitHub PAT plus a crew with no github-cli feature still gets gh: command not found. The endpoint is read-only and advisory. It never edits devcontainer_config and never triggers a rebuild — adding a feature changes what runs inside the container, so it stays a separate, user-confirmed action (Update Crew or crewship crew config). Request: crewId is a required path parameter and workspace_id selects the workspace. No request body. Credentials are matched using the same three-way grant rule as the rest of the credentials surface: workspace-scoped, crew-scoped via credential_crews, or assigned to one of this crew’s agents (with any lease still live). Revoked and soft-deleted credentials are excluded. A provider with no known CLI (Notion, Stripe, an unrecognised string) reports nothing rather than guessing. Matching is on the tool name, not the feature ref, so an equivalent feature counts: docker-outside-of-docker satisfies a DOCKER credential, and a mise nodejs satisfies an NPM one. Auth: any workspace member Response: 200 OK

{
  "crew_id": "ccrew0123456789abcdefghij",
  "crew_slug": "ops",
  "tools": ["terraform"],
  "checked": 2,
  "gaps": [
    {
      "credential_id": "ccred0123456789abcdefghij",
      "credential_name": "gh-pat",
      "provider": "GITHUB",
      "tool": "gh",
      "feature": "ghcr.io/devcontainers/features/github-cli:1",
      "feature_id": "github-cli"
    }
  ]
}

Response Fields:

Field	Type	Description
`crew_id`	string	The crew’s ID
`crew_slug`	string	The crew’s slug
`tools`	string[]	CLI tools the container already has (devcontainer features + mise). Never `null`
`checked`	number	Credentials examined that carry a known tool requirement. `checked - len(gaps)` are already served
`gaps`	object[]	One entry per credential whose tool is absent. Never `null`
`gaps[].tool`	string	The binary the credential is meant to be read by, e.g. `gh`
`gaps[].feature`	string	The devcontainer feature ref that installs `tool`
`gaps[].feature_id`	string	The feature’s short id, e.g. `github-cli`

Status	Condition
`400`	`crewId` missing
`404`	Crew not found in this workspace

CLI:

crewship crew credential-readiness <slug-or-id>

Crew Capabilities

GET /api/v1/crews/{crewId}/capabilities

Returns one authoring-oriented capability bundle for the crew: resolved container resources, enabled crew integrations and their enabled tool names, agent slugs, available code runtimes, script-interpreter mappings, and the routine DSL JSON schema. Auth: authenticated workspace member Request: crewId is a required path parameter. Workspace context is required and may be supplied with X-Workspace-ID (or the equivalent workspace context described at the top of this page). No request body. Response: 200 OK

{
  "crew_id": "crew_123",
  "crew_slug": "engineering",
  "container": { "datastores": [], "tools": [] },
  "integrations": [],
  "agents": [],
  "runtimes": {
    "code": { "wired": ["cel"], "reserved_unwired": [] },
    "script_interpreters": { ".py": "python3" }
  },
  "schema": { "type": "object" }
}

container.datastores and container.tools are arrays and may be empty. Only enabled crew integrations are included; integrations[].tools contains only explicitly enabled crew-scoped tool bindings. schema is the nested routine DSL schema object, not a JSON-encoded string.

Status	Condition
`400`	`crewId` is missing
`404`	Crew not found in the selected workspace
`500`	Database or capability-resolution failure

Connections

Crew connections (“crew links” in the UI) define which crews can reach each other. A link is what allows cross-crew task assignment, messages and shared files; without one every attempt is refused server-side. direction is read from from_crew_id’s side: unidirectional means from may hand work to to and not the reverse; bidirectional means either may. Links to a soft-deleted crew are never listed and are removed when the crew is deleted.

List Connections

GET /api/v1/crew-connections?workspace_id={workspaceId}

Request: workspace_id is the required workspace query parameter. No request body. Response: 200 OK — array of connection objects:

[
  {
    "id": "cc_abc",
    "workspace_id": "ws_123",
    "from_crew_id": "crew_abc",
    "from_crew_name": "Engineering",
    "from_crew_slug": "engineering",
    "to_crew_id": "crew_xyz",
    "to_crew_name": "Design",
    "to_crew_slug": "design",
    "direction": "bidirectional",
    "status": "active",
    "created_at": "2024-01-15T10:00:00Z",
    "updated_at": "2024-01-15T10:00:00Z"
  }
]

Create Connection

POST /api/v1/crew-connections?workspace_id={workspaceId}

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

Field	Type	Required	Default	Description
`from_crew_id`	string	Yes	—	Source crew ID
`to_crew_id`	string	Yes	—	Target crew ID (must differ from `from_crew_id`)
`direction`	string	No	`"bidirectional"`	`"bidirectional"` or `"unidirectional"`

{
  "from_crew_id": "crew_abc",
  "to_crew_id": "crew_xyz",
  "direction": "bidirectional"
}

Response: 201 Created for a new link, 200 OK when one already existed.

{ "id": "cc_abc" }

The call is an upsert on the PAIR, not an insert: a pair is one edge whichever end you name first.

Same pair, same orientation → the stored link keeps its id and takes the new direction.
Same pair, reverse orientation → the stored link becomes bidirectional (you asked for the way back as well). To make a link one-way in the other direction, delete it and create it again.

Status	Condition
`200`	The pair was already linked; direction updated in place
`400`	Missing IDs, same source/target, or invalid `direction`
`404`	One or both crews not found in this workspace

Delete Connection

DELETE /api/v1/crew-connections/{connectionId}?workspace_id={workspaceId}

Auth: OWNER, ADMIN, or MANAGER role Request: connectionId is a required path parameter and workspace_id is the workspace query parameter. No request body. Response: 204 No Content

Status	Condition
`404`	Connection not found

Crew Files (Proxy)

File operations are proxied through the crewshipd sidecar to the crew’s container filesystem.

Endpoint	Method	Description
`GET /api/v1/crews/{crewId}/files`	GET	List files in crew workspace
`GET /api/v1/crews/{crewId}/files/download?path=...`	GET	Download a file
`PUT /api/v1/crews/{crewId}/files/save`	PUT	Save/upload a file

Delete a Crew File

DELETE /api/v1/crews/{crewId}/files/delete?path={path} Auth: Authenticated workspace member with the create capability. The crew must belong to the selected workspace. Request: No body. The required path query parameter is a relative file path under the crew’s shared/output tree. Absolute paths and traversal are rejected. Response: 200 OK with the sidecar response:

{ "status": "deleted", "path": "shared/probe.sh" }

Deletion is idempotent: a missing file still returns success. Statuses: 400 missing or invalid path; 401 unauthenticated; 403 insufficient role/capability; 404 crew not found in the workspace; 500 storage/delete failure; 502 sidecar unavailable. A missing storage provider may return 503 from the sidecar.

Crew Git Diff

GET /api/v1/crews/{crewId}/git-diff?agent_slug={agentSlug} Returns the crew container’s base-branch diff, the same change set used by the dashboard’s Changes tab. agent_slug is optional and selects the agent workspace when the crew has multiple agent workspaces. Auth: Authenticated workspace member with the read capability. The crew must belong to the selected workspace. Request: No body. Optional agent_slug query parameter. Response: 200 OK with the decoded git-diff object from crewshipd. If the workspace is not a repository, the response is { "is_repo": false }. Statuses: 401 unauthenticated; 403 insufficient role/capability; 404 crew not found in the workspace; 500 crew lookup failure; 502 crewshipd unavailable or diff computation failure.

Live Service Inventory

GET /api/v1/crews/{crewId}/services Returns the live sidecar containers, not the stored services_json configuration snapshot. Auth: Authenticated workspace member with the read capability. The crew must belong to the selected workspace. Request: No body or query parameters. Response: 200 OK:

{
  "services": [
    {
      "name": "postgres",
      "image": "postgres:16",
      "type": "postgres",
      "status": "running",
      "ports": ["5432/tcp"]
    }
  ]
}

type is one of postgres, redis, mysql, mongodb, or other. A provider without live service-list capability returns 200 with an empty services array. Statuses: 401 unauthenticated; 403 insufficient role/capability; 404 crew not found in the workspace; 500 crew lookup or service-list failure.

Live Container Inventory

GET /api/v1/crews/{crewId}/containers Returns every container the crew has on the runtime right now — its agent runtime container and its sidecars — with live state and usage. Wider than Live Service Inventory, which answers about sidecars only and renames them to their manifest service names; here name is the container’s real runtime name, the one docker logs takes. Auth: Authenticated workspace member with the read capability. The crew must belong to the selected workspace. Request: No body. workspace_id query parameter (or the X-Workspace-ID header) selects the workspace. Response: 200 OK:

{
  "containers": [
    {
      "name": "crewship-team-backend-ckcrew0001",
      "image": "crewship/agent:latest",
      "kind": "crew",
      "status": "running",
      "cpu_percent": 3.5,
      "memory_mb": 412,
      "agent_count": 4
    },
    {
      "name": "crewship-svc-backend-ckcrew0001-postgres",
      "image": "postgres:16",
      "kind": "sidecar",
      "status": "stopped",
      "cpu_percent": null,
      "memory_mb": null,
      "agent_count": null
    }
  ]
}

kind is crew (the agent runtime) or sidecar (a declared service). status is the live state — running, stopped, creating or error — the same vocabulary Container Status reports. null means unmeasured, never zero. A stopped container has no CPU or memory reading, a runtime without stats support (apple-container) has none for anything, and agent_count is set on the crew row only — no agent runs in a postgres container. Render an absent number as ”—”; rendering it as 0 draws an idle container where nothing was measured. A provider without live container-list capability returns 200 with an empty containers array. The array is always present: a client that treats a missing containers field as “nothing is running” reproduces the defect this endpoint was added to fix (#1697) — treat it as a broken response instead. Statuses: 400 missing crewId; 401 unauthenticated; 403 insufficient role/capability; 404 crew not found in the workspace; 500 crew lookup or container-list failure. A failed per-container stats read is not an error: that row’s cpu_percent and memory_mb come back null.

Crew Assignments

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

Request: crewId is a required path parameter and workspace_id is the workspace query parameter. No request body. List task assignments for a crew. Response: 200 OK — array of assignment objects.

Crew Peer Conversations

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

Request: crewId is a required path parameter and workspace_id is the workspace query parameter. No request body. List peer-to-peer conversations between agents in a crew. Response: 200 OK with an object containing conversations (array) and count (integer).

Status	Condition
`400`	Invalid crew or workspace context
`401`	Missing authentication
`403`	Caller is not allowed to read the crew

Crew Standup

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

Request: crewId is a required path parameter; optional query parameters are crew_id and since. No request body. Get standup summary for a crew. Response: 200 OK with crew_id, date, summary, and items fields.

Status	Condition
`400`	Invalid query or crew context
`401`	Missing authentication
`403`	Caller is not allowed to read the crew
`404`	Crew not found

Crew Escalations

An escalation is a question an agent asked a human and blocked on. It has one non-terminal state and three terminal ones:

Status	Meaning	Written by
`PENDING`	waiting for a human	the agent, via `POST /api/v1/internal/escalations`
`RESOLVED`	a human decided; `action` is `approve`, `reject` or `redirect`	resolve
`EXPIRED`	the deadline passed and nobody decided	the server (see below)
`CANCELLED`	a human withdrew the question without deciding	cancel

Terminal states are terminal — every transition out of one is a 409 whose message names the state actually reached. The deadline. Each escalation is raised with deadline_at = created_at + 300 s, published to the agent on the create so its wait is bounded by the server’s clock rather than one of its own. When the deadline passes with no answer, the row becomes EXPIRED and the agent continues without the answer, having been explicitly told so — the wait response carries status: EXPIRED and a mandatory warning, and the journal entry is severity warn. The run is not failed and no default answer is invented; see Harbormaster → What happens when nobody answers for the reasoning. Expiry is applied by the long poll the agent is on, by a 60 s background sweeper for rows whose agent is gone, and by the read paths below before they answer. All three go through one compare-and-swap, so a row expires exactly once. deadline_at is null on rows raised before the column existed; those never expire.

List Escalations

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

Auth: Authenticated workspace member; workspace_id must identify the caller’s workspace. Path / query parameters: crewId is the crew ID; workspace_id is the required workspace ID. Optional status narrows to one lifecycle state (PENDING, RESOLVED, EXPIRED, CANCELLED); an unrecognised value returns an empty list rather than everything, so a typo cannot silently widen the filter. Any past-deadline question in the workspace is settled before the list is built, so a row can never be listed as PENDING past its own deadline_at. Response: 200 OK with an array of escalation objects. Each carries deadline_at (nullable) alongside status, action, resolution, resolved_by and resolved_at.

Status	Condition
`401`	Missing authentication or workspace context
`500`	Database query or row scan failed

Resolve Escalation

PATCH /api/v1/escalations/{escalationId}/resolve?workspace_id={workspaceId}

Request: escalationId is a required path parameter, workspace_id selects the workspace, and the JSON body is the escalation decision (action and optional resolution details). Response: 200 OK with the resolved escalation id, status, and action.

Status	Condition
`400`	Invalid decision body
`401`	Missing authentication
`403`	Insufficient role
`404`	Escalation not found
`409`	Escalation is no longer `PENDING` — the message names the state it reached (`RESOLVED`, `EXPIRED` or `CANCELLED`)

Cancel Escalation

POST /api/v1/escalations/{escalationId}/cancel?workspace_id={workspaceId}

Auth: MANAGER+ (create role) — the same gate as resolve, because closing out a blocking request is the same class of act whichever way it is closed. Request: optional JSON body {"reason": "..."}. The reason is recorded on the row and in the journal entry. Withdraws a question that stopped mattering. Deliberately not the same as resolve --action reject: a rejection is a decision the agent should act on, while a cancellation says nobody ever considered it. Any agent still waiting is unblocked immediately with an explicit “no answer” warning. Response: 200 OK with { "id": string, "status": "CANCELLED" }.

Status	Condition
`403`	Insufficient role
`404`	Escalation not found — also the answer for another tenant’s id, so the endpoint is not an existence oracle
`409`	Escalation is no longer `PENDING`
`500`	Update failed

Sweep Expired Escalations

POST /api/v1/escalations/sweep-expired?workspace_id={workspaceId}

Auth: Authenticated workspace OWNER or ADMIN (manage role) — it writes terminal states. Request: no body. Scoped to the caller’s workspace, so it cannot reach another tenant’s rows. Expires every past-deadline PENDING escalation in the workspace now. The background sweeper and the read paths already do this; the endpoint makes the mechanism operable and observable rather than only inferable from a ticker. Running it twice returns 0 the second time. Response: 200 OK with { "expired": integer }.

Status	Condition
`401`	Missing workspace context
`403`	Caller is not `OWNER`/`ADMIN`
`500`	Sweep failed

Pending Escalation Count

GET /api/v1/escalations/pending-count?workspace_id={workspaceId}

Request: workspace_id is the workspace context. No request body. Returns count of pending escalations across the workspace. Past-deadline questions are settled first, so an unanswered escalation stops being counted once its deadline passes instead of accumulating forever. Response: 200 OK with { "count": integer }.

Status	Condition
`400`	Invalid workspace context
`401`	Missing authentication
`403`	Caller is not allowed to read escalations
`500`	Count query failed

Purge Crew Escalations

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

Auth: Authenticated workspace OWNER or ADMIN (manage role). Path / query parameters: crewId is the crew ID; workspace_id is the required workspace ID. The request has no body. The operation permanently deletes all escalation rows for that crew in that workspace. Response: 200 OK

{ "deleted": 2 }

Status	Condition
`400`	Missing `crewId`
`401`	Missing workspace context or authentication
`403`	Caller is not an `OWNER` or `ADMIN`
`500`	Database purge failed

Activity Feed (removed)

The dedicated GET /api/v1/activity aggregator has been removed. It merged three tables (assignments, peer conversations, escalations) in memory and would silently drop a whole source on any query error while still returning 200 OK. The activity feed is now sourced from the journal, which is the canonical event stream:

GET /api/v1/journal?entry_type=peer.conversation,peer.escalation,assignment.created,assignment.running&crew_id={crewId}

Filter by crew_id / agent_id, bound the window with since=, and page with cursor / limit (see Journal). Display names and crew colors are not part of the journal row (it stores ids + payload slugs); resolve them via GET /api/v1/journal/lookup. The crewship activity CLI command wraps this same query — see CLI · Activity.

​Endpoints

​Crew CRUD

​List Crews

​Response Fields

​Create Crew

​Get Crew

​Update Crew

​Delete Crew

​Members

​List Members

​Add Member

​Update Member Role

​Remove Member

​Persona

​Get Crew Persona

​Set Crew Persona

​Reset Crew Persona

​Policy

​Get Crew Policy

​Set Crew Policy

​Avatar

​Apply Avatar Style

​Container

​Start Container

​Stop Container

​Container Status

​Credential Readiness

​Crew Capabilities

​Connections

​List Connections

​Create Connection

​Delete Connection

​Crew Files (Proxy)

​Delete a Crew File

​Crew Git Diff

​Crew Git Diff

​Live Service Inventory

​Live Service Inventory

​Live Container Inventory

​Live Container Inventory

​Crew Assignments

​Crew Peer Conversations

​Crew Standup

​Crew Escalations

​List Escalations

​Resolve Escalation

​Cancel Escalation

​Sweep Expired Escalations

​Pending Escalation Count

​Purge Crew Escalations

​Activity Feed (removed)

Endpoints

Crew CRUD

List Crews

Response Fields

Create Crew

Get Crew

Update Crew

Delete Crew

Members

List Members

Add Member

Update Member Role

Remove Member

Persona

Get Crew Persona

Set Crew Persona

Reset Crew Persona

Policy

Get Crew Policy

Set Crew Policy

Avatar

Apply Avatar Style

Container

Start Container

Stop Container

Container Status

Credential Readiness

Crew Capabilities

Connections

List Connections

Create Connection

Delete Connection

Crew Files (Proxy)

Delete a Crew File

Crew Git Diff

Crew Git Diff

Live Service Inventory

Live Service Inventory

Live Container Inventory

Live Container Inventory

Crew Assignments

Crew Peer Conversations

Crew Standup

Crew Escalations

List Escalations

Resolve Escalation

Cancel Escalation

Sweep Expired Escalations

Pending Escalation Count

Purge Crew Escalations

Activity Feed (removed)