Skip to main content
POST

Request Inputs

The inputs field accepts a JSON object whose values are MessageContent items. Each value is a typed, discriminated union — the type field determines which modality is passed in as context for the agent. You can mix and match any number of modalities in a single request (e.g. a document + a reference image + a text instruction). Each slot can also be a plain JSON primitive (string, number, boolean, array, object) when the agent’s input schema declares a non-media field — e.g. an email_body string or a structured metadata object to include alongside the uploaded file. See the Multi-modal Inputs guide for the full reference on each modality, including detail levels for images / video, uploaded-file workflows, and typed Pydantic / Zod input models.
inputs is just a dictionary of named context slots — the keys are arbitrary (e.g. "file", "document", "reference_image", "instruction", "email_details") and match the input schema of your agent. Each value is either a MessageContent object of one of the types above, or a plain JSON primitive.

Generic payload — all input types

A single inputs object can freely mix every modality together with raw strings / JSON. The example below combines an uploaded file, a file URL, an image URL, a video URL, an audio URL, a text instruction, and two plain-primitive context fields (an HTML email body and a structured metadata object):
All input types

Minimal payload shapes

Document (PDF, Word, etc.) via URL
Document via uploaded file ID
Image + text instruction
Video + reference image
Audio transcription
Uploaded file + raw string / JSON context
Set config.service_tier to control both billing and request routing — mirroring OpenAI’s service_tier and Vertex AI’s Gemini Flex/Priority offering:
  • standard / default (default) — baseline rates and latency.
  • flex0.5× cost (50% off), higher latency. Best for batch / background workloads.
  • priority1.8× cost, lowest latency. Best for latency-sensitive, user-facing workflows.
Omitting the field (or passing "auto" or null) resolves to standard. See the pricing guide for full details.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Request to execute an agent.

metadata
RequestMetadata · object

Optional metadata to pass to the model.

config
AgentExecutionConfig · object

The configuration for the agent execution request.

id
string

Unique identifier of the request.

created_at
string<date-time>

Date and time when the request was created (in UTC timezone)

callback_url
string<uri> | null

The URL to call when the request is completed.

Minimum string length: 1
model
enum<string> | null

VLM Run Agent model to use for execution. When omitted, the skill's vlmrun.yaml model is used; otherwise the agent default.

Available options:
vlmrun-orion-1,
vlmrun-orion-1:auto,
vlmrun-orion-1:fast,
vlmrun-orion-1:pro,
vlmrun-orion-2,
vlmrun-orion-2:auto,
vlmrun-orion-2:qwen3.6-35b-a3b,
vlmrun-orion-2:gemma4-26b-a4b,
vlmrun-orion-2:cosmos3-nano,
vlmrun-orion-2:kimi-2.6,
vlmrun-orion-2:kimi-k3,
vlmrun-orion-2:gpt-5.5,
vlmrun-orion-2:opus-4.8,
vlmrun-orion-2:muse-spark-1.1,
vlmrun-orion-2:grok-4.5,
vlmrun-orion-2:gemini-flash-3.6,
vlmrun-orion-2:fast,
vlmrun-orion-2:pro
name
string | null

Name of the agent. If not provided, we use the prompt to identify the unique agent.

batch
boolean
default:true

Whether to process the document in batch mode (async).

inputs
AgentExecutionInputs · object | null

The inputs to the agent.

Response

Successful Response

Response to the agent execution request.

name
string
required

Name of the agent

usage
CreditUsageResponse · object

The usage metrics for the request.

id
string

Unique identifier of the agent execution response.

response
any | null

The response from the model.

execution_mode
enum<string>
default:agent

How the execution ran: program when a cached skill pipeline.py ran as fixed code (no LLM agent loop), else agent. Always agent for non-Orion-2 models.

Available options:
agent,
program
status
enum<string>
default:pending

The status of the job.

Available options:
pending,
enqueued,
running,
completed,
failed,
paused
created_at
string<date-time>

Date and time when the execution was created (in UTC timezone)

completed_at
string<date-time> | null

Date and time when the execution was completed (in UTC timezone)