> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guidinghand.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference

> Base URLs, authentication and versioning for the GuidingHand API.

The pages in this section are generated from GuidingHand's OpenAPI 3.1 spec, which is the contract for the API. The same file is served at [`https://guidinghand.ai/openapi.json`](https://guidinghand.ai/openapi.json) if you want to generate a client.

## Base URLs

| Environment | Base URL                     | Notes                                                                                                                         |
| ----------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Production  | `https://guidinghand.ai`     | Live billing.                                                                                                                 |
| Development | `https://dev.guidinghand.ai` | Stripe in test mode. Use it to build and test an integration without real charges. It has its own console, orgs and API keys. |

All paths start with `/v1`, for example `https://guidinghand.ai/v1/sessions`.

## Authentication

Send an org API key as a bearer token on every request:

```bash theme={null}
curl https://guidinghand.ai/v1/agents \
  -H "Authorization: Bearer $GUIDINGHAND_API_KEY"
```

Keys start with `gh_live_`. Admins create them in the console under **Settings → API keys**; each key is shown once and belongs to one org. See [API keys](/concepts/orgs#api-keys).

Requests with a body send JSON with `Content-Type: application/json`. Responses are JSON, except a recorded screen (`GET /v1/tasks/{task_id}/recording/{seq}`), which is a PNG.

## Versioning

The version is in the path: `/v1`. Within `v1`, new fields, endpoints and event types may be added, so ignore fields and event types your code doesn't know rather than failing on them.

## Objects and conventions

* Every object has an `object` field: `agent`, `session`, `task`, `recording` or `webhook`.
* Timestamps are ISO 8601 strings in UTC.
* A session's id is its pairing code (`K7QM-24XP`). Task ids start with `task_`.
* Lists return `{ "data", "has_more", "next_cursor" }`, newest first. See [pagination](/guides/errors#pagination).
* Errors return `{ "error": { "type", "message" } }`. See [errors](/guides/errors).
* `metadata` on sessions and tasks holds your own string values and is returned as given.

## The older session-token API

Before `/v1`, integrations used a smaller task API authenticated with one session's token. It still works, and it is what [`/tools.json`](/guides/ai-agents) describes for LLM agents.

| Endpoint      | Body                                                                                | Does                                                                                                  |
| ------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `POST /start` | `{ prompt, request_id? }`                                                           | Starts a task. Returns its `id`, `cursor` and first `update`.                                         |
| `POST /wait`  | `{ id, after, timeout_ms?, question_id?, answer?, approval_id?, decision?, note? }` | Long-polls for events after `after` (default 25 s, at most 55 s), and answers a question or approval. |
| `POST /stop`  | `{ id }`                                                                            | Stops the task.                                                                                       |
| `POST /tasks` | none                                                                                | This session's tasks, newest first.                                                                   |
| `POST /trace` | `{ id }`                                                                            | Diagnostics for one task, safe to paste into a support ticket.                                        |
| `GET /health` | none                                                                                | Service status; with a token, also whether the computer is connected.                                 |

Authenticate with `Authorization: Bearer <session_token>`. The `session_token` (`gh_sk_…`) is returned once by `POST /v1/sessions`. You can also use an org API key and name the session with `code` in the body.

Differences from `/v1`:

* Errors are `{ "error": "message" }`, a string rather than an object. Extra fields sit next to it, such as `code` and `answered_by` when a question was already answered.
* Tasks come back as `{ id, request_id, status, done, cursor, events, update, question?, approval?, result?, error? }`: the pending item is in `question` or `approval` instead of `pending`. `question.customer_can_answer` and `approval.customer_can_approve` are the same as in `/v1`.
* Answers and approvals go through `/wait` instead of a separate `/respond`.

New integrations should use `/v1`.