Skip to main content
The pages in this section are generated from Eager’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/agents/support/responses.

​
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; each key is shown once and belongs to one org. See API keys. Requests with a body send JSON with Content-Type: application/json (an upload can also send the file itself). Responses are JSON, except a streamed reply (POST /v1/agents/{agent_id}/responses with "stream": true), which is server-sent events, an upload’s file (GET /v1/uploads/{upload_id}/content), and a recorded screen (GET /v1/tasks/{task_id}/recording/{seq}) or an open test machine’s screen (GET /v1/start_states/{start_state_id}/screen), which are images.

​
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, agent_draft, agent_version, agent_file, procedure, procedure_revision, response, conversation, conversation_item, upload, computer, computer_pool, session, task, recording, webhook, tool_secret, connector, connection or audit_event, and for evals test_case, test_set, test_run, attempt, start_state or runner.
  • Timestamps are ISO 8601 strings in UTC.
  • Responses start with resp_, conversations conv_, uploads upl_, procedures prc_, computer pools pool_ and tasks task_. A session’s id is its pairing code (K7QM-24XP), and so is a linked computer’s. Eval ids start with tc_ (test case), ts_ (test set), tr_ (test run), at_ (attempt), ss_ (start state) and rn_ (runner); a test case can also be named by its key.
  • Lists return { "data", "has_more", "next_cursor" }, a page at a time (limit, cursor), and most take q to search them. See pagination and search.
  • Errors return { "error": { "type", "message" } }. See errors.
  • metadata on conversations, sessions, tasks and eval objects holds your own 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, conversation_id, 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 route. A session’s token speaks for the person at the computer, so they’re recorded in the task’s conversation (conversation_id) as the person’s, with the same rules as the desktop app: one the agent keeps for your team (customer_can_answer or customer_can_approve is false) gets 403 with code: "customer_answers_off" or "customer_approvals_off". Your team decides those with POST /v1/conversations/{conversation_id}/decisions, or here with an org API key and code (then it’s your team’s decision).
New integrations should use /v1.