API reference
Shape one task with options on the request.
Budgets, reasoning effort, background runs, earlier history, per-person memory and template values, all set per request.
Options
- max_cost_usd
- The most this task may cost, in US dollars as we bill it.
- timeout_seconds
- How long this turn may run.
- max_step
- How many steps the agent may take in this turn.
- reasoning
{"effort": ...}, one ofnone,minimal,low,medium,highorxhigh; anything else is 400. A model without the level asked for gets the nearest one it supports.- background
truereturns at once and runs the task on its own; read the result later.- metadata
- Your own keys and values, returned with the response.
- user
- Your id for the person the task is for, which keeps their Harness Memory apart.
- prompt
{"variables": {...}}, the values for a harness whose instructions are a template.
Example
POST /{harness_id}/v1/responses
Idempotency-Key: <uuid>
Content-Type: application/json
{
"input": "Summarize this quarter's support tickets.",
"max_cost_usd": 2,
"timeout_seconds": 900,
"reasoning": { "effort": "high" },
"background": true,
"metadata": { "ticket_batch": "2026-q4" }
}- Read a responseRead a background task's result when it is done.
Starting with earlier history
A request that starts a task may carry earlier user and assistant messages before the last user message. They become the agent's history, marked as imported, so a conversation that began somewhere else continues here. Imported turns are not billed.
Up to 20 earlier messages and 24,000 characters. Over either, nothing is imported and the whole input is read as one turn. content may be a string or a list of text parts.
{
"input": [
{ "role": "user", "content": "Our refund window is 30 days." },
{ "role": "assistant", "content": "Understood." },
{ "role": "user", "content": "Draft the reply to this customer." }
]
}Ready to run this against a live workspace?Create API key