> Index of all guides: https://hither.dev/llms.txt. Agents start at https://hither.dev/skill.md.

# Connect over REST

Not an agent? Read [connect a computer](getting-started.md).

You are an agent that can make HTTP calls but can't add an MCP server. Use [MCP](apps.md) if your client supports it: REST gives you an anonymous agent, every connection ends within 24 hours, and nothing can make it last longer. Follow these steps in order. Send a `User-Agent` naming your agent, such as `my-agent/1.0`, on every request.

## Step 1: Get an agent token

```http
POST https://hither.dev/api/agents
Content-Type: application/json

{ "agentName": "Research agent" }
```

`agentName` is required, 1 to 80 characters, and the person sees it marked as unverified. No other field is accepted. The server answers `201` with:

- `token`, your agent token. It starts with `hither_st_`. Store it privately; the server never shows it again.
- `agentId`, your identity.
- `expiresAt`, in Unix milliseconds, 24 hours from now. The token stops working then and can't be renewed. Every connection you open ends by then too.

## Step 2: Ask for a computer

```http
POST https://hither.dev/api/connect/request
Authorization: Bearer <token>
Content-Type: application/json

{ "operations": ["files.read", "files.list", "files.search"], "durationSeconds": 7200 }
```

Both fields are optional, so `{}` is a valid body.

| Field | What it's for |
| --- | --- |
| `operations` | Dotted names of what the task needs. Leave it out to ask for every operation except `mcp.*`. |
| `durationSeconds` | Access length from the request, 60 to 86,400. It never runs past your token's `expiresAt`. |

The answer is `201` with `connectionId`, `setupUrl` and `expiresAt`, the setup deadline. Give the person `setupUrl` whole, including `#key=`, and never post it publicly.

## Step 3: Wait for approval

Ask the person to open `setupUrl` on the computer you will use, choose permissions, run the setup command and approve in the terminal. Then `GET https://hither.dev/api/connections/<connectionId>` with `Authorization: Bearer <token>` every 5 seconds:

| `status` | Do |
| --- | --- |
| `pending` | Keep checking. `setupStep` is `run_setup` until the helper reads the code, then `awaiting_local_approval`. |
| `active` | Approved. Start when `online` is `true`. If it stays `false`, ask the person to wake the computer or check its network. |
| `ended` | Stop. `endedReason` is `expired`, `cancelled`, `denied`, `revoked` or `computer_removed`. Start again only if the person asks. |

The response also has `deviceId`, `deviceName`, `temporary` and `expiresAt`, when access ends.

## Step 4: Work

Use `Authorization: Bearer <token>` with the [REST endpoints](clients.md#rest). There's no activation step: the token you already hold works as soon as the person approves. Your connection gets sandboxed Terminal only, never full access or MCP servers, and on Windows it gets no Terminal.

You can open connections to more than one computer with the same token, up to the [limits](how-it-works.md#limits).

## Errors

| Status | Error | What to do |
| --- | --- | --- |
| 400 | `invalid_agent` | Send only `agentName`, 1 to 80 characters with no control characters. |
| 400 | `invalid_connection_request` | Check `operations` and the `durationSeconds` range, and send no other fields. |
| 401 | `unauthorized` | The token is wrong or expired. After 24 hours, start again at step 1 only if the person asks. |
| 404 | `connection_not_found` | Use the `connectionId` from step 2, with the token that created it. |
| 429 | `connection_rate_limited` | Stop. More requests won't help. |
| 429 | `connection_limit_or_identity_expired` | You have 5 pending or active connections, made 20 today, or your token expired. Finish or drop one first. |
| 403 | `anonymous_oauth_required`, `account_agent_required` | A REST agent can't be claimed or kept. The person can connect an agent through MCP with an account instead. |
| 410 | `endpoint_removed` | You followed old instructions. Use the steps on this page. |
| 503 | `connections_unconfigured` | This server is closed to anonymous agents. Use [MCP with sign-in](apps.md). |
| 403 | Cloudflare `1010` | Send a `User-Agent`, then check that `GET https://hither.dev/health` returns `"ok": true`. If still blocked, report the ray ID and stop. |
| 500 or none |  | The request may have gone through. For step 1, make one new agent. For step 2, asking again opens a second request, which counts toward your 5 until it expires 10 minutes later. |