Use the API

The console, CLI, and your application use the same /v2 API. Start the server with the quickstart, then create an agent and submit work from a second terminal.

Use the CLI first

The published launcher also provides API commands. It finds a local server started with the same data directory, so you do not need to copy its token:

npx @parcha/agentrun@0.4 agents list
npx @parcha/agentrun@0.4 help

Save this as agent.json:

{
  "definition": {
    "id": "release-notes",
    "name": "Release notes",
    "instructions": "Write release notes from the supplied changes. Do not invent changes.",
    "harness": "pi",
    "tools": []
  }
}

Create it:

npx @parcha/agentrun@0.4 agents create --body @agent.json

Save the input as run.json:

{
  "input": {
    "content": "Write release notes: added CSV export; fixed the date filter."
  }
}

With a model key configured, start a capped run. This calls the model provider:

npx @parcha/agentrun@0.4 runs start release-notes --max-cost-usd 1 --body @run.json

Use the returned run_id:

npx @parcha/agentrun@0.4 runs get RUN_ID

Inspect status, result, error, and pending. If it asks a question, answer with runs message RUN_ID --content "...". The CLI source reference also documents commands added on main; use your installed command's help to check availability.

Connect over HTTP

Set AGENTRUN_BASE_URL to the server's printed API address, including /v2. For a launcher using its default data directory, read the token into the environment without displaying it:

export AGENTRUN_BASE_URL=http://127.0.0.1:7340/v2
export AGENTRUN_API_KEY="$(cat "$HOME/.agentrun/.token")"

Use the actual printed port. With a custom --data directory, the token is in that directory's .token. For a remote server, inject its token through your application's secret manager.

A read-only request:

curl --fail-with-body --silent --show-error \
  "$AGENTRUN_BASE_URL/agents" \
  -H "Authorization: Bearer $AGENTRUN_API_KEY"

Create an agent with the same agent.json:

curl --fail-with-body --silent --show-error \
  "$AGENTRUN_BASE_URL/agents" \
  -H "Authorization: Bearer $AGENTRUN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @agent.json

Use either the CLI creation or the HTTP creation for this example; do not create the same ID twice.

Routes to build around

Request	Purpose
GET /v2/health	Check server health without a credential.
GET /v2/capabilities	Discover runtime capabilities.
GET /v2/openapi.json	Read this server's API schema.
POST /v2/agents	Create an agent from {definition}.
POST /v2/agents/{id}/runs	Start work with {input, max_cost_usd?}.
GET /v2/runs/{id}	Inspect state and the final result.
GET /v2/runs/{id}/timeline	Follow activity; use the schema's cursor/polling contract.
POST /v2/runs/{id}/messages	Answer or follow up with {content}.

Send the bearer token for authenticated requests. Use an Idempotency-Key when retrying a run creation after a connection failure; keep the same key and request body for that logical submission.

Handle errors explicitly

• 401: token absent or refused.
• 409 agent_not_runnable: inspect the reported setup problem, such as a missing model key or unavailable box.
• 409 not_continuable: start a new run instead of messaging a failed or cancelled run.
• 412: a revision or learning item changed since you read its ETag.
• 422: fix the named request fields.
• 429: the server has reached its run or request limit.

The running server's OpenAPI is authoritative for its version. The server reference describes current main.

Client libraries

The TypeScript client is @parcha/agentrun-client on npm. The Python client is parcha-agentrun on PyPI and imports as agentrun. Both read AGENTRUN_BASE_URL and AGENTRUN_API_KEY, have one method per API operation, and can wait for a run:

npm i @parcha/agentrun-client
pip install parcha-agentrun

The home page shows both creating an agent, starting a capped run, and answering its question. See the TypeScript client and Python client references. @parcha/agentrun is the launcher and CLI, not a client library; do not import the older @parcha/agentrun 0.2 SDK as the server client.