# Use the API

The console, CLI, and your application use the same `/v2` API. Start the server with the [quickstart](/docs/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:

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

Save this as `agent.json`:

```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:

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

Save the input as `run.json`:

```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:

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

Use the returned `run_id`:

```sh
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](/docs/cli-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:

```sh
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:

```sh
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`:

```sh
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](/docs/server-reference#what-it-serves) 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:

```sh
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](/docs/client-typescript) and [Python client](/docs/client-python) 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.