`GET /api/agent-profiles/board` — one server-paginated, filtered + sorted page of the settings agent-profiles board plus the total + the facet chips.

GET

/api/agent-profiles/board

const url = 'https://example.com/api/agent-profiles/board';
const options = {method: 'GET', headers: {cookie: 'supacloud_session=<supacloud_session>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Authorizations

cookie_auth

Parameters

Query Parameters

string

Free-text search over the name, slug or description.

execution_mode

string

execution_mode filter chip (normal | workflow; #708 who-3 retired ultracode).

sort

string

Whitelisted sort column: name | agent | mode | version. Default is the legacy enabled DESC, name ASC order.

dir

string

asc | desc (default asc).

limit

integer format: int64

offset

integer format: int64

include_facets

boolean

Recompute the facet chips (default true). The board sends false on a page/sort change since the chip counts are workspace-wide.

Responses

200

One page of agent profiles.

application/json

GET /api/agent-profiles/board body — one page of agent profiles + total + facet chips.

object

facets

One of:

null
object

null

The workspace-wide facet chips for the settings agent-profiles board.

object

by_execution_mode

required

Counts per execution mode (normal | workflow; #708 who-3 retired ultracode).

Array<object>

One filter-chip value and its count. Counts are workspace-wide (independent of the active filter — the chip totals do not shift as the user filters).

object

count

required

How many rows fall in this bucket.

integer format: int64

value

required

The bucket value (e.g. a scope, a role, a framework).

string

total

required

Total profiles (independent of the active filter).

integer format: int64

items

required

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
string

null

ADR 0045 §3.6 — the profile’s default reasoning effort (migration 208, effort_default TEXT). Canonical lowercase string (minimal | low | medium | high | max); None means “inherit the runner default”. #[serde(default)] keeps old AgentProfileVersion JSON snapshots (written before this column existed) deserializable — they default to None (a no-op). Runtime stays String; the spec narrows it to the closed canonical [sc_types::Effort] (its lowercase wire form matches this column’s DB CHECK set).

string

Allowed values: minimal low medium high max

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

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

total

required

integer format: int64

Example

{
  "items": [
    {
      "avatar_kind": "color",
      "effort_default": "minimal",
      "execution_mode": "normal",
      "model_policy": "manual"
    }
  ]
}

400

Structured client error

application/json

The canonical JSON body of every error response — the single source of truth the frontend binds to. Every AppError serializes as this exact shape, and the generated OpenAPI component ApiErrorBody (with its ErrorCode enum) is what the frontend error schema is generated from, so there is no hand-written error schema on either end.

object

code

required

Machine-readable, stable error code.

string

Allowed values: not_found unauthorized forbidden bad_request unprocessable precondition_failed conflict method_not_allowed rate_limited quota_exceeded database_error docker_error vault_error internal_error

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

401

Authentication required

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

403

Permission denied

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}

500

Structured server error

application/json

object

code

required

Machine-readable, stable error code.

string

details

One of:

null
object

null

Present only on a quota-exceeded 403 — the inline upgrade-CTA payload.

object

key

required

The entitlement feature key that was hit, e.g. apps.max_count.

string

limit

required

The plan’s limit for this key.

integer format: int64

upgrade_url

required

Where to send the user to upgrade.

string

used

required

Current usage (count or bytes, per the key).

integer format: int64

error

required

Human-readable message (the server’s English text; the client may localize by code).

string

Example

{
  "code": "not_found"
}