---
title: "Authorized custom-agent roster and selected settings for the Agents workspace"
method: GET
path: "/api/v1/organizations/{organization_id}/agents/page"
tags: ["organizations"]
---

# Authorized custom-agent roster and selected settings for the Agents workspace

`GET /api/v1/organizations/{organization_id}/agents/page`

## Request

- Base URL: `https://composal.com` (the document declares no server; this is the origin it was published from)
- URL: `https://composal.com/api/v1/organizations/{organization_id}/agents/page`
- Auth: HTTP bearer

## Path parameters

- `organization_id` string, required

## Query parameters

- `agent_view` 'conversation' | 'settings' | 'updates'
- `updates_before` string
- `agent_conversation` string
- `conversations_after` string
- `conversation_before` string
- `agent` string
- `agent_search` string
- `integration_search` string
- `work_repository_search` string
- `cursor` string
- `limit` integer

## Response `200`

Custom-agent workspace page

- PersistentAgentsWorkspacePage
  - `runtime_versions` string[]: Runtime choices authorized for this organization.
  - `model_choices` object[]
    - `provider` string, required
    - `model` string, required
    - `label` string, required
    - `available` boolean, required
    - `speeds` string[], required
    - `default_reasoning` 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max', required
    - `reasoning` string[], required
    - `cost_tier` integer, nullable: Relative usage cost from 1 (cheapest) to 4, from list prices. Null when unpriced. Absent on older API replicas.
  - `can_edit_integration_connections` boolean, required
  - `integration_choices_truncated` boolean, required
  - `integration_choices` PersistentAgentConnectionChoice[], required
    - `id` string, required
    - `name` string, required
    - `toolkit` string, required
    - `reference` string, required
    - `available` boolean, required
    - `status` string, required
  - `integration_selected` PersistentAgentConnectionChoice[], required
    - `id` string, required
    - `name` string, required
    - `toolkit` string, required
    - `reference` string, required
    - `available` boolean, required
    - `status` string, required
  - `inbox` object, nullable
    - `has_agents` boolean, required
    - `briefing` AgentBriefing
      - `schema_version` 1, required
      - `snapshot_id` string, required
      - `generated_at` string, date-time, required
      - `recap` object
        - `status` 'empty' | 'pending' | 'ready' | 'unavailable', required
        - `model` string
        - `generated_at` string, date-time
      - `window` object, required
        - `from` string, date-time, required
        - `to` string, date-time, required
        - `timezone` string, required
      - `blocks` union[], required
        - union
          - object
            - `type` 'paragraph', required
            - `content` union[], required
              - …
          - object
            - `type` 'work_previews', required
            - `collection_id` string, required
            - `title` string, required
      - `collections` object[], required
        - `id` string, required
        - `label` string, required
        - `count` integer, required
        - `work_ids` string[], required
        - `coding_summary` object: Combined completed coding outcomes at one delivery stage. Count is the total submitted items; collection count remains the number of saved results.
          - `activity` 'bug_fix' | 'test_repair', required
          - `action` string, required
          - `subject` string, required
          - `count` integer, required
      - `work` AgentWorkView[], required
        - `id` string, required
        - `revision` integer, required
        - `agent` object, required
          - `id` string, required
          - `name` string, required
        - `kind` 'finding' | 'communication' | 'deliverable' | 'generic' | 'coding', required
        - `state` 'working' | 'completed' | 'failed' | 'not_pursued', required
        - `attention` 'none' | 'exception', required
        - `title` string, required
        - `summary` string, required
        - `updated_at` string, date-time, required
        - `payload` union, required
          - AgentWorkCodeChange: Agent-reported coding work, not remote state verification or a viewer access grant. Repository must be currently selected and readable by the controlling user at publication with an exactly matching name. Item IDs and Sentry organization/issue identities must be unique. Completed work requires failing-before and passing-after verification for every item.
            - `schema_version` 1, required
            - `type` 'code_change', required
            - `evidence` AgentWorkEvidence[], required
              - …
            - `activity` 'bug_fix' | 'test_repair', required
            - `repository` object, required
              - …
            - `completed_at` string, date-time, required
            - `delivery` object, required
              - …
            - `items` object[], required
              - …
          - object
            - `schema_version` 1, required
            - `type` 'finding', required
            - `evidence` AgentWorkEvidence[], required
              - …
            - `measurement` AgentWorkMeasurement, required
              - …
          - object
            - `schema_version` 1, required
            - `type` 'message_excerpt', required
            - `evidence` AgentWorkEvidence[], required
              - …
            - `channel` 'slack' | 'email', required
            - `participants` object[], required
              - …
            - `subject` string, nullable, required
            - `text` string, required
            - `source_url` string, nullable, required
          - object
            - `schema_version` 1, required
            - `type` 'library_file', required
            - `evidence` AgentWorkEvidence[], required
              - …
            - `library_artifact_id` string, required
            - `caption` string, required
          - object
            - `schema_version` 1, required
            - `type` 'generic', required
            - `evidence` AgentWorkEvidence[], required
              - …
            - `group` object: Optional grouping of 1–20 individual results, people or changes. Each field is one item and contributes exactly one to the displayed count, not an attribute of a single result. For people, label is the person's display name and value describes their outcome. Omit group for ordinary report attributes. Action is a short past-tense verb; subject is the noun phrase agreeing with the item count; provider is a toolkit name or null. Counts are derived by Rails, never submitted.
              - …
            - `fields` object[], required
              - …
          - object
            - `schema_version` 2, required
            - `type` 'generic', required
            - `evidence` AgentWorkEvidence[], required
              - …
            - `group` object: Optional grouping of 1–20 individual results. Each field contributes one item; never repeat a Sentry organization_slug/issue_id even through different accounts. Counts are derived by Rails, never submitted.
              - …
            - `fields` object[], required
              - …
        - `group` object, nullable
          - `category` 'items' | 'people' | 'changes', required
          - `action` string, required
          - `subject` string, required
          - `provider` string, nullable, required
          - `count` integer, required
        - `surface` 'finding' | 'artifact' | 'generic' | 'coding', required
        - `attribution` 'agent_reported', required
        - `conversation_href` string, nullable, required
        - `library_files` object[], required
          - `id` string, required
          - `title` string, required
          - `content_type` string, required
          - `byte_size` integer, required
          - `download_href` string, required
          - `preview` 'image' | 'none', required
      - `truncated` boolean, required
    - `unread` PersistentAgentSummary[], required
      - `id` string, required
      - `organization_id` string, required
      - `controlling_user_id` string, required
      - `name` string, required
      - `runtime_version` 'v1' | 'v2': Immutable execution runtime selected at creation.
      - `provisioning` PersistentAgentClawderProvisioning: Safe managed-worker readiness. Creating an organization's first V2 agent starts provisioning; later agents reuse its worker. Ready requires actual placement and native readiness, not just an accepted deployment request.
        - `status` 'provisioning' | 'ready' | 'failed', required
        - `can_retry` boolean, required
        - `error` string, nullable, required: Safe user-facing failure description.
      - `preview` object, nullable
        - `text` string, required
        - `conversation_id` string, required
      - `persona` PersistentAgentPersona
        - `status` 'pending' | 'generating' | 'publishing' | 'ready' | 'failed' | 'uncertain', required
        - `generation_id` string, required
        - `colour` string, required
        - `personality` string, required
        - `can_retry` boolean, required
        - `sprite` PersistentAgentSprite
          - `schema` 1, required
          - `content_type` 'image/webp', required
          - `width` integer, required
          - `height` 260 | 390 | 520 | 1040, required
          - `sha256` string, required
          - `columns` integer, required
          - `rows` 5, required
          - `frame_width` 48 | 72 | 96 | 192, required
          - `frame_height` 52 | 78 | 104 | 208, required
          - `states` object, required
            - `idle` PersistentAgentSpriteState, required
              - …
            - `happy` PersistentAgentSpriteState, required
              - …
            - `spin` PersistentAgentSpriteState, required
              - …
            - `thinking` PersistentAgentSpriteState, required
              - …
            - `working` PersistentAgentSpriteState, required
              - …
        - `image_digest` string, nullable, required
      - `avatar` string, nullable: Emoji or up to two visible grapheme clusters, at most 64 UTF-8 bytes, without control or bidi override characters. Null selects the default icon. Omission preserves legacy configuration bytes.
      - `slug` string, required
      - `status` 'draft' | 'active' | 'paused' | 'archived', required
      - `configuration_revision` integer, required
      - `url_slug` string: Stable organization-scoped browser name for /ORG/agent/NAME. Legacy slug and public IDs remain accepted.
      - `visibility` 'private' | 'organization'
      - `sharing_version` integer
      - `sharing_fixed` boolean: Project agents have a fixed audience and cannot change visibility.
      - `can_manage_sharing` boolean
      - `can_delete` boolean: Whether this viewer may delete this v2 agent.
      - `can_manage` boolean, required
      - `has_unread_updates` boolean, required
      - `preview_received_at` string, date-time, nullable: When a newer canonical conversation preview was first projected. Older previews may be undated; this is not task completion time.
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
    - `recent` PersistentAgentSummary[], required
      - `id` string, required
      - `organization_id` string, required
      - `controlling_user_id` string, required
      - `name` string, required
      - `runtime_version` 'v1' | 'v2': Immutable execution runtime selected at creation.
      - `provisioning` PersistentAgentClawderProvisioning: Safe managed-worker readiness. Creating an organization's first V2 agent starts provisioning; later agents reuse its worker. Ready requires actual placement and native readiness, not just an accepted deployment request.
        - `status` 'provisioning' | 'ready' | 'failed', required
        - `can_retry` boolean, required
        - `error` string, nullable, required: Safe user-facing failure description.
      - `preview` object, nullable
        - `text` string, required
        - `conversation_id` string, required
      - `persona` PersistentAgentPersona
        - `status` 'pending' | 'generating' | 'publishing' | 'ready' | 'failed' | 'uncertain', required
        - `generation_id` string, required
        - `colour` string, required
        - `personality` string, required
        - `can_retry` boolean, required
        - `sprite` PersistentAgentSprite
          - `schema` 1, required
          - `content_type` 'image/webp', required
          - `width` integer, required
          - `height` 260 | 390 | 520 | 1040, required
          - `sha256` string, required
          - `columns` integer, required
          - `rows` 5, required
          - `frame_width` 48 | 72 | 96 | 192, required
          - `frame_height` 52 | 78 | 104 | 208, required
          - `states` object, required
            - `idle` PersistentAgentSpriteState, required
              - …
            - `happy` PersistentAgentSpriteState, required
              - …
            - `spin` PersistentAgentSpriteState, required
              - …
            - `thinking` PersistentAgentSpriteState, required
              - …
            - `working` PersistentAgentSpriteState, required
              - …
        - `image_digest` string, nullable, required
      - `avatar` string, nullable: Emoji or up to two visible grapheme clusters, at most 64 UTF-8 bytes, without control or bidi override characters. Null selects the default icon. Omission preserves legacy configuration bytes.
      - `slug` string, required
      - `status` 'draft' | 'active' | 'paused' | 'archived', required
      - `configuration_revision` integer, required
      - `url_slug` string: Stable organization-scoped browser name for /ORG/agent/NAME. Legacy slug and public IDs remain accepted.
      - `visibility` 'private' | 'organization'
      - `sharing_version` integer
      - `sharing_fixed` boolean: Project agents have a fixed audience and cannot change visibility.
      - `can_manage_sharing` boolean
      - `can_delete` boolean: Whether this viewer may delete this v2 agent.
      - `can_manage` boolean, required
      - `has_unread_updates` boolean, required
      - `preview_received_at` string, date-time, nullable: When a newer canonical conversation preview was first projected. Older previews may be undated; this is not task completion time.
      - `created_at` string, date-time, required
      - `updated_at` string, date-time, required
  - `updates` PersistentAgentUpdates
    - `agent_id` string, required
    - `viewer_id` string, required
    - `entries` PersistentAgentUpdate[], required
      - `sequence` integer, required
      - `task_id` string, required
      - `conversation_id` string, required
      - `status` 'completed' | 'failed' | 'cancelled' | 'blocked', required
      - `reason` string, nullable, required
      - `result` object, nullable, required
      - `unread` boolean, required
    - `next_before` integer, nullable, required
    - `read_through` integer, required
    - `can_mark_read` boolean, required
  - `platform_event_types` string[], required
  - `conversation` PersistentAgentConversation
    - `direct_chat_available` boolean: Rails-owned eligibility for a new foreground turn in this conversation. Absent on older API replicas; clients use ordinary inbox ingress.
    - `current_activity` object, nullable: Current conversation work at this response version, independent of message pagination. Optional during the additive rollout.
      - `input_id` string, required
      - `task_id` string, nullable, required
      - `state` 'queued' | 'running' | 'yielded' | 'waiting' | 'blocked' | 'completed' | 'failed' | 'cancelled' | 'requires_start' | 'paused' | 'archived', required
    - `background_updates` PersistentAgentHelper[]: Recent background results for this conversation, including parents outside the current message page. Optional during the additive API rollout.
      - `purpose` string, required
      - `status` 'registered' | 'accepted' | 'queued' | 'running' | 'yielded' | 'waiting' | 'blocked' | 'completed' | 'failed' | 'cancelled', required
      - `task_id` string, nullable, required
      - `conversation_id` string, required
      - `reason` string, nullable, required
      - `text` string, nullable, required
      - `truncated` boolean, required
      - `can_open_conversation` boolean: True after canonical helper input publication; omitted by older servers.
    - `task_control` PersistentAgentTaskControl, required
      - `task_id` string, required
      - `can_stop` boolean, required
      - `stop_requested` boolean, required
    - `pending_approval` PersistentAgentPendingApproval, required
      - `task_id` string, required
      - `wait_id` string, required
      - `tool` string, required
      - `arguments` object, required
      - `resource` object, required
        - `id` string, required
        - `version` string, required
      - `expires_at` string, date-time, required
      - `version` union, required: A displayed runtime position. The server selects the backend and validates the agent, epoch and bounded SQL ordinal.
        - string
        - string
      - `can_decide` boolean, required
    - `pending_question` PersistentAgentPendingQuestion, required
      - `task_id` string, required
      - `wait_id` string, required
      - `question` string, required
      - `expires_at` string, date-time, required
      - `can_reply` boolean, required
    - `conversations` PersistentAgentConversationDirectory, required
      - `next_after` string, nullable, required
      - `items` object[], required
        - `id` string, required
        - `label` string, required
    - `conversation_id` string, required
    - `version` string, nullable, required
    - `next_before` string, nullable, required
    - `can_send` boolean, required
    - `send_action` 'send' | 'activate_and_send' | 'null', nullable, required
    - `inputs` object[], required
      - `input` PersistentAgentInput, required
        - `author` object
          - `id` string, required
          - `name` string, required
        - `id` string, required
        - `conversation_id` string, required
        - `status` 'published', required
        - `version` string, required
        - `message` union, required
          - PersistentAgentOrdinaryMessage
            - `schema` 1 | 2, required
            - `id` string, required
            - `kind` 'message', required
            - `agent_id` string, required
            - `actor_user_id` string, required
            - `accepted_at` string, date-time, required
            - `operation_key` string, required
            - `conversation_id` string, required
            - `text` string, required
            - `mode` 'steer' | 'follow_up', required
          - PersistentAgentQuestionReplyMessage
            - `schema` 3, required
            - `id` string, required
            - `kind` 'message', required
            - `agent_id` string, required
            - `actor_user_id` string, required
            - `accepted_at` string, date-time, required
            - `operation_key` string, required
            - `conversation_id` string, required
            - `text` string, required
            - `mode` 'steer', required
            - `reply_to` object, required
              - …
      - `task` object, nullable, required
        - `helpers` PersistentAgentHelper[]: Background work associated with this turn. Optional during the additive rollout to older API replicas.
          - `purpose` string, required
          - `status` 'registered' | 'accepted' | 'queued' | 'running' | 'yielded' | 'waiting' | 'blocked' | 'completed' | 'failed' | 'cancelled', required
          - `task_id` string, nullable, required
          - `conversation_id` string, required
          - `reason` string, nullable, required
          - `text` string, nullable, required
          - `truncated` boolean, required
          - `can_open_conversation` boolean: True after canonical helper input publication; omitted by older servers.
        - `id` string, required
        - `status` 'queued' | 'running' | 'yielded' | 'waiting' | 'blocked' | 'completed' | 'failed' | 'cancelled', required
        - `reason` string, nullable, required
        - `result` object, nullable, required
  - `agents` PersistentAgentSummary[], required
    - `id` string, required
    - `organization_id` string, required
    - `controlling_user_id` string, required
    - `name` string, required
    - `runtime_version` 'v1' | 'v2': Immutable execution runtime selected at creation.
    - `provisioning` PersistentAgentClawderProvisioning: Safe managed-worker readiness. Creating an organization's first V2 agent starts provisioning; later agents reuse its worker. Ready requires actual placement and native readiness, not just an accepted deployment request.
      - `status` 'provisioning' | 'ready' | 'failed', required
      - `can_retry` boolean, required
      - `error` string, nullable, required: Safe user-facing failure description.
    - `preview` object, nullable
      - `text` string, required
      - `conversation_id` string, required
    - `persona` PersistentAgentPersona
      - `status` 'pending' | 'generating' | 'publishing' | 'ready' | 'failed' | 'uncertain', required
      - `generation_id` string, required
      - `colour` string, required
      - `personality` string, required
      - `can_retry` boolean, required
      - `sprite` PersistentAgentSprite
        - `schema` 1, required
        - `content_type` 'image/webp', required
        - `width` integer, required
        - `height` 260 | 390 | 520 | 1040, required
        - `sha256` string, required
        - `columns` integer, required
        - `rows` 5, required
        - `frame_width` 48 | 72 | 96 | 192, required
        - `frame_height` 52 | 78 | 104 | 208, required
        - `states` object, required
          - `idle` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `happy` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `spin` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `thinking` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `working` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
      - `image_digest` string, nullable, required
    - `avatar` string, nullable: Emoji or up to two visible grapheme clusters, at most 64 UTF-8 bytes, without control or bidi override characters. Null selects the default icon. Omission preserves legacy configuration bytes.
    - `slug` string, required
    - `status` 'draft' | 'active' | 'paused' | 'archived', required
    - `configuration_revision` integer, required
    - `url_slug` string: Stable organization-scoped browser name for /ORG/agent/NAME. Legacy slug and public IDs remain accepted.
    - `visibility` 'private' | 'organization'
    - `sharing_version` integer
    - `sharing_fixed` boolean: Project agents have a fixed audience and cannot change visibility.
    - `can_manage_sharing` boolean
    - `can_delete` boolean: Whether this viewer may delete this v2 agent.
    - `can_manage` boolean, required
    - `has_unread_updates` boolean, required
    - `preview_received_at` string, date-time, nullable: When a newer canonical conversation preview was first projected. Older previews may be undated; this is not task completion time.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `pagination` PersistentAgentPagination, required
    - `limit` integer, required
    - `next` string, nullable
  - `creation_enabled` boolean, required
  - `selected_agent` PersistentAgentDetail, required
    - `id` string, required
    - `organization_id` string, required
    - `controlling_user_id` string, required
    - `name` string, required
    - `runtime_version` 'v1' | 'v2': Immutable execution runtime selected at creation.
    - `provisioning` PersistentAgentClawderProvisioning: Safe managed-worker readiness. Creating an organization's first V2 agent starts provisioning; later agents reuse its worker. Ready requires actual placement and native readiness, not just an accepted deployment request.
      - `status` 'provisioning' | 'ready' | 'failed', required
      - `can_retry` boolean, required
      - `error` string, nullable, required: Safe user-facing failure description.
    - `preview` object, nullable
      - `text` string, required
      - `conversation_id` string, required
    - `persona` PersistentAgentPersona
      - `status` 'pending' | 'generating' | 'publishing' | 'ready' | 'failed' | 'uncertain', required
      - `generation_id` string, required
      - `colour` string, required
      - `personality` string, required
      - `can_retry` boolean, required
      - `sprite` PersistentAgentSprite
        - `schema` 1, required
        - `content_type` 'image/webp', required
        - `width` integer, required
        - `height` 260 | 390 | 520 | 1040, required
        - `sha256` string, required
        - `columns` integer, required
        - `rows` 5, required
        - `frame_width` 48 | 72 | 96 | 192, required
        - `frame_height` 52 | 78 | 104 | 208, required
        - `states` object, required
          - `idle` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `happy` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `spin` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `thinking` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `working` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
      - `image_digest` string, nullable, required
    - `avatar` string, nullable: Emoji or up to two visible grapheme clusters, at most 64 UTF-8 bytes, without control or bidi override characters. Null selects the default icon. Omission preserves legacy configuration bytes.
    - `slug` string, required
    - `status` 'draft' | 'active' | 'paused' | 'archived', required
    - `configuration_revision` integer, required
    - `url_slug` string: Stable organization-scoped browser name for /ORG/agent/NAME. Legacy slug and public IDs remain accepted.
    - `visibility` 'private' | 'organization'
    - `sharing_version` integer
    - `sharing_fixed` boolean: Project agents have a fixed audience and cannot change visibility.
    - `can_manage_sharing` boolean
    - `can_delete` boolean: Whether this viewer may delete this v2 agent.
    - `can_manage` boolean, required
    - `has_unread_updates` boolean, required
    - `preview_received_at` string, date-time, nullable: When a newer canonical conversation preview was first projected. Older previews may be undated; this is not task completion time.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
    - `configuration` PersistentAgentSavedConfiguration, required
      - `avatar` string, nullable: Emoji or up to two visible grapheme clusters, at most 64 UTF-8 bytes, without control or bidi override characters. Null selects the default icon. Omission preserves legacy configuration bytes.
      - `instructions` string, required
      - `work_repositories` PersistentAgentWorkRepository[], required
        - `repository_id` string, required
        - `permission` 'read' | 'write', required
        - `write_branches` string[]: Exact branches allowed for writes. Empty or omitted allows all branches, subject to exclude_default_branch and normal repository protections.
        - `exclude_default_branch` boolean: With write permission, exclude the current default branch. Defaults to false.
      - `skills` AutomationSkillReference[], required
        - `repository_id` string, required
        - `revision` string, required: Original immutable Git commit SHA.
        - `path` string, required
        - `sha256` string, required
        - `files` AutomationSkillFile[]
          - `path` string, required
          - `sha256` string, required
      - `tools` string[], required
      - `connection_grants` string[], required: Selected app-account references, pinned as agent_connection_ID:GENERATION. Saving selects full tool access for that account; credentials remain in the provider vault.
      - `trigger_bindings` union[], required
        - union
          - string
          - PersistentAgentScheduleBinding
            - `id` string, required
            - `type` 'schedule', required
            - `schedule` union, required
              - …
            - `timezone` string, required: Explicit IANA time zone, matching the cron zone when applicable.
            - `grace_seconds` integer, required: Explicit late one-shot grace. Recurring downtime coalesces to one occurrence; resume skips the unclaimed backlog through its saved boundary.
            - `text` string, required
            - `conversation_id` string, required
          - PersistentAgentWebhookBinding: Saved webhook draft. Endpoint consent and ingress adapters are not yet qualified for activation.
            - `type` 'webhook', required
            - `id` string, required
            - `endpoint_id` string, required: Non-secret server-owned endpoint reference; never grants authority.
            - `conversation_id` string, required
            - `text` string, required
            - `event_types` string[], required
            - `max_events_per_day` integer, required
          - PersistentAgentPlatformEventBinding
            - `type` 'platform_event', required
            - `id` string, required
            - `repository_id` string, required
            - `event_types` string[], required
            - `max_events_per_day` integer, required
            - `conversation_id` string, required
            - `text` string, required
          - PersistentAgentProviderEventBinding: Saved provider source draft. Owner consent is separate and the receiving adapter remains unavailable for activation.
            - `type` 'provider_event', required
            - `id` string, required
            - `subscription_id` string, required
            - `max_events_per_day` integer, required
            - `conversation_id` string, required
            - `text` string, required
      - `destinations` string[], required
      - `timezone` string, required: IANA time zone identifier; default UTC.
      - `wake_policy` PersistentAgentWakePolicy: Event suppression before task admission. Exact ignored types run first. Where semantic relevance screening is enabled, subscribed external events are compared with the agent's instructions and subscription purpose. Human messages, replies, routines and helpers bypass screening. Omission preserves historical configuration bytes.
        - `ignored_event_types` string[], required
        - `relevance` boolean: Defaults to true when omitted. False opts this agent out of semantic screening of its subscribed external events; it does not change event subscriptions or resource authority.
      - `model_policy` union, required
        - object
          - `mode` 'platform_default', required
        - object
          - `provider` string, required
          - `model` string, required
          - `reasoning` 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
      - `budgets` object, required
        - `daily_cents` integer, required
        - `task_tokens` integer, required
        - `task_compute_seconds` integer, required
        - `task_deadline_seconds` integer, required
        - `max_concurrent_tasks` integer, required
      - `memory` object, required
        - `enabled` boolean, required
        - `max_bytes` integer, required
    - `configuration_version` string, nullable, required: Opaque version token. Echo the version returned by the server; null denotes an empty stream.
    - `lifecycle_version` string, nullable, required: Opaque version token. Echo the version returned by the server; null denotes an empty stream.
    - `direct_chat_available` boolean: Advisory availability of direct V1 chat. The chat endpoint rechecks current authority.
    - `model_change_action` 'save' | 'apply' | 'null', nullable: Advisory composer action. Save retains lifecycle state; apply offers a guarded model-only activation that rechecks unfinished tasks and accepted helpers at publication. Null means model settings are unavailable.
    - `lifecycle_actions` string[], required: Currently authorized lifecycle actions for the saved revision and observed state. Publication rechecks current authority and the expected version.
    - `setup_pending` boolean, required
    - `can_edit_configuration` boolean, required
    - `can_reconcile_save` boolean, required: May reconcile an identical previously accepted save; this does not authorize new configuration edits.
  - `pinned_agent` PersistentAgentSummary, required
    - `id` string, required
    - `organization_id` string, required
    - `controlling_user_id` string, required
    - `name` string, required
    - `runtime_version` 'v1' | 'v2': Immutable execution runtime selected at creation.
    - `provisioning` PersistentAgentClawderProvisioning: Safe managed-worker readiness. Creating an organization's first V2 agent starts provisioning; later agents reuse its worker. Ready requires actual placement and native readiness, not just an accepted deployment request.
      - `status` 'provisioning' | 'ready' | 'failed', required
      - `can_retry` boolean, required
      - `error` string, nullable, required: Safe user-facing failure description.
    - `preview` object, nullable
      - `text` string, required
      - `conversation_id` string, required
    - `persona` PersistentAgentPersona
      - `status` 'pending' | 'generating' | 'publishing' | 'ready' | 'failed' | 'uncertain', required
      - `generation_id` string, required
      - `colour` string, required
      - `personality` string, required
      - `can_retry` boolean, required
      - `sprite` PersistentAgentSprite
        - `schema` 1, required
        - `content_type` 'image/webp', required
        - `width` integer, required
        - `height` 260 | 390 | 520 | 1040, required
        - `sha256` string, required
        - `columns` integer, required
        - `rows` 5, required
        - `frame_width` 48 | 72 | 96 | 192, required
        - `frame_height` 52 | 78 | 104 | 208, required
        - `states` object, required
          - `idle` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `happy` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `spin` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `thinking` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
          - `working` PersistentAgentSpriteState, required
            - `row` integer, required
            - `frames` integer, required
            - `duration_ms` number, required: Duration of each frame in milliseconds; interpolated states use 1000/24
      - `image_digest` string, nullable, required
    - `avatar` string, nullable: Emoji or up to two visible grapheme clusters, at most 64 UTF-8 bytes, without control or bidi override characters. Null selects the default icon. Omission preserves legacy configuration bytes.
    - `slug` string, required
    - `status` 'draft' | 'active' | 'paused' | 'archived', required
    - `configuration_revision` integer, required
    - `url_slug` string: Stable organization-scoped browser name for /ORG/agent/NAME. Legacy slug and public IDs remain accepted.
    - `visibility` 'private' | 'organization'
    - `sharing_version` integer
    - `sharing_fixed` boolean: Project agents have a fixed audience and cannot change visibility.
    - `can_manage_sharing` boolean
    - `can_delete` boolean: Whether this viewer may delete this v2 agent.
    - `can_manage` boolean, required
    - `has_unread_updates` boolean, required
    - `preview_received_at` string, date-time, nullable: When a newer canonical conversation preview was first projected. Older previews may be undated; this is not task completion time.
    - `created_at` string, date-time, required
    - `updated_at` string, date-time, required
  - `new_configuration` PersistentAgentSavedConfiguration, required
    - `avatar` string, nullable: Emoji or up to two visible grapheme clusters, at most 64 UTF-8 bytes, without control or bidi override characters. Null selects the default icon. Omission preserves legacy configuration bytes.
    - `instructions` string, required
    - `work_repositories` PersistentAgentWorkRepository[], required
      - `repository_id` string, required
      - `permission` 'read' | 'write', required
      - `write_branches` string[]: Exact branches allowed for writes. Empty or omitted allows all branches, subject to exclude_default_branch and normal repository protections.
      - `exclude_default_branch` boolean: With write permission, exclude the current default branch. Defaults to false.
    - `skills` AutomationSkillReference[], required
      - `repository_id` string, required
      - `revision` string, required: Original immutable Git commit SHA.
      - `path` string, required
      - `sha256` string, required
      - `files` AutomationSkillFile[]
        - `path` string, required
        - `sha256` string, required
    - `tools` string[], required
    - `connection_grants` string[], required: Selected app-account references, pinned as agent_connection_ID:GENERATION. Saving selects full tool access for that account; credentials remain in the provider vault.
    - `trigger_bindings` union[], required
      - union
        - string
        - PersistentAgentScheduleBinding
          - `id` string, required
          - `type` 'schedule', required
          - `schedule` union, required
            - object
              - …
            - object
              - …
            - object
              - …
          - `timezone` string, required: Explicit IANA time zone, matching the cron zone when applicable.
          - `grace_seconds` integer, required: Explicit late one-shot grace. Recurring downtime coalesces to one occurrence; resume skips the unclaimed backlog through its saved boundary.
          - `text` string, required
          - `conversation_id` string, required
        - PersistentAgentWebhookBinding: Saved webhook draft. Endpoint consent and ingress adapters are not yet qualified for activation.
          - `type` 'webhook', required
          - `id` string, required
          - `endpoint_id` string, required: Non-secret server-owned endpoint reference; never grants authority.
          - `conversation_id` string, required
          - `text` string, required
          - `event_types` string[], required
          - `max_events_per_day` integer, required
        - PersistentAgentPlatformEventBinding
          - `type` 'platform_event', required
          - `id` string, required
          - `repository_id` string, required
          - `event_types` string[], required
          - `max_events_per_day` integer, required
          - `conversation_id` string, required
          - `text` string, required
        - PersistentAgentProviderEventBinding: Saved provider source draft. Owner consent is separate and the receiving adapter remains unavailable for activation.
          - `type` 'provider_event', required
          - `id` string, required
          - `subscription_id` string, required
          - `max_events_per_day` integer, required
          - `conversation_id` string, required
          - `text` string, required
    - `destinations` string[], required
    - `timezone` string, required: IANA time zone identifier; default UTC.
    - `wake_policy` PersistentAgentWakePolicy: Event suppression before task admission. Exact ignored types run first. Where semantic relevance screening is enabled, subscribed external events are compared with the agent's instructions and subscription purpose. Human messages, replies, routines and helpers bypass screening. Omission preserves historical configuration bytes.
      - `ignored_event_types` string[], required
      - `relevance` boolean: Defaults to true when omitted. False opts this agent out of semantic screening of its subscribed external events; it does not change event subscriptions or resource authority.
    - `model_policy` union, required
      - object
        - `mode` 'platform_default', required
      - object
        - `provider` string, required
        - `model` string, required
        - `reasoning` 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
    - `budgets` object, required
      - `daily_cents` integer, required
      - `task_tokens` integer, required
      - `task_compute_seconds` integer, required
      - `task_deadline_seconds` integer, required
      - `max_concurrent_tasks` integer, required
    - `memory` object, required
      - `enabled` boolean, required
      - `max_bytes` integer, required
  - `repository_choices` PersistentAgentRepositoryChoice[], required
    - `id` string, required
    - `name` string, nullable, required
    - `slug` string, nullable, required
    - `available` boolean, required
  - `repository_choices_truncated` boolean, required
  - `organization_id` string, required
  - `selected_reference` string, nullable, required
  - `viewer_id` string, required

## Other responses

- `401`: Authentication required
- `403`: Forbidden
- `404`: Organization or selected authorized agent unavailable
- `422`: Unprocessable entity
- `502`: Bad gateway
- `503`: Selected private agent state temporarily unavailable

---

[API](https://skmtc.dev/composal/apis/vex-api.md) - [All operations](https://skmtc.dev/composal/apis/vex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/composal/apis/vex-api/revisions/19698ba051dc?raw)