---
title: "List organization-shared and explicitly authorized persistent agents without fetching Git state or transcripts"
method: GET
path: "/api/v1/organizations/{organization_id}/agents"
tags: ["organizations"]
---

# List organization-shared and explicitly authorized persistent agents without fetching Git state or transcripts

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

## 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`
- Auth: HTTP bearer

## Path parameters

- `organization_id` string, required

## Query parameters

- `runtime_version` 'v1' | 'v2'
- `limit` integer
- `cursor` string
- `q` string
- `status` 'all' | 'draft' | 'active' | 'paused' | 'archived'

## Response `200`

Authorized agent roster

- object
  - `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

## Other responses

- `401`: Authentication required
- `403`: Current private-agent management authority required
- `404`: Organization or authorized agent not found
- `409`: Version or idempotency conflict; reload before starting a new operation
- `422`: Invalid configuration or operation
- `502`: Bad gateway
- `503`: Private Git state unavailable. Retry the same Idempotency-Key and unchanged body.

---

[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/74298a24e040?raw)