Skip to main content
An agent run is a durable, asynchronous record. Keep the returned run_id with your source record so you can correlate status, documents, webhooks, and support traces later.

​
Run lifecycle

  1. Call GET /api/v1/agents and select an accessible agent.
  2. If the run has files, call POST /api/v1/agents/{agent_id}/upload-urls.
  3. Upload each file directly to its presigned URL with PUT and the requested content type.
  4. Call POST /api/v1/agents/{agent_id}/run with the uploaded file keys and/or a user_message.
  5. Poll GET /api/v1/runs/{id} until the status is terminal, or receive a run webhook.
Run statuses are queued, running, completed, failed, and cancelled.
completed means the agent finished. A returned document can still be a draft, awaiting approval, or waiting to be processed into a connected system.

​
Upload a file

First request an upload URL:
Upload the file with the returned upload_url. The URL expires after one hour:

​
Create and follow the run

Poll the returned status_url until the run is terminal. A failed run can still contain conversations and documents; inspect both the run’s error and each document’s error.

​
Multiple and background files

  • A run accepts up to 50 foreground files.
  • process_together: true sends up to 10 foreground files through one agent conversation.
  • Background files are available to tools but are not read by the agent directly. When a run contains only background files, include a user_message that tells the agent what to do.
  • Set notification_email only when email notification is desired. Omitting it sends no completion email.

​
Process a document

GET /api/v1/documents/{id} returns the full document_data. POST to the same resource processes its current data into the configured system of record. Check the returned document status: an external-system rejection is represented by status: "error" and an error message in an HTTP 200 response. DELETE /api/v1/documents/{id} is a soft delete. It cancels in-flight work and moves the document to trash.