Agent API

Request fields, response shapes, budgets, memory, source policy, and Agent operations.

Run an Agent task

POST /v1/agent

Requires agent:chat.

{
    "operation": "ask",
    "prompt": "Research Retool and return current stage, employee scale, and three evidence-backed lookalikes.",
    "session_id": "optional_stable_id",
    "max_output_tokens": 8000,
    "max_acu": 0.8,
    "sources": ["people", "public_web", "connected_apps"],
    "memory": "none",
    "response_format": "standard"
}

Request fields

Field	Type	Rules
`operation`	`ask`, `connect`, `connections`	Defaults to `ask`
`prompt`	string	Required for `ask`; maximum 20,000 characters
`app`	string	Required for `connect`
`session_id`	string	Optional stable conversation identifier
`max_output_tokens`	integer	Compatibility metadata; `256`–`64,000`; default `8,000`
`max_acu`	number	Admission/billing limit; `0.2`–`6.4`; default `0.8`
`sources`	string array	Any of `people`, `public_web`, `connected_apps`
`memory`	string	`none`, `read`, or `read_write`
`response_format`	string	`standard` or `markdown`
`output_schema`	object	Optional per-turn JSON Schema
`output_contract`	string	Fixed server-owned output contract
`stage_seed`	object	Required with the stage-lookalike output contract
`stage_options`	object	Fixed-contract options; `requested_count` is `1`–`25`, default `10`

max_output_tokens cannot exceed max_acu × 10,000, but it is compatibility metadata rather than an enforced provider output ceiling: the API validates and echoes it without forwarding it to Eve. max_acu gates account balance and billing; it is not a provider-compute cap.

Standard response

{
    "data": {
        "output": "Human-readable synthesis",
        "artifacts": [],
        "input_requests": []
    },
    "meta": {
        "acu_limit": 0.8,
        "acu_used": 0.4
    }
}

data.artifacts contains raw outputs from the research tools the Agent ran (searches, enrichments, page reads, deep research). Internal machinery — skill loading, memory, planning — never appears there.

When output_schema or output_contract is supplied, a validated data.structured_output is present. Stage-aligned lookalikes require the paired stage_seed and output_contract: "stage_aligned_lookalikes_v1", plus the explicit sources: ["public_web"] and memory: "none" policy; they cannot use an arbitrary caller schema. Optional stage_options.requested_count is bound into the immutable specialist request and defaults to 10. See Structured outputs.

Connection operations

Start a durable OAuth connection:

{
    "operation": "connect",
    "app": "gmail"
}

List apps connected to the authenticated identity:

{
    "operation": "connections"
}

The public API never accepts arbitrary provider credentials or a caller-selected user identity.

Response transport

Use Accept: application/json for a single completed envelope.
Use Accept: text/markdown only with response_format: "markdown" and no structured-output mode.
Use Accept: text/event-stream for progress and long-running work.

Long-running JSON asks — any fixed-contract request, plus any ask billed as deep work (max_acu above 0.8, or an explicit deep-research or lookalike prompt) — are delivered as one valid JSON value, but the response may stream leading whitespace keepalives while research runs so intermediary proxies do not time the request out mid-task. Read the complete body before parsing it. Once those keepalives begin, a terminal runtime failure cannot change the already-open HTTP status; it returns HTTP 200 with a top-level error, error.http_status, and error.retryable. Treat every top-level error as a failed request. SSE callers must likewise consume the terminal event rather than treating the initial HTTP 200 as completion.

Errors and limits

Condition	Status and code
Missing or invalid prompt for `ask`	`422 validation_failed`
Fixed-contract provenance could not be verified	`503 structured_output_unverified`
The Agent did not produce the requested result	`503 structured_output_incomplete`
The public result failed caller-schema validation	`503 structured_output_invalid`
The Agent could not complete the task	`503 agent_unavailable`

The prompt is limited to 20,000 characters. Workspace credits and per-key budgets are enforced. max_acu is the request's admission/billing limit; max_output_tokens is not an enforced Eve generation ceiling. Agent calls use the organization and API-key per-minute buckets; there is no additional Agent route cap. See Errors & rate limits for authentication, budget, retry, and plan details.