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. organizationId and documentId are required and identify the document the execution runs against — the document must already exist, and findings are persisted to it as comment annotations. 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

x-velt-api-key
string
required
Your API key.
x-velt-auth-token
string
required

Body

Params

data
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 agentId, organizationId, or documentId; invalid trigger or deviceType) / NOT_FOUND (store database not found, or the target document does not exist) / ALREADY_EXISTS (an execution is already running for this agent + document combination; the error message includes the running execution’s ID) / RESOURCE_EXHAUSTED (the workspace’s AI credits are exhausted).