Send the agent a message (submit a run)

Submits a run and returns 202 immediately; there is no blocking or SSE mode on this endpoint. Read the reply over the session WebSocket (GET /v1/ws), poll GET /v1/agents/{agentID}/runs/{runID} for status, or use the MCP send_workspace_message tool, which can wait. A run is nondeterministic and billable. Retry only with an Idempotency-Key: the same key replays the original run for 24 h (the replay carries X-Plori-Idempotent-Replay: true).

post/v1/agents/{agentID}/runs

Request

  • Base URL: https://api.plori.ai
  • URL: https://api.plori.ai/v1/agents/{agentID}/runs
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Path parameters

agentIDstring uuid required

Headers

Idempotency-Keystring

Optional run deduplication key. If the nonempty header and JSON idempotency_key are both set, the header takes precedence.

Request body

messagestring

The user message. Exactly one of message or messages is required; messages wins if both are set.

session_idstring

Continue an existing thread; omit to start a new one.

idempotency_keystring
max_turn_tokensinteger

Optional cumulative cache-weighted token ceiling for this run. 0 or omitted: no ceiling for a registered account, whose credit balance is its only spend limit, and 2,000,000 for an anonymous trial. Near the ceiling the agent stops using tools and ends with a reply that says the work so far is saved and that a new message continues the task.

max_advisor_spend_micro_usdinteger nullable

Advisor completion cap for the turn in micro-USD. Omit the field or send null to use the agent cap. Set 0 to disable advisor completions.

max_turn_secondsinteger

Soft checkpoint for this turn; 0 or omitted = the default.

github_tokenstring

Job-lifetime contents:read GITHUB_TOKEN for repository checkout. Delivered only to this turn in memory and never persisted; the owning API-key fallback is supported for GHES.

github_server_urlstring uri

HTTPS origin that issued github_token, such as https://github.com or a GHES origin. The token's in-memory Git credential helper is scoped to this host; invalid values fall back to github.com.

callback_urlstring
callback_secretstring

Response

Run submitted. Headers X-Plori-Run-Id and X-Plori-Session-Id mirror the body.

run_idstring required
workspace_idstring uuid

The Workspace the run belongs to; omitted for runs outside a Workspace.

session_idstring required

Changes

No recorded changes to this operation across all 1 revision of this API.