--- title: "GET /api/v1/organizations/{organization_id}/agents/{id}" method: GET path: "/api/v1/organizations/{organization_id}/agents/{id}" tags: ["organizations"] --- # GET /api/v1/organizations/{organization_id}/agents/{id} `GET /api/v1/organizations/{organization_id}/agents/{id}` ## 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/{id}` - Auth: HTTP bearer ## Path parameters - `organization_id` string, required - `id` string, required ## Response `200` Authorized agent settings - PersistentAgentResponse - `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. ## 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)