Agent API
Hand a task to a Claude-powered agent that works in a session.
The Agent API runs a Claude-powered agent on a task you describe in plain language. The agent works in a Boxline session, so you can watch it in the live view. It is the quickest way to try Boxline end to end before you build your own agent loop.
Start a run
POST/v1/agent/runs
curl -X POST https://api.staging.boxline.dev/v1/agent/runs \
-H "x-api-key: $BOXLINE_API_KEY" \
-H "content-type: application/json" \
-d '{"task": "Open example.com and summarise what the page is for in two sentences."}'| Field | Default | Description |
|---|---|---|
task | required | What the agent should do, in plain language. |
sessionId | none | Run in an existing session instead of a new one. |
browser | true | Give a new session a browser. |
shell | false | Give a new session a shell. |
maxSteps | 30 | Upper bound on agent steps (1 to 100). |
provider | first configured | "anthropic" (Claude) or "openai" (GPT). See Choose a model. |
model | provider default | A model id from GET /v1/agent/models, e.g. "claude-opus-5" or "gpt-6-sol". |
effort | model default | "low", "medium", "high", "xhigh" or "max". |
keepSession | false | Keep the session the run created instead of releasing it when the run finishes. |
The response (201) is { id, status, sessionId, provider, model } with status "running".
Choose a model
GET/v1/agent/models
Lists every provider and model you can pick, with prices per million tokens and whether the provider is available. The same browser and shell tools work with every model.
| Provider | Models |
|---|---|
| Anthropic Claude | claude-opus-5 (default, most capable), claude-sonnet-5, claude-haiku-4-5 |
| OpenAI | gpt-6-sol (default, built for agents), gpt-6-astra (most capable), gpt-6-luna (lowest cost) |
Each finished run reports usage.costUsd: the model cost of that run, separate from session time.
Get the result
GET/v1/agent/runs/:id
Returns { id, status, task, sessionId, provider, model, steps, result, error, usage }. status is "running", "completed" or "failed"; steps lists the agent’s messages and tool calls; result holds the final answer and error the reason for a failure. usage reports model tokens.
GET/v1/agent/runs/:id/events streams the run as server-sent events, one per step.
const { id } = await client.agent.run({ task: "Find the pricing page on example.com" });
const run = await client.agent.wait(id); // polls until it finishes
console.log(run.status, run.result);Writing good tasks
- Say what done looks like: the answer, file or state you expect.
- Name the site or starting URL when you know it.
- Keep one goal per run; chain runs for multi-part work.
These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.