Skip to main content
POST
Run Execution
Use this API to start an asynchronous agent execution. The engine creates an execution document in Firestore and dispatches a Cloud Task for processing. The response returns immediately with the executionId. Poll Get Execution to track progress and fetch findings. The apiKey is injected from request headers. Pass organizationId and documentId at the top level of the body if you want findings to land as comment annotations on a specific document. Cross-page execution is controlled via the crossPageExecute boolean; there is no separate endpoint. The schema uses .passthrough() so any additional fields are forwarded.

Endpoint

POST https://api.velt.dev/v2/agents/execution/run

Headers

string
required
Your API key.
string
required

Body

Params

object
required

Example Requests

1. Single page execution

2. Cross-page execution with user context (mobile)

3. Workflow-triggered execution

4. Minimal request

Response

Success Response

Failure Response

Errors: INVALID_ARGUMENT (invalid URL, missing required fields, invalid trigger or deviceType) / NOT_FOUND (agent does not exist) / FAILED_PRECONDITION (agent is disabled, store database not found, or an active execution already exists for this document).