Wallfacer API v1
The Wallfacer API provides two tiers of infrastructure access: a managed Task API for AI-powered coding sessions, and an IaaS VM API for direct virtual machine control.
The full spec is at /docs/openapi.yaml.
Accounts
Manage accounts. Every resource (environments, tasks, VMs) belongs to an account.
GET /v1/accounts: List accountsPOST /v1/accounts: Create an accountGET /v1/accounts/{account_id}: Get an accountPATCH /v1/accounts/{account_id}: Update an accountDELETE /v1/accounts/{account_id}: Delete an accountPOST /v1/accounts/{account_id}/avatar: Set the account avatarDELETE /v1/accounts/{account_id}/avatar: Remove the account avatarPATCH /v1/accounts/{account_id}/setup: Record a setup decision
Environments
Environments define how a VM is set up: which repo to clone, what commands to run, and what services to start. Create an environment once, then use it to boot VMs or start tasks.
GET /v1/accounts/{account_id}/environments: List environmentsPOST /v1/accounts/{account_id}/environments: Create an environmentGET /v1/accounts/{account_id}/environments/{environment_id}: Get an environmentPATCH /v1/accounts/{account_id}/environments/{environment_id}: Update an environmentDELETE /v1/accounts/{account_id}/environments/{environment_id}: Delete an environment
Virtual Machines
Create, manage, and destroy VMs. VMs are always booted from an environment: you pick the environment, and everything else is derived from it.
GET /v1/accounts/{account_id}/vms: List VMsPOST /v1/accounts/{account_id}/vms: Create a VMGET /v1/accounts/{account_id}/vms/{vm_id}: Get a VMDELETE /v1/accounts/{account_id}/vms/{vm_id}: Destroy a VMPOST /v1/accounts/{account_id}/vms/{vm_id}/commands: Execute a commandGET /v1/accounts/{account_id}/vms/{vm_id}/simulator: Get simulator statusGET /v1/accounts/{account_id}/vms/{vm_id}/simulator/screenshot: Get simulator screenshotPOST /v1/accounts/{account_id}/vms/{vm_id}/simulator/builds: Trigger a buildGET /v1/accounts/{account_id}/vms/{vm_id}/simulator/logs: List simulator logs
Tasks
A task represents a unit of work, such as "fix the login bug" or "add dark mode." Create a task, then open sessions against it to start coding conversations.
GET /v1/tasks: List tasks across your accountsGET /v1/accounts/{account_id}/tasks: List tasksPOST /v1/accounts/{account_id}/tasks: Create a taskGET /v1/accounts/{account_id}/tasks/{task_id}: Get a taskPATCH /v1/accounts/{account_id}/tasks/{task_id}: Update a taskDELETE /v1/accounts/{account_id}/tasks/{task_id}: Delete a taskPOST /v1/accounts/{account_id}/tasks/{task_id}/directions: Direct a blocked taskPOST /v1/accounts/{account_id}/tasks/{task_id}/retries: Retry an errored taskGET /v1/accounts/{account_id}/tasks/{task_id}/sessions: List sessionsPOST /v1/accounts/{account_id}/tasks/{task_id}/sessions: Create a sessionGET /v1/accounts/{account_id}/tasks/{task_id}/sessions/{session_id}: Get a sessionPATCH /v1/accounts/{account_id}/tasks/{task_id}/sessions/{session_id}: Update a sessionGET /v1/accounts/{account_id}/tasks/{task_id}/sessions/{session_id}/messages: List messagesPOST /v1/accounts/{account_id}/tasks/{task_id}/sessions/{session_id}/messages: Send a messageGET /v1/accounts/{account_id}/tasks/{task_id}/sessions/{session_id}/messages/{message_id}: Get a messageDELETE /v1/accounts/{account_id}/tasks/{task_id}/sessions/{session_id}/messages/{message_id}: Delete a message
Account Users
Manage membership and roles on an account. Admins+ can add, update, and remove users.
GET /v1/accounts/{account_id}/users: List account usersPOST /v1/accounts/{account_id}/users: Attach an existing user to the accountGET /v1/accounts/{account_id}/users/{user_id}: Get an account userPATCH /v1/accounts/{account_id}/users/{user_id}: Update a user's roleDELETE /v1/accounts/{account_id}/users/{user_id}: Remove a user from the account
Agent Domain
The subdomain every one of an account's agents is addressed at. Choosing it is the first thing an account does: it is what gives each agent a real email address, a mailbox, and the ability to be shared a document the way a colleague is. It is chosen once and cannot be changed afterwards, because every agent address, every document shared with one, and every message sent by one hangs off it.
GET /v1/accounts/{account_id}/workspace: Get the agent domainPUT /v1/accounts/{account_id}/workspace: Choose the agent domainGET /v1/accounts/{account_id}/workspace/labels/{label}: Check a subdomain
Agent Handles
A handle is the one name an agent answers to everywhere: the part before the `@` in its email address, and the name people type after the `@` in Slack. It has to satisfy both systems at once, and it is never reused, so check a candidate here before you hire or rename an agent rather than finding out when the accounts are created.
GET /v1/accounts/{account_id}/handles/{handle}: Check a handle
Agent Identities
The accounts an agent holds on external systems, so you can see what it can reach and grant or revoke each one. A Google account gives the agent a real address in your agent domain, a mailbox, and the ability to be shared documents the way a colleague is. A Slack app gives it its own name, avatar, handle and direct-message conversation in your workspace. Each account is addressed by the name of the system it is on, so granting one is a single request against a fixed address.
GET /v1/accounts/{account_id}/agents/{agent_user_id}/identities: List an agent's identitiesGET /v1/accounts/{account_id}/agents/{agent_user_id}/identities/{provider}: Get an agent identityPUT /v1/accounts/{account_id}/agents/{agent_user_id}/identities/{provider}: Give an agent an identityDELETE /v1/accounts/{account_id}/agents/{agent_user_id}/identities/{provider}: Take an identity awayPOST /v1/accounts/{account_id}/agents/{agent_user_id}/identities/{provider}/tokens: Mint an access tokenPOST /v1/accounts/{account_id}/agents/{agent_user_id}/identities/{provider}/approvals: Request a permission approval link
Agent Journal
An agent's own memory: short notes it writes for itself about work it has done and people it has worked with, and reads back in every session that follows. The agent decides what goes in and nothing approves it, so the journal is how an agent gets better at your work over time rather than starting each task from nothing. Everything in it is readable here, by anyone on the account. Entries are written by the agent while it works, and nobody writes one for it. What you can do is correct one and delete one: an agent's memory of your work is yours to keep honest, and a note that should not be in it should not be in it.
GET /v1/accounts/{account_id}/agents/{agent_user_id}/journals: List an agent's journal entriesPATCH /v1/accounts/{account_id}/agents/{agent_user_id}/journals/{journal_id}: Update a journal entryDELETE /v1/accounts/{account_id}/agents/{agent_user_id}/journals/{journal_id}: Delete a journal entry
Agent Objectives
What an agent is driving toward. An objective is a standing statement of intent with
no deadline: "keep response time on customer bug reports under one business day", not
"answer this ticket". The agent reads its objectives while it decides what matters,
and files the commitments it takes on against them, so you can see what a piece of
work was in service of.
You write objectives; the agent does not write its own. Any member of the account can
create, edit, and close one. The agent's own side is reading them and closing one when
it is genuinely met, abandoned, or replaced, and it records a line of reasoning when
it does.
GET /v1/accounts/{account_id}/agents/{agent_user_id}/objectives: List an agent's objectivesPOST /v1/accounts/{account_id}/agents/{agent_user_id}/objectives: Create an objectiveGET /v1/accounts/{account_id}/agents/{agent_user_id}/objectives/{objective_id}: Get an objectivePATCH /v1/accounts/{account_id}/agents/{agent_user_id}/objectives/{objective_id}: Update or close an objectiveDELETE /v1/accounts/{account_id}/agents/{agent_user_id}/objectives/{objective_id}: Delete an objective
Agent Reveries
What an agent currently believes about how to do its work: a short list of claims, grouped by area, written by the agent's own scheduled pass over the corrections its colleagues gave it. The whole list rides into every session, so a claim is in force on the agent's next turn.
You correct an agent by talking to it, in the app or Slack or email, the way you would correct a colleague. There is nothing to file and no endpoint that writes a claim for you. What you do here is read the list, sharpen a claim, and delete one you disagree with. A claim you have edited is yours from then on: the agent's own pass may cite it and may not change it.
GET /v1/accounts/{account_id}/agents/{agent_user_id}/reveries: List an agent's reveriesGET /v1/accounts/{account_id}/agents/{agent_user_id}/reveries/sections: List the sections a claim can be filed underGET /v1/accounts/{account_id}/agents/{agent_user_id}/reveries/{reverie_id}: Read one reveriePATCH /v1/accounts/{account_id}/agents/{agent_user_id}/reveries/{reverie_id}: Edit a reverieGET /v1/accounts/{account_id}/agents/{agent_user_id}/reveries/{reverie_id}/revisions: Read a reverie's historyDELETE /v1/accounts/{account_id}/agents/{agent_user_id}/reveries/{reverie}: Delete a reverie
Agent Todos
What an agent owes. A todo is a commitment the agent wrote down while it worked: "check
whether the migration finished on Thursday", "follow up with the reporter once the fix
ships". A todo can carry a due time, and when that time arrives the agent is started on
a conversation with the todo as its prompt, so a promise made on Monday happens on
Thursday without anybody chasing it.
The agent is the only author. You add a todo by asking the agent for it in conversation,
the same way you would ask a colleague, and it writes it down. What you can do here is
correct one that is still open and delete one that should not be on the list at all.
Closing a todo stays the agent's act, because the outcome is its account of how the work
went. Objectives are the half you author, through the objectives endpoints.
GET /v1/accounts/{account_id}/agents/{agent_user_id}/todos: List an agent's todosGET /v1/accounts/{account_id}/agents/{agent_user_id}/todos/{todo_id}: Get a todoPATCH /v1/accounts/{account_id}/agents/{agent_user_id}/todos/{todo_id}: Update a todoDELETE /v1/accounts/{account_id}/agents/{agent_user_id}/todos/{todo_id}: Delete a todo
Agents
Agents are the identities your account runs autonomous work as. Each has a title, a job description (a handbook page), the single environment it works in, and the model that powers it. An automated step names the agent that runs it. Disabling an agent keeps its history but removes it from new work.
GET /v1/accounts/{account_id}/agents: List agentsPOST /v1/accounts/{account_id}/agents: Onboard an agentGET /v1/accounts/{account_id}/agents/{agent_user_id}: Get an agentPATCH /v1/accounts/{account_id}/agents/{agent_user_id}: Update an agentDELETE /v1/accounts/{account_id}/agents/{agent_user_id}: Disable an agentPOST /v1/accounts/{account_id}/agents/{agent_user_id}/replays: Replay quiet thread repliesGET /v1/accounts/{account_id}/agents/{agent_user_id}/quiet-replies: List quiet thread repliesGET /v1/accounts/{account_id}/agents/{agent_user_id}/browser-state: Get saved browser stateDELETE /v1/accounts/{account_id}/agents/{agent_user_id}/browser-state: Clear saved browser state
Analytics
Read-only reports on the work done in an account and the model usage behind it.
GET /v1/accounts/{account_id}/analytics/autonomyGET /v1/accounts/{account_id}/analytics/handbooksGET /v1/accounts/{account_id}/analytics/bottlenecksGET /v1/accounts/{account_id}/analytics/completionGET /v1/accounts/{account_id}/analytics/agents: Get AI employee performanceGET /v1/accounts/{account_id}/analytics/agents/{agent_user_id}: Get one AI employee's performanceGET /v1/accounts/{account_id}/analytics/usage: Get account model usage
Attachments
Attachments carry arbitrary content along with a task, such as a ticket body, an external reference, or a file. Text content is prepended to the agent's first message; binary and URI-only content is referenced but not fetched.
GET /v1/accounts/{account_id}/tasks/{task_id}/attachments: List attachments for a taskPOST /v1/accounts/{account_id}/tasks/{task_id}/attachments: Create an attachmentDELETE /v1/accounts/{account_id}/tasks/{task_id}/attachments/{attachment_id}: Delete an attachmentGET /v1/accounts/{account_id}/tasks/{task_id}/attachments/{attachment_id}/contents: Read attachment contents
Audit
Admin-only. Returns audit rows across three streams: execution (what happened on tasks), policy (configuration changes), and access (who looked at what).
GET /v1/accounts/{account_id}/audit: List audit eventsGET /v1/accounts/{account_id}/audit/policy: List policy audit eventsGET /v1/accounts/{account_id}/audit/access: List access audit events
Connections
The external systems your account is linked to. A connection is established once, by an admin, and everything your agents do on that system sits inside it. Connecting Slack is what lets each of your agents have its own app there, with its own name, avatar and direct-message conversation.
GET /v1/accounts/{account_id}/connections: List connections
Credentials
Hand an agent a login the way you hand a new hire one. A credential belongs to the account, is granted to agents one at a time, and reaches a granted agent's work as a named variable it can use but never read. Values are write-only: once stored, no endpoint returns one, and replacing it is the only way to change it. Revoking a grant takes effect on the agent's next session.
GET /v1/accounts/{account_id}/credentials: List credentialsPOST /v1/accounts/{account_id}/credentials: Add a credentialGET /v1/accounts/{account_id}/credentials/{credential_id}: Get a credentialPATCH /v1/accounts/{account_id}/credentials/{credential_id}: Update a credentialDELETE /v1/accounts/{account_id}/credentials/{credential_id}: Delete a credentialGET /v1/accounts/{account_id}/credentials/{credential_id}/grants: List who holds a credentialPUT /v1/accounts/{account_id}/credentials/{credential_id}/grants/{agent}: Give an agent a credentialDELETE /v1/accounts/{account_id}/credentials/{credential_id}/grants/{agent}: Take a credential backGET /v1/accounts/{account_id}/agents/{agent_user_id}/credentials: List what an agent holdsGET /v1/accounts/{account_id}/credential-requests: List credential requestsGET /v1/accounts/{account_id}/credential-requests/{credentialRequest_id}: Get a credential requestPOST /v1/accounts/{account_id}/credential-requests/{credentialRequest_id}/resolve: Resolve a credential request
Directory
Everybody the account knows: its members, its AI employees, and everybody its agents have met on a channel. One row per person, kept rather than assembled, so somebody last heard from years ago still resolves and everything ever written about them joins under one reference.
The two things you can change here are how a person wants to be written to, and whether two rows are actually one person.
GET /v1/accounts/{account_id}/people: List the people this account knowsGET /v1/accounts/{account_id}/people/{person_id}: Show one personPATCH /v1/accounts/{account_id}/people/{person_id}: Set how a person wants to be written toPOST /v1/accounts/{account_id}/people/{person_id}/merges: Fold one person into another
Endpoints
PUT /v1/accounts/{account_id}/agents/{agent_user_id}/automation: Attach (or replace) the git token one agent authenticates with. The
token is validated by the form request, stored encrypted, and never
returned; the git username is resolved from the token for display.DELETE /v1/accounts/{account_id}/agents/{agent_user_id}/automation: Disconnect one agent's git token. Steps that run as this identity then
have no git credentials until a token is attached again.GET /v1/accounts/{account_id}/agents/{agent_user_id}/usageGET /v1/accounts/{account_id}/events/shapes
Event keys
Account-owned keys for ingesting events. Unlike a personal API token, an event key
belongs to the account rather than to the person who created it, so it keeps working
after that person leaves the account. Use one per integration that sends events to
your account (for example, one per webhook source), and revoke them individually.
An event key authenticates only the event-ingest endpoint (`POST /v1/accounts/{account}/events`).
It cannot create tasks, environments, or VMs, or read any account data. Managing keys
(listing, creating, revoking) requires an admin or owner of the account.
GET /v1/accounts/{account_id}/keys: List event keysPOST /v1/accounts/{account_id}/keys: Create an event keyDELETE /v1/accounts/{account_id}/keys/{key}: Revoke an event key
Events
Lifecycle event timeline for environment snapshot generation. One row per state transition (setup started, service healthy, environment ready, etc.).
GET /v1/accounts/{account_id}/environments/{environment_id}/events: List environment generation eventsGET /v1/accounts/{account_id}/events: List eventsPOST /v1/accounts/{account_id}/events: Ingest an eventGET /v1/accounts/{account_id}/events/{event_id}: Get an event
Inbound webhook collectors
Account-owned inbound URLs. Each collector gives you a unique URL you paste into an
external system's webhook settings (for example Sentry, Linear, HubSpot, or Stripe).
Whatever that system POSTs to the URL is captured as an event on your account stream,
where a playbook's trigger can run on it. No per-system code: the raw payload lands in
the event `data`, and a trigger describes in plain language when it should run.
Like an event key, a collector belongs to the account rather than to the person who
created it, so it keeps working after that person leaves. The full URL carries the
collector's secret, so treat it as a credential; you can read it again at any time by
listing collectors, and rotate it if it ever leaks. Managing collectors (listing,
creating, rotating, deleting) requires an admin or owner of the account.
GET /v1/accounts/{account_id}/collectors: List collectorsPOST /v1/accounts/{account_id}/collectors: Create a collectorPOST /v1/accounts/{account_id}/collectors/{collector}/secret-rotations: Rotate a collector secretDELETE /v1/accounts/{account_id}/collectors/{collector}: Delete a collector
Inbound webhooks
Public collector URLs that turn any external system's webhook into an event on your account stream. Create and manage collectors from your account settings, paste the URL into the external system, and the payloads land in your event stream where your automation can match on them.
POST /v1/hooks/{collector}/{secret}: Receive a webhook
Invitations
Create and manage account invitations. Invitations are for emails that do not yet belong to a Wallfacer user; once accepted, the invitee is attached to the account with the invited role.
GET /v1/invitations/{token}: Show an invitationPATCH /v1/invitations/{token}: Accept an invitationGET /v1/accounts/{account_id}/invitations: List pending invitationsPOST /v1/accounts/{account_id}/invitations: Create an invitation
Logs
Per-manifest-step logs for VMs and environment snapshots. Each entry captures one step's stdout/stderr, status, exit code, and timing.
GET /v1/accounts/{account_id}/vms/{vm_id}/logs: List logs for a VMGET /v1/accounts/{account_id}/vms/{vm_id}/logs/{log}: Show one VM logGET /v1/accounts/{account_id}/environments/{environment_id}/logs: List logs for an environmentGET /v1/accounts/{account_id}/environments/{environment_id}/logs/{log}: Show one environment logGET /v1/accounts/{account_id}/environments/{environment_id}/snapshots/{snapshot}/logs: List logs for a snapshotGET /v1/accounts/{account_id}/environments/{environment_id}/snapshots/{snapshot}/logs/{log}: Show one snapshot logGET /v1/accounts/{account_id}/tasks/{task_id}/sessions/{session_id}/logs: List logs for a sessionGET /v1/accounts/{account_id}/tasks/{task_id}/sessions/{session_id}/logs/{log}: Show one session log
MCP connections
Sign in to the MCP servers on an environment that authenticate with OAuth. A server configured as `{url, auth: {type: "oauth"}}` cannot be used until somebody has signed in to it once: creating a connection returns a link to the provider's own consent screen, and the grant it produces is held encrypted and renewed in the background from then on. Servers that carry a header you supply need none of this.
GET /v1/accounts/{account_id}/environments/{environment_id}/connections: List connectionsPOST /v1/accounts/{account_id}/environments/{environment_id}/connections: Start a sign-in
Onboarding
A saved first-task setup, private to the current member of an account. Resume it on any device.
GET /v1/accounts/{account_id}/onboardings/current: Read first-task setupPUT /v1/accounts/{account_id}/onboardings/current: Save first-task setupPOST /v1/accounts/{account_id}/onboardings/{onboarding}/tasks: Start the first task
Pages
Handbook pages hold the knowledge half of your handbook: markdown guidance (how to write a great pull request, how to evaluate an idea) that AI agents receive when they run related playbooks. Pages also organize the handbook: a page can hold sub-pages and playbooks, so a page doubles as a section.
GET /v1/accounts/{account_id}/pages: List pagesPOST /v1/accounts/{account_id}/pages: Create a pageGET /v1/accounts/{account_id}/pages/{page_id}: Get a pagePATCH /v1/accounts/{account_id}/pages/{page_id}: Update a pageDELETE /v1/accounts/{account_id}/pages/{page_id}: Delete a pageGET /v1/accounts/{account_id}/pages/{page_id}/revisions: List page revisionsGET /v1/accounts/{account_id}/pages/{page_id}/revisions/{revision_id}: Get a page revisionGET /v1/accounts/{account_id}/handbook: Get the handbook treePATCH /v1/accounts/{account_id}/handbook: Reorder the handbook
Pipeline Versions
Each pipeline keeps an immutable history of versions. Tasks pin to the version active at the time they were created and continue running on that pinned version even after the pipeline publishes a newer one. Publish a new version to change pipeline behavior.
GET /v1/accounts/{account_id}/pipelines/{pipeline_id}/versions: List pipeline versionsPOST /v1/accounts/{account_id}/pipelines/{pipeline_id}/versions: Publish a new pipeline versionGET /v1/accounts/{account_id}/pipelines/{pipeline_id}/versions/{version}: Get a pipeline versionGET /v1/accounts/{account_id}/pipelines/{pipeline_id}/versions/{a}/diff/{b}: Diff two pipeline versions
Pipelines
Handbook pipelines define what your AI does for a task: an ordered list of steps (AI work, or a wait on a signal from the system the work lives in) plus triggers that spawn new tasks from inbound events.
GET /v1/accounts/{account_id}/pipelines: List pipelinesPOST /v1/accounts/{account_id}/pipelines: Create a pipelineGET /v1/accounts/{account_id}/pipelines/{pipeline_id}: Get a pipelinePATCH /v1/accounts/{account_id}/pipelines/{pipeline_id}: Update pipeline metadataDELETE /v1/accounts/{account_id}/pipelines/{pipeline_id}: Delete a pipelinePUT /v1/accounts/{account_id}/pipelines/{pipeline_id}/draft: Save a draftDELETE /v1/accounts/{account_id}/pipelines/{pipeline_id}/draft: Discard the draftPOST /v1/accounts/{account_id}/pipelines/{pipeline_id}/objective: Compile an objective from plain English
Search
Search across an account in one request. A single query returns matching environments, tasks, sessions, handbook pages, and pipelines, grouped by type.
GET /v1/accounts/{account_id}/search: Search
Secrets
Manage encrypted environment secrets. Reference a secret as `${secrets.NAME}` from any string-valued field in the environment's manifest (env values, command lines, working directories, healthcheck URLs and commands, source repo and branch fields, callback URLs); the platform substitutes the decrypted value before the manifest reaches the booting VM. A reference to a secret that does not exist on the environment fails the boot with a diagnostic listing every unresolved name. Values are write-only after creation; once stored, a value cannot be retrieved through any endpoint and must be rotated to replace.
GET /v1/accounts/{account_id}/environments/{environment_id}/secrets: List secrets for an environmentPOST /v1/accounts/{account_id}/environments/{environment_id}/secrets: Create a secretGET /v1/accounts/{account_id}/environments/{environment_id}/secrets/{secret_id}: Show a secretPATCH /v1/accounts/{account_id}/environments/{environment_id}/secrets/{secret_id}: Rotate a secretDELETE /v1/accounts/{account_id}/environments/{environment_id}/secrets/{secret_id}: Delete a secret
Snapshots
Manage snapshots of environments. Each snapshot represents one generation attempt. Successful ones are `ready`; failed ones are preserved so their logs can be inspected.
GET /v1/accounts/{account_id}/environments/{environment_id}/snapshots: List snapshots for an environmentPOST /v1/accounts/{account_id}/environments/{environment_id}/snapshots: Regenerate an environment's snapshotGET /v1/accounts/{account_id}/environments/{environment_id}/snapshots/{snapshot}: Show a snapshotDELETE /v1/accounts/{account_id}/environments/{environment_id}/snapshots/{snapshot}: Delete a snapshotPOST /v1/accounts/{account_id}/environments/{environment_id}/snapshots/{snapshot}/promote: Promote a snapshot to base
Task Actions
Every step execution on a task surfaces here. List them to see what the playbook has run, or cancel an in-flight step.
GET /v1/accounts/{account_id}/tasks/{task_id}/actions: List actions on a taskGET /v1/accounts/{account_id}/tasks/{task_id}/actions/{action_id}: Get a task actionPATCH /v1/accounts/{account_id}/tasks/{task_id}/actions/{action_id}: Transition a task action
Task Audit
A single, exportable record of a complete task run: the exact playbook version it followed, every step with who or what performed it and the verdict it produced, and the full event timeline.
GET /v1/accounts/{account_id}/tasks/{task_id}/audit: Get a task audit record
Task Events
Per-task projection of the event stream. Returns every event attached to the task, whether the caller ingested it directly with `task_ids`, an account-scoped routing pipeline routed it, or a pipeline automation emitted it.
GET /v1/accounts/{account_id}/tasks/{task_id}/events: List events attached to a task
Uploads
Files you send to storage directly, then attach to a task, a session, or a message.
Small supporting material can travel inside a create request as `inputs[].text` or
`inputs[].content_base64`. Larger material cannot: an API request has a transport size
limit well below what a single input may hold, and a request over it fails before we
can tell you why. An upload moves the bytes off that path. You declare the file, send
it straight to storage over a URL we sign for exactly those bytes, and then name the
upload where the content would have gone.
Three steps:
1. `POST /v1/accounts/{account}/uploads` with the file's name, exact byte size, and
SHA-256. The response carries `upload_url` and `upload_headers`.
2. `PUT` the file to `upload_url` with those headers, exactly as returned. Storage
refuses a body of a different length or with different contents.
3. `PATCH /v1/accounts/{account}/uploads/{upload}` with `{"status": "ready"}`. The
stored file is checked against what you declared, and the upload becomes usable.
Then pass `{"inputs": [{"upload_id": "..."}]}` to task, session, or message create. The
instruction itself stays ordinary prompt text; an upload is material the agent opens
with its file tools, never the instruction.
An upload can back exactly one input. Unused uploads expire, and are removed with their
file, after 30 minutes.
GET /v1/accounts/{account_id}/uploads: List uploadsPOST /v1/accounts/{account_id}/uploads: Create an uploadGET /v1/accounts/{account_id}/uploads/{upload_id}: Get an uploadPATCH /v1/accounts/{account_id}/uploads/{upload_id}: Mark an upload readyDELETE /v1/accounts/{account_id}/uploads/{upload}: Delete an upload
