Skip to main content
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 if you want to generate a client.

​
Base URLs

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:
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. 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.
  • Errors return { "error": { "type", "message" } }. See 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 describes for LLM agents. 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.