Agent API
Use the organization-scoped HTTP API to create, configure and message persistent agents, retrieve replies and manage lifecycle and triggers.
Contents
Use the versioned HTTP API directly from your application. The OpenAPI document is the canonical source for request schemas, response fields and operation IDs. Generate a client from it if you need types; the planned composalai/agent-sdk is not required and is not available yet.
Manage sharing
Creation accepts optional visibility: "private"; the default is "organization". Read agent.visibility and agent.sharing_version from the agent response. An owner or manager can change sharing with:
PATCH /api/v1/organizations/acme/agents/AGENT/sharing
Content-Type: application/json
Authorization: Bearer YOUR_TOKEN
{"expected_version": 7, "visibility": "organization"}
Echo the current integer sharing_version as expected_version; it is independent of native settings versions. A stale version returns 409. After a timeout, GET the agent to confirm its audience before submitting another change. This endpoint does not use an idempotency key. An organization member cannot change sharing or configuration simply because they can message the agent. Membership removal or switching to private revokes ungranted access and prevents further task execution for that requester.
Shared messages use the owner's configured tools and selected accounts. Only the owner can edit account grants. Provider-event consent includes the audience; visibility changes can require the owner to renew that consent. Organization sharing includes future members; membership is checked live for access.
Authenticate and select an agent
Send a Composal personal access token in Authorization: Bearer …. The token acts as its user, within that user's organization membership and agent access. New agents default to organization sharing: members can view and message them, while only the owner and explicit managers can change settings. Private agents require an explicit grant even for organization administrators. Existing agents also become organization-shared at rollout; owners/managers can switch them to private afterward.
The base collection is:
https://composal.ai/api/v1/organizations/{organization_id}/agents
organization_id accepts an accessible organization slug or public ID. An agent selector accepts its readable url_slug, legacy slug or agent_… public ID. Browser links use /{organization}/agent/{url_slug}; aliases are reserved within that organization and stay stable when the display name changes. Save returned public IDs in your integration. Agent and run identifiers are opaque values, not SQL IDs.
Use /spark for runtime endpoints. Existing clients and saved Library links can still use the deprecated /clawder paths.
For a live agent list, GET $BASE/page/roster returns agents, pinned_agent, pagination and creation_enabled without loading editor choices or a conversation. Supply agent to keep the selected agent visible outside the current search or page, agent_search to filter, and cursor to continue pagination.
The examples below use Bash, curl and jq. Load COMPOSAL_API_TOKEN through your secret manager. This helper passes the token through stdin rather than a command-line argument; do not enable shell tracing around credentials.
export ORG=your-organization
export BASE="https://composal.ai/api/v1/organizations/$ORG/agents"
api() {
curl --fail-with-body --silent --show-error --config - "$@" <<EOF
header = "Authorization: Bearer ${COMPOSAL_API_TOKEN:?Set COMPOSAL_API_TOKEN}"
header = "Content-Type: application/json"
EOF
}
Create an agent
Create an agent using a name and configuration. A slug is generated automatically. Choose a stable idempotency key for this creation and retain the exact request file until its outcome is known.
cat > create-agent.json <<'JSON'
{"name":"Research assistant","configuration":{"instructions":"Research the topics I send and report your sources."}}
JSON
api "$BASE" --request POST \
--header 'Idempotency-Key: research-agent-create-001' \
--data-binary @create-agent.json > created-agent.json
export AGENT="$(jq -r '.agent.id' created-agent.json)"
api "$BASE/$AGENT" > agent.json
Creation saves the agent as a draft and queues provisioning. The draft stays visible while the Enterprise runtime starts. Inspect the returned setup state and follow the agent with GET until it is ready. Reuse the same creation key and body after an uncertain response.
Customize an avatar
New agents default to the animated pixel style on desktop and web. The original sphere is available as dither. They look toward your pointer and greet hover or focus with hops, spins, pops, and dances. Pressing their controls sends them on a quick run-off-and-return. Thinking characters ponder and bob; working characters bounce with a quicker rhythm. A smaller version appears beside the chat's thinking or working text. Characters keep the same appearance across clients; regenerating a published pixel avatar gives it a fresh seed. Explicit custom portraits and emoji remain available. Characters stay still when your system reduces motion or your organization uses still avatars.
GET $BASE/$AGENT/avatar/configuration?style_catalog=2 returns the current persona, eight styles, saved visual preferences, and can_generate / can_edit capabilities. Styles are pixel, dither, chibi, anime, globby, emoji, animal, and dino. Choose Pixel under Customize avatar on desktop or web to preview and save a shape, color, and accessory. Auto picks a value from the character’s seed. The pixel style’s optional pixel object accepts shape, palette, and topping and ignores description. The saved configuration returns pixel with its seed, and the agent persona includes it once the change is ready. Owners and managers of V2 agents can request a change:
POST /api/v1/organizations/acme/agents/AGENT/avatar/generate?style_catalog=2
Content-Type: application/json
Idempotency-Key: avatar-dino-001
{"expected_generation":"CURRENT_64_CHARACTER_GENERATION_ID","mode":"edit","style":"dino","description":"A curious purple pal"}
Copy expected_generation from persona.generation_id. description is optional and accepts up to 1,200 characters. edit uses the published character as a reference; new creates a fresh character. The response contains the updated configuration. Generation is asynchronous and retains the published image until the replacement is ready. A stale generation returns 409; invalid styles return 422. After uncertain delivery, replay the exact body and idempotency key.
For an explicit retry of a failed or uncertain generation, POST $BASE/$AGENT/avatar/retry with expected_generation and a stable Idempotency-Key. This resumes saved work and returns the avatar configuration. Fetch published images through the authenticated GET $BASE/$AGENT/avatar?version=IMAGE_DIGEST route; add asset=sprite and use the sprite's digest for its animation sheet. The built-in agent avatar tool can read, generate, and retry its own character. Use the avatar dialog or the HTTP API to set Pixel options.
Send work and read replies
For a V2 agent, open GET $BASE/$AGENT/spark/events?conversation_id=main with the same authentication as other agent requests. The response is text/event-stream: an initial snapshot contains saved messages and current run state, followed by live delta, committed message, and terminal run events. Named payload schemas are in the OpenAPI document. Reconnect to receive a fresh snapshot after an interruption. A renew event means the server is about to end the stream on purpose; reconnect at once instead of backing off. Browser clients can use a signed-in session with EventSource; API clients use their bearer token. Submit V2 messages to POST $BASE/$AGENT/spark/inputs with conversation_id, text, and a stable Idempotency-Key. Keep accepted runs and live text visible until saved messages replace them; a terminal event can arrive before its history commit.
When someone who can send opens a conversation, POST $BASE/$AGENT/spark/warm with its conversation_id so the agent prepares before their first message. It returns HTTP 202, calls no model and adds nothing to the conversation.
Ordinary V2 inputs return HTTP 202 with a run_id. An immediate /stop control instead returns HTTP 200 with status: "completed", aborted, aborted_run_ids and an optional warning. It creates no new run and has no run_id. Clear the command’s pending input, keep other runs visible, and observe the affected runs through history or events until their terminal status arrives. A warning can indicate that remote work is still stopping. After an uncertain control response, check existing run state; do not automatically replay the control.
List a V2 agent’s native conversations with GET $BASE/$AGENT/spark/threads; use the returned next_cursor for another page. Owners and managers can create a thread with POST to that path, an optional title and a stable Idempotency-Key. Use the returned opaque thread id as conversation_id for history, streaming and messages. POST $BASE/$AGENT/spark/threads/$THREAD/compact requests native compaction of an idle thread; its receipt distinguishes completed from unchanged. If compaction fails, the API returns 409 with code compaction_failed. Send an empty JSON object for that request.
GET $BASE/$AGENT/spark/lifecycle reports the proactive schedule, memory search and compaction settings. Owners and managers can enable or disable the native proactive check with POST to the same path and { "heartbeat_enabled": true } or false. These endpoints retain the agent’s existing access rules and are available for native agents.
GET $BASE/$AGENT/spark/routines lists the agent’s scheduled routines, including disabled routines and its heartbeat. Follow next_cursor to read another page. Each row includes its schedule, next run, and last result. Owners and managers can send { "enabled": false } or true to POST $BASE/$AGENT/spark/routines/$ROUTINE to pause or enable that routine. For a heartbeat with utility_model settings, send { "utility_model": "<option id>" } or { "utility_model": null } to use Automatic. The response reports can_manage. Routine IDs belong to a single agent.
GET $BASE/$AGENT/spark/library lists published files with Pagy pagination metadata. Pass its next value as cursor to read another page. Download one with GET $BASE/$AGENT/spark/library/$ARTIFACT/download using the same authentication. These downloads check the agent’s current audience and return attachments; bucket credentials and public storage URLs are never returned. The agent publishes outputs with its native library_publish tool, using text, base64 content, or a path in its assigned Blaxel workspace.
main is the default conversation. Supply another identifier to keep separate work in a different conversation. Sending creates an input; the response is not the agent's answer.
cat > message.json <<'JSON'
{"conversation_id":"main","text":"Describe your instructions and the tools available to you."}
JSON
api "$BASE/$AGENT/spark/inputs" --request POST \
--header 'Idempotency-Key: research-message-001' \
--data-binary @message.json
api "$BASE/$AGENT/spark?conversation_id=main" > conversation.json
Use streaming events to observe replies and run status. Reload native history after reconnecting; acceptance alone does not mean the run completed.
Configuration and versions
Read and update native settings through GET and PATCH /{id}/spark/settings. Echo the returned opaque version as expected_version when changing instructions. Configure repositories, integrations, routines and model policy through the corresponding native endpoints in the OpenAPI document, or ask the agent in chat. A stale version returns 409; reload before preparing a new edit.
Endpoint reference
| Method | Path | Purpose |
|---|---|---|
| GET / POST | / | List or create agents |
| GET / DELETE | /{id} | Inspect or delete an agent |
| PATCH | /{id}/sharing | Change private/team visibility |
| GET / PATCH | /{id}/spark/settings | Read or update settings |
| POST | /{id}/spark/inputs | Send a message |
| GET | /{id}/spark | Read saved conversation history |
| GET | /{id}/spark/events | Stream live events |
| GET | /{id}/spark/routines | Inspect scheduled work |
Apps and incoming events
Configure accounts and custom MCP servers through the native agent's Apps and MCPs settings. GitHub platform events reach only agents with matching authorized repository subscriptions. Agents can manage subscriptions through their native tools. Provider signatures, account authorization, relevance routing and duplicate suppression apply before delivery.
Errors and retries
- 401 / 403 / 404: authenticate again or check the user's current access. Private agent selection can return 404 rather than disclose its existence.
- 409: state changed or requires reconciliation. For a definite version conflict, reload and make a new decision with a new key. An unknown external effect is not permission to submit it again.
- 422: fix the request using returned validation errors. A changed request needs a new key.
- 429 / 503: follow
Retry-Afterand use bounded retries. Preserve the same key, body and expected versions for the same intended mutation. - Network timeout: acceptance is uncertain. Keep the original request/key and reconcile or retry that exact operation. Never generate a new key automatically.
Task failure is reported in conversation/outcome data even when its GET succeeds. A 201 message receipt, successful HTTP response or running worker does not prove the task completed. Stopping a task does not undo effects already started; uncertain usage and effects can remain under reconciliation.
V2 work repositories and GitHub
Read GET $BASE/$AGENT/spark/repositories to obtain work_repositories and the current version. Owners and managers replace the selection with PUT to the same URL:
{
"expected_version": 0,
"work_repositories": [
{ "repository_id": "repo_EXAMPLE", "permission": "write", "write_branches": [] }
]
}
Use the actual repository ID and the version returned by GET. A concurrent settings change returns 409; read the latest selection before submitting a replacement. An empty array revokes all repository access. V2 creation also accepts configuration.work_repositories. Repository grants require current membership and an active repository in the agent’s organization.
The V2 agent exposes work_repositories_list, github_cli, github_subscriptions_list, github_subscribe and github_unsubscribe. github_cli uses the same repository-scoped GitHub App authorization as V1; credentials remain on the platform. It accepts a repository ID, HTTP method, repository-relative API path and JSON body. For example, POST pulls creates a PR with title, head, base, body and optional draft. Composal prepends a black identity card with the agent’s name and character, linked to its conversation. PR description edits through github_cli retain the original author’s signed card, including edits through the Issues API. The image is visible to PR viewers; opening the conversation requires Composal access. Sandbox Git credentials can push authorized branches and read PRs and issues; use github_cli for PR and issue writes so the agent identity is attached. GitHub’s Git APIs can create commits and refs; the tool does not provide a local Git checkout. Read grants reject writes. For write grants, write_branches: [] means all branches; exclude_default_branch: true instead excludes the current default branch and cannot be combined with an exact branch list. Branch restrictions permit explicit-branch file and ref writes through github_cli; sandbox Git credentials remain read-only, and automated merges and PR branch updates are disabled. The exclusion checks GitHub’s default branch before dispatch and fails closed when it cannot be confirmed.
Ask the agent to subscribe to the GitHub events needed for its role. A subscription contains a unique id, selected repository_id, exact event_types (for example github.pull_request and github.issue_comment), conversation_id (usually main), purpose text, and max_events_per_day from 1 to 1000. Repeating an identical subscription is safe. Unsubscribing retires that ID permanently; use a new ID for a replacement. Events are admitted only from the subscription’s creation time, use stable native input keys across delivery retries, and are checked against current repository and agent authority before dispatch. Events past a subscription’s daily limit are skipped and show as over_limit in event history, so the next day starts with new events. Integration events and their GitHub webhook types must be enabled on the platform.
V2 agent workspace
The agent workspace uses the current organization's V2 agent authorization. Read access allows viewing subagents, computer state, frames and process names. Starting a computer requires permission to manage the agent.
GET /api/v1/organizations/:organization/agents/:agent/spark/subagents?conversation_id=main
GET /api/v1/organizations/:organization/agents/:agent/spark/computer
POST /api/v1/organizations/:organization/agents/:agent/spark/computer/start
GET /api/v1/organizations/:organization/agents/:agent/spark/computer/frame
The subagent response contains native child sessions for the selected conversation and an optional next_cursor. Pass it as cursor for older children. Titles are native names or task titles, rather than list positions.
Send an empty JSON object when starting a computer. The accepted response reports starting; read the computer endpoint until it reports ready. Its response also includes can_start and projected process names and statuses. Frames return JPEG bytes. These endpoints require a compatible worker bridge; opening a panel never creates a missing sandbox.
Agent marketplace
Marketplace listings are published copies of a V2 agent's instructions, memories, skills and required apps. The catalog returns public listings and your organization's own listings; scope=mine keeps only your organization's, scope=composal keeps only the listings Composal maintains (from_composal: true, published by "Composal"), and q and category narrow the results. Without filters the response leads with a composal section before the category sections. Each listing has a permanent slug (its address is /marketplace/<slug>); the listing endpoints accept the slug or the public id, and explainer holds the listing's optional Markdown write-up.
GET /api/v1/organizations/:organization/agent_marketplace?category=engineering
GET /api/v1/organizations/:organization/agent_marketplace/:listing
GET /api/v1/organizations/:organization/agent_marketplace/draft?agent_id=:agent
POST /api/v1/organizations/:organization/agent_marketplace
PATCH /api/v1/organizations/:organization/agent_marketplace/:listing
DELETE /api/v1/organizations/:organization/agent_marketplace/:listing
POST /api/v1/organizations/:organization/agent_marketplace/:listing/install
GET /api/v1/organizations/:organization/agent_marketplace/shared/:share_token
POST /api/v1/organizations/:organization/agent_marketplace/shared/:share_token/install
Publish with name, summary, category, optional visibility (organization, link or public), optional source_agent_id, and a bundle of instructions, memories (up to 50 strings), skills (up to 20 objects with a lowercase name, description and body) and integrations (up to 10 objects with a toolkit and reason). Publishing from an agent requires permission to manage it. Only the publisher and organization administrators can update or remove a listing; send the listing's version as expected_version when updating, or receive 409.
The draft also returns page_app_choices: owned Composal Pages with a prepared template revision, or available: false when preparation is needed. To bundle up to five apps, pass bundle.page_apps as { source_site_id, revision } references from those choices. The server verifies ownership and pins the reviewed code. Listing details expose page_apps summaries and counts.apps includes both Page apps and external requirements; code, private blob references and running publisher URLs are excluded. Installs deploy fresh organization apps with empty storage and no secret values before runtime work starts. Existing installs keep their pinned revision.
Install requires an Idempotency-Key header. It creates a private V2 agent in the organization in the path and returns install.agent with its id and url_slug; retrying with the same key returns the same agent. share_token is returned only to people who can manage a listing. A token for a link listing works from any organization; for an organization listing it works only for that organization's members. Removed listings return 404.
Public listings can also be read without authentication. These endpoints back composal.com/marketplace and accept the same q, category, scope and page parameters. Signed out, the catalog and :listing never return organization or link listings, a share token opens link and public listings only, share_token is always null and no app is reported as connected. With a browser session whose active organization has agents on, they answer as that organization, as the organization endpoints do. Every response, including 404, carries viewer with signed_in and the organization (slug, name) read for, or null. Listings include publisher_avatar_url: the publisher's own profile picture, or null. Installing still needs a signed-in organization.
GET /api/v1/agent_marketplace?category=engineering
GET /api/v1/agent_marketplace/:listing
GET /api/v1/agent_marketplace/shared/:share_token
GitHub subscriptions support optional structured filters: workflow_names,
workflow_paths, check_names, branches, refs, conclusions, pr_authors,
sender_logins, and labels. Each field accepts 1–30 exact string alternatives;
all supplied fields must match. branches uses the source/head branch, including
PR head branches; refs matches the supplied ref exactly. Labels match any named
label on the PR or issue. Missing fields do not match. For check events, workflow
names and paths are resolved by exact check suite using GitHub Actions read access.
Use these filters for admission; restrictions written in text are instructions
for the model and do not prevent delivery. Unmatched events use no daily quota
and create no background run. For example, use actions: ["completed"] and
filters: { workflow_names: ["Release Composal Desktop"], branches: ["master"], conclusions: ["success"] } for successful desktop releases.
delivery_ttl_seconds optionally expires waiting or restart-delayed event
deliveries 60–86400 seconds after receipt (default 3600). Expired events do not
start late. Processing results remain in event_deliveries_list; internal event
jobs do not appear in routines and are removed after completion or terminal
failure. Startup also removes expired legacy composal-event-* one-shot jobs
without touching user-created routines. To change an immutable subscription,
register a new subscription ID and retire the old one.