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

> ## Agent Instructions
> H Platform has four products: the Agents API (managed computer-use agents, base URL https://agp.eu.hcompany.ai/api/v2 or https://agp.hcompany.ai/api/v2 for the US), the Models API (OpenAI-compatible Holo vision-language models at https://api.hcompany.ai/v1), HoloDesktop CLI (Holo on the user's own desktop), and HoloTab (a free no-code Chrome extension that runs Holo in the user's browser, with recordable routines and schedules).
> Authenticate with a bearer API key from the HAI_API_KEY environment variable. SDKs: `pip install hai-agents` (Python, `from hai_agents import Client`) and `npm install hai-agents` (TypeScript, `import { HaiAgentsClient } from "hai-agents"`). CLI: `hai`.
> Agents do work in a browser or on a desktop; describe the task as an imperative instruction. To run a task quickly, prefer the pre-built agent `h/web-surfer-flash`. Read results from the session's `latest_answer` after it reaches a terminal status.
> Sessions are the unit of work; wait for a terminal status (completed, failed, timed_out, interrupted) before reading the answer. Use webhooks or the `changes` long-poll endpoint to follow progress.

# Run agents from n8n

> Run computer-use agents from an n8n workflow over plain HTTP: create the session, wait for the result, use the answer downstream.

The Agents API works in [n8n](https://n8n.io) as a plain HTTP integration and needs no custom node. Every call below is an **HTTP Request** node with **Authentication** set to the Header Auth credential from step 1.

| Node | Method | URL |
| - | - | - |
| Start Session | `POST` | `https://agp.eu.hcompany.ai/api/v2/sessions` |
| Poll Status | `GET` | `https://agp.eu.hcompany.ai/api/v2/sessions/{{ $('Start Session').item.json.id }}/status` |
| Read Answer | `GET` | `https://agp.eu.hcompany.ai/api/v2/sessions/{{ $('Start Session').item.json.id }}` |

<Steps titleSize="h3">
  <Step id="create-a-credential" title="Create a credential">
    In n8n, go to **Credentials → Add Credential → Header Auth**:

    | Field | Value |
    | - | - |
    | Name | `Authorization` |
    | Value | `Bearer hk-...` |

    Create the key at [platform.hcompany.ai/settings/api-keys](https://platform.hcompany.ai/settings/api-keys?product=computeruseagents\&source=docs). It's shown once, and scoped to one organization.
  </Step>

  <Step id="start-a-session" title="Start a session">
    Add the **Start Session** node with **Body Content Type** set to JSON:

    ```json Request body theme={"system"}
    {
      "agent": "h/web-surfer-flash",
      "messages": [
        {"type": "user_message", "message": "Find the top 3 trending repositories on GitHub today and report their names and star counts"}
      ]
    }
    ```

    `h/web-surfer-flash` is a pre-built agent with its own browser, so you have nothing else to set up. To run your own agent, pass its name or an inline agent object (see [Create a session](/agents-api/sessions/create)). The response carries the session `id`:

    ```json Response theme={"system"}
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "status": {"status": "pending", "steps": 0},
      "agent_view_url": "https://platform.hcompany.ai/agents/sessions/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "latest_answer": null
    }
    ```
  </Step>

  <Step id="poll-for-completion" title="Poll for completion">
    Add a **Wait** node (2 to 5 seconds, or 10 to 15 for tasks that run several minutes), then the **Poll Status** node, then an **If** node on `status`:

    | `status` | Meaning | Branch |
    | - | - | - |
    | `completed` | Done | Go to step 4 |
    | `failed`, `timed_out`, `interrupted` | Ended without an answer to use | Stop, read `error` |
    | `queued`, `pending`, `running`, `paused`, `idle`, `awaiting_tool_results` | Still going | Loop back to **Wait** |

    ```json Status response theme={"system"}
    {
      "status": "running",
      "error": null,
      "steps": 7
    }
    ```
  </Step>

  <Step id="read-the-answer" title="Read the answer">
    The status endpoint doesn't carry the answer. Once `status` is `completed`, the **Read Answer** node fetches the session: its `latest_answer` holds the agent's final result.
  </Step>
</Steps>

## Import the full workflow

Paste this JSON onto an empty n8n canvas (or **⋯ menu → Import from clipboard**) to get the nodes above, wired as a Wait, Poll Status, If loop. Then open each HTTP Request node and pick your own Header Auth credential: the placeholder credential ID won't match your instance. Add a counter if you want a hard cap on polls.

<Accordion title="n8n workflow JSON">
  ```json theme={"system"}
  {
    "nodes": [
      {"parameters": {}, "type": "n8n-nodes-base.manualTrigger", "typeVersion": 1, "position": [0, 0], "id": "cddf1db5-ac4a-4020-907c-20039726f972", "name": "When clicking 'Execute workflow'"},
      {
        "parameters": {
          "method": "POST", "url": "https://agp.eu.hcompany.ai/api/v2/sessions",
          "authentication": "genericCredentialType", "genericAuthType": "httpHeaderAuth",
          "sendBody": true, "specifyBody": "json",
          "jsonBody": "{\n  \"agent\": \"h/web-surfer-flash\",\n  \"messages\": [\n    {\"type\": \"user_message\", \"message\": \"Find the top 3 trending repositories on GitHub today and report their names and star counts\"}\n  ]\n}",
          "options": {}
        },
        "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.4, "position": [208, 0], "id": "afb14ac5-9686-44af-b0ff-7c6268defbb8", "name": "Start Session",
        "credentials": {"httpHeaderAuth": {"id": "REPLACE_WITH_YOUR_CREDENTIAL_ID", "name": "Header Auth account"}}
      },
      {"parameters": {"amount": 3, "unit": "seconds"}, "type": "n8n-nodes-base.wait", "typeVersion": 1.1, "position": [416, 0], "id": "a1111111-1111-4111-8111-111111111111", "name": "Wait", "webhookId": "b2222222-2222-4222-8222-222222222222"},
      {
        "parameters": {"url": "=https://agp.eu.hcompany.ai/api/v2/sessions/{{ $('Start Session').item.json.id }}/status", "authentication": "genericCredentialType", "genericAuthType": "httpHeaderAuth", "options": {}},
        "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.4, "position": [624, 0], "id": "cdff9632-065d-41a0-b71f-563d70c2eddf", "name": "Poll Status",
        "credentials": {"httpHeaderAuth": {"id": "REPLACE_WITH_YOUR_CREDENTIAL_ID", "name": "Header Auth account"}}
      },
      {
        "parameters": {
          "conditions": {
            "options": {"caseSensitive": true, "leftValue": "", "typeValidation": "strict", "version": 2},
            "conditions": [{"id": "c3333333-3333-4333-8333-333333333333", "leftValue": "={{ ['completed','failed','timed_out','interrupted'].includes($json.status) }}", "rightValue": "", "operator": {"type": "boolean", "operation": "true", "singleValue": true}}],
            "combinator": "and"
          },
          "options": {}
        },
        "type": "n8n-nodes-base.if", "typeVersion": 2.2, "position": [832, 0], "id": "d4444444-4444-4444-8444-444444444444", "name": "Session finished?"
      },
      {
        "parameters": {"url": "=https://agp.eu.hcompany.ai/api/v2/sessions/{{ $('Start Session').item.json.id }}", "authentication": "genericCredentialType", "genericAuthType": "httpHeaderAuth", "options": {}},
        "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.4, "position": [1040, -96], "id": "72eccd6a-4d0e-4f55-9809-ba7708d8760b", "name": "Read Answer",
        "credentials": {"httpHeaderAuth": {"id": "REPLACE_WITH_YOUR_CREDENTIAL_ID", "name": "Header Auth account"}}
      }
    ],
    "connections": {
      "When clicking 'Execute workflow'": {"main": [[{"node": "Start Session", "type": "main", "index": 0}]]},
      "Start Session": {"main": [[{"node": "Wait", "type": "main", "index": 0}]]},
      "Wait": {"main": [[{"node": "Poll Status", "type": "main", "index": 0}]]},
      "Poll Status": {"main": [[{"node": "Session finished?", "type": "main", "index": 0}]]},
      "Session finished?": {"main": [[{"node": "Read Answer", "type": "main", "index": 0}], [{"node": "Wait", "type": "main", "index": 0}]]}
    },
    "pinData": {},
    "meta": {}
  }
  ```
</Accordion>

## Event-driven alternative

Instead of polling, get a [webhook](/agents-api/webhooks/overview) when a session changes status. The same pattern works with Make, Zapier, Pipedream, or any tool that can make HTTP requests.

<Steps>
  <Step title="Add a Webhook trigger node in n8n">
    Copy its Production URL.
  </Step>

  <Step title="Register the URL">
    Call [Create webhook](/agents-api/webhooks/create) with that URL. Subscribe to `session.completed` and `session.failed`, or to `session.status_updated` for every transition (see the [event catalog](/agents-api/webhooks/events)).
  </Step>

  <Step title="Handle the delivery">
    Each delivery is a signed `POST` with `session_id`, `status`, and `previous_status`. The same event can arrive more than once: [verify the signature](/agents-api/webhooks/overview#verifying-deliveries), skip event ids you've already processed, and fetch the session for the authoritative state.
  </Step>
</Steps>

Related: [Create a session](/agents-api/sessions/create), [Session status](/agents-api/sessions/status), [SDKs](/agents-api/sdks)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.