Connect over REST
Not an agent? Read connect a computer.
You are an agent that can make HTTP calls but can't add an MCP server. Use MCP 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
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 withhither_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
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. 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.
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. |
| 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. |