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",
    "task": "Find sales leaders matching these constraints and return JSON.",
    "inputs": { "company_domain": "example.com", "locations": ["New York"] },
    "session_id": "optional_stable_id",
    "max_results": 25,
    "max_acu": 2,
    "sources": ["people", "public_web"],
    "memory": "none",
    "response_format": "standard"
}

Request fields

Field	Type	Rules
`operation`	`ask`, `connect`, `connections`	Defaults to `ask`
`task`	string	Preferred instruction for `ask`; maximum 20,000 characters
`prompt`	string	Deprecated alias for `task`; never provide both
`inputs`	object	Optional task inputs; maximum 32,000 serialized UTF-8 bytes
`app`	string	Required for `connect`
`session_id`	string	Optional stable conversation identifier
`max_results`	integer	Primary-result limit; `1`–`25`; default `25`
`max_acu`	integer	Hard customer admission and billing ceiling; `1`–`64`; default `2`
`sources`	string array	Any of `people`, `public_web`
`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`

An ask requires exactly one of task or the legacy prompt. inputs are available only for ask. max_results, max_acu, sources, and memory are signed into Eve's authenticated execution policy and enforced by tools. Provider/API calls are metered separately inside that signed policy and are hard-capped at 20 per run; raising max_acu never raises that server ceiling.

Durable JSON response

JSON asks return immediately with 202:

{
    "data": {
        "run_id": "run_123",
        "status": "queued",
        "poll_url": "/v1/agent/runs/run_123"
    },
    "meta": { "acu_limit": 2, "acu_used": 0 }
}

Poll GET /v1/agent/runs/run_123. A completed run returns:

{
    "data": {
        "output": "Human-readable synthesis",
        "artifacts": []
    },
    "meta": {
        "acu_limit": 2,
        "acu_used": 1
    }
}

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.

Cancel a queued or running job with DELETE /v1/agent/runs/run_123. Cancellation before billing finalization releases the API-key budget reservation. Run inputs and results are retrievable for seven days; later polls return 410 run_expired.

Response transport

Use Accept: application/json for a durable 202 job and poll URL.
Set response_format: "markdown" to receive Markdown from the completed poll.
Use Accept: text/event-stream for a live, cancellable interactive stream.

JSON work is independent of the HTTP socket. SSE callers must 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`
Background execution is unavailable	`503 queue_unavailable`

The task (or legacy prompt) is limited to 20,000 characters. Workspace credits and per-key budgets are enforced. max_acu is the request's signed execution 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.