Create a session

curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent": {},
  "messages": [
    {}
  ],
  "max_steps": 123,
  "max_time_s": 123,
  "idle_timeout_s": 123,
  "group_id": "<string>",
  "parent_session_id": "<string>",
  "answer_format": {}
}
'

{
  "id": "<string>",
  "request": {},
  "status": {},
  "created_at": "<string>"
}

POST

api

sessions

Create a session

curl --request POST \
  --url https://agp.eu.hcompany.ai/api/v2/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent": {},
  "messages": [
    {}
  ],
  "max_steps": 123,
  "max_time_s": 123,
  "idle_timeout_s": 123,
  "group_id": "<string>",
  "parent_session_id": "<string>",
  "answer_format": {}
}
'

{
  "id": "<string>",
  "request": {},
  "status": {},
  "created_at": "<string>"
}

Creates a new session that runs an agent against the given task. The session starts in pending status and transitions to running once the agent launches. Returns the created Session object with status pending.

Headers

Idempotency-Key

string

Optional idempotency key (max 128 characters). Safe retry within 24 hours: reusing the same key with a different body returns 422.

Request body

agent

string | object

required

Either a catalog identifier (string, e.g. "h/web-surfer-holo3-1-35b") or an inline Agent object. An inline agent must include its own environments (at most one per kind), unless it is a pure manager that only delegates to subagents; the session resolves only agent and reads everything else (environments, skills, subagents) from there.Using a catalog id (environments come from the agent’s stored spec):

"agent": "h/web-surfer-holo3-1-35b"

Inline agent, with environments nested under it:

"agent": {
  "name": "weather-agent",
  "description": "Looks up weather by city",
  "environments": [
    {
      "id": "browser",
      "kind": "web",
      "headless": true,
      "width": 1280,
      "height": 720,
      "start_url": "https://www.bing.com/"
    }
  ]
}

See Browser for its config and fields.

messages

array

Initial messages queued before the agent’s first step. Usually a single user message describing the task.Each message has:

type (string): "user_message"
message (string): The instruction or task description.
images (array, optional): Base64 data URIs to attach (e.g. data:image/png;base64,...).
caller_id (string, optional): Identifies the message sender. Defaults to user; leave it unset for normal user input.

"messages": [
  {"type": "user_message", "message": "Book a flight from Paris to Tokyo on June 15"}
]

max_steps

integer

Cap on the number of steps the agent may take, where each step is one decide-and-act cycle. On reaching the cap the agent is asked to produce a final answer from what it has so far (it is not hard-killed), so you still get a structured result. Defaults to a runtime value when omitted.

max_time_s

number

Cap on wall-clock seconds. On reaching the cap, like max_steps, the agent is asked for a final answer rather than terminated abruptly. Omit it to run uncapped.

idle_timeout_s

integer

Switches between one-shot and interactive. Leave it null for a one-shot task: the session ends as soon as the agent answers. Set it (in seconds) to keep the session open for follow-up messages: after each answer the session enters the idle status and waits this long for your next message before terminating.

group_id

string

Tag for grouping related sessions. You can later query all sessions with GET /sessions?group_id=....

parent_session_id

string

ID of a parent session, for multi-agent orchestration. The parent’s status endpoint will include this session in its subagent_session_ids list.

answer_format

object

A JSON Schema the final answer must conform to. When set, the agent returns structured data matching the schema instead of free-form text, and answer is an object rather than a string. Leave it null for free-form text.

"answer_format": {
  "type": "object",
  "properties": {
    "stories": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {"title": {"type": "string"}, "url": {"type": "string"}},
        "required": ["title", "url"]
      }
    }
  },
  "required": ["stories"]
}

Response

string

Unique session identifier.

request

object

The original session request body.

status

object

Session status object with status: "pending" for a newly created session.

created_at

string

ISO 8601 timestamp.

Examples

Basic session

Reference a catalog agent; its stored spec supplies the environments:

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "h/web-surfer-holo3-1-35b",
    "messages": [
      {"type": "user_message", "message": "Find the best-rated sushi restaurants in San Francisco"}
    ]
  }'

Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "request": {
    "agent": "h/web-surfer-holo3-1-35b",
    "messages": [
      {"type": "user_message", "message": "Find the best-rated sushi restaurants in San Francisco"}
    ]
  },
  "status": {
    "status": "pending",
    "error": null,
    "steps": 0,
    "usage_per_model": [],
    "subagent_session_ids": []
  },
  "created_at": "2026-05-07T14:30:00Z",
  "started_at": null,
  "finished_at": null
}

With idempotency key

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-unique-key-123" \
  -d '{
    "agent": "h/web-surfer-holo3-1-35b",
    "messages": [
      {"type": "user_message", "message": "Search for direct flights from CDG to NRT on June 15"}
    ]
  }'

With an inline agent and explicit browser environment

Pass an inline Agent instead of a catalog id when you want to override the environments (or any other field) on a per-session basis. Environments must be nested under agent.

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "name": "web-price-finder",
      "description": "Web browsing agent with a custom browser config",
      "environments": [
        {"id": "browser", "kind": "web", "headless": true, "width": 1280, "height": 720, "start_url": null}
      ]
    },
    "messages": [
      {"type": "user_message", "message": "Open the spreadsheet on the desktop and create a summary of Q2 sales"}
    ]
  }'

Child session (multi-agent)

curl -X POST https://agp.eu.hcompany.ai/api/v2/sessions \
  -H "Authorization: Bearer $H_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "h/web-surfer-holo3-1-35b",
    "parent_session_id": "parent-session-uuid",
    "group_id": "trip-planning-001",
    "messages": [
      {"type": "user_message", "message": "Find hotels near Shinjuku station under $150/night"}
    ]
  }'

Errors

Status	Cause
`409`	An `Idempotency-Key` from a still in-flight request was reused before it completed. Retry after `Retry-After`.
`422`	Request body failed validation, or an `Idempotency-Key` was reused with a different body.
`429`	Concurrency quota exceeded. See Rate limits.

Delete Status

​Headers

​Request body

​Response

​Examples

​Basic session

​With idempotency key

​With an inline agent and explicit browser environment

​Child session (multi-agent)

​Errors

Headers

Request body

Response

Examples

Basic session

With idempotency key

With an inline agent and explicit browser environment

Child session (multi-agent)

Errors