Skip to content
SupaCloud Docs
Select themeSelect language

`GET /api/agent-profiles` — list the workspace's agent profiles (runbooks).

GET
/api/agent-profiles
curl --request GET \
  --url https://example.com/api/agent-profiles \
  --cookie supacloud_session=<supacloud_session>

Authorizations

Section titled “Authorizations”

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
Array<object>
object
autonomy_level

ADR 0045 §3.1 Stage 4 — OPTIONAL profile autonomy override (mig 214, nullable SMALLINT). None = inherit the project/workspace level (sits between project and workspace in the §3.1 precedence chain). #[serde(default)] keeps old AgentProfileVersion JSON snapshots (pre-214) deserializable — they default to None (a no-op).

integer | null format: int32
autonomy_overrides

ADR 0045 §3.1 — per-axis Advanced override vector (mig 214, JSONB NOT NULL DEFAULT '{}'). Empty {} = no per-axis override; the editor reads an optional level key. #[serde(default)] keeps old snapshots deserializable. Runtime stays serde_json::Value; the spec types it as an open map.

object
key
additional properties
avatar_kind
required

Avatar rendering kind (color | initial | icon | image). Runtime String; the spec narrows it to the closed [AvatarKind] the editor offers.

string
Allowed values: color initial icon image
avatar_value
string | null
capability_allowlist
required
Array<string>
color
required
string
created_at
required
string format: date-time
default_agent_type
required
string
description
string | null
effort_default
One of:
null
enabled
required
boolean
execution_mode

Issue #364 / ADR 0039 (D7) — Claude execution mode lever (normal | workflow; ultracode was RETIRED from this dimension by #708 who-3, migration 285 — it survives only as the top EFFORT stage). #[serde(default = ...)] keeps old AgentProfileVersion JSON snapshots (written before this column existed) deserializable; they default to "normal" (a no-op). Runtime String; the spec narrows it to the closed [ExecutionMode].

string
Allowed values: normal workflow
fixed_model
string | null
id
required
string format: uuid
interactive_approval

ADR 0045 §3.2 Stage 3 — when true, a task running under this profile arms the interactive-approval gate (the runner’s canUseTool / pre-exec hook pauses on a dangerous tool call, an open question, or a visual before/after and waits for a human Approve/Reject; migration 213). false is today’s behaviour (no gate). #[serde(default)] keeps old AgentProfileVersion JSON snapshots (written before this column existed) deserializable — they default to false (a no-op).

boolean
is_workspace_default

Issue #242 — when true, this profile’s capability_allowlist is the workspace fallback MCP tool set for profile-less / empty-allowlist tasks. At most one profile per team carries this flag (enforced by the partial unique index uq_agent_profiles_workspace_default in migration 119).

boolean
mcp_memory_create

ADR 0049 (#547 / #548) — opt-in gate for the agent memory.create MCP tool (migration 249, BOOLEAN NOT NULL DEFAULT false). When false (the default for every profile) a task running under this profile CANNOT directly create a memory — memory.create fails closed; only a workspace admin enabling this on the profile editor opens the unreviewed direct-write path. Distinct from memory_policy.allow_propose_create (the default-true review-first gate). #[serde(default)] keeps old AgentProfileVersion JSON snapshots (written before this column existed) deserializable — they default to false (a no-op).

boolean
memory_policy
required

The fixed memory-policy knobs the editor reads. Runtime stays serde_json::Value; the spec types it as [AgentMemoryPolicy].

object
allow_personal
required
boolean
auto_inject_kinds
required
Array<string>
auto_inject_scopes
required
Array<string>
max_auto_memories
required
integer format: int64
mcp_read_kinds
required
Array<string>
mcp_read_scopes
required
Array<string>
model_policy
required

Model-selection policy (manual | fixed | auto). Runtime String; the spec narrows it to the closed [ModelPolicy].

string
Allowed values: manual fixed auto
name
required
string
persona_prompt
required
string
post_flight_checks
required

Forward-compatible list of post-flight check entries (e.g. the kind:"visual_verify" gate). Runtime stays serde_json::Value; spec-typed as an array of open maps.

Array<object>
object
key
additional properties
pr_template
string | null
pre_flight_checks
required

Forward-compatible list of pre-flight check entries (each an open object, e.g. a kind-discriminated gate). Runtime stays serde_json::Value; the spec types it as an array of open maps so the value is not stripped.

Array<object>
object
key
additional properties
required_worker_group_ids

ADR 0046 RUNG 1b — OPTIONAL profile worker-group affinity override (mig 227, nullable UUID[]). None = inherit (the head of the first-non-null profile->project->task chain — NULL contributes nothing); Some(vec![]) = an explicit “no affinity from this source”. Resolved into the task’s required_labels by services::runners::groups. #[serde(default)] keeps old AgentProfileVersion JSON snapshots (pre-227) deserializable.

NB: this binding is intentionally EXCLUDED from agent-profile version snapshot/restore — it is dispatch-routing scope (a live operational binding), not part of the profile’s behavioural definition, so a version restore does not carry or revert it (ADR 0046 RUNG 1b review).

Array<string> | null
retry_policy
required

Open retry-policy bag. Runtime stays serde_json::Value; spec-typed as an open map.

object
key
additional properties
review_required
required
boolean
script_allowlist

Issue #217 / ADR 0028 — optional slug whitelist for the script.run MCP tool. NULL means any script in the workspace is callable; a non-NULL array (including empty) is an explicit whitelist.

Array<string> | null
slug
required
string
tags
required
Array<string>
updated_at
required
string format: date-time
version
required
integer format: int32
workspace_id
required
string format: uuid
Example
[
  {
    "avatar_kind": "color",
    "effort_default": "minimal",
    "execution_mode": "normal",
    "model_policy": "manual"
  }
]