Skip to main content
Launch a session, watch it move through a predictable lifecycle, steer it while it runs, and read the result when it finishes. Every follow-up call (sending a message, pausing, cancelling) is addressed to the session’s id. Optional max_steps and max_time_s caps bound how long it runs before the agent is asked for a final answer. 
SESSION=$(curl -s -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": "Top 3 stories on Hacker News?"}]}' | jq -r .id)
echo "$SESSION"
Launch returns the session id; from there you poll its progress and read the answer exactly as in the Quickstart.
The session object carries progress and usage, not the result. The agent’s final answer comes from GET /sessions/{id}/changes (answer) or the answer_event in the event stream. For live updates, long-poll changes rather than polling status.

​
What’s a Session

FieldDescription
idThe session’s UUID, the handle for every follow-up call.
requestEchoes what you submitted, with agent resolved to its full spec even if you passed a catalog id.
statusCarries the live status, step count, per-model token usage (usage_per_model), any error, and subagent_session_ids. See Session status for the breakdown.
created_at / started_at / finished_atTrack the run’s timeline; the latter two are null until they happen.

​
Lifecycle

The agent perceives and acts in its environment step by step, moving through the same state machine regardless of which agent runs it. While it runs you can steer with messages or lifecycle controls.
Prefer a UI? Watch any session live, or replay it afterward, in the H Platform.
StatusMeaningTerminal
pendingSession created, agent is launching.No
runningAgent is actively working on the task.No
pausedManually paused via the API. State is preserved.No
idleInteractive agent finished a task and is waiting for your next message.No
completedAgent finished the task successfully.Yes
timed_outAgent exceeded the maximum allowed time.Yes
interruptedSession was canceled via DELETE.Yes
failedAn unrecoverable error occurred.Yes

​
Structured output

By default the agent’s answer is free-form text. Pass an answer_format (a JSON Schema) when you create the session and the agent returns data that conforms to it: the answer you read from changes is then a JSON object instead of a string. 
# Launch with a schema...
SESSION=$(curl -sX 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": "Top 3 stories on Hacker News right now?"}],
    "answer_format": {
      "type": "object",
      "properties": {
        "stories": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {"title": {"type": "string"}, "url": {"type": "string"}},
            "required": ["title", "url"]
          }
        }
      },
      "required": ["stories"]
    }
  }' | jq -r .id)

# ...then read the structured answer once it lands.
curl -s "https://agp.eu.hcompany.ai/api/v2/sessions/$SESSION/changes" \
  -H "Authorization: Bearer $H_API_KEY" | jq .answer

​
Endpoints

MethodPathDescription
POST/api/v2/sessionsCreate a session
GET/api/v2/sessionsList sessions
GET/api/v2/sessions/{id}Retrieve a session
GET/api/v2/sessions/{id}/statusGet session status
DELETE/api/v2/sessions/{id}Cancel a session
POST/api/v2/sessions/{id}/messagesSend a message
POST/api/v2/sessions/{id}/pausePause a session
POST/api/v2/sessions/{id}/resumeResume a session
POST/api/v2/sessions/{id}/force_answerForce final answer
GET/api/v2/sessions/{id}/changesLong-poll for changes
GET/api/v2/sessions/{id}/eventsList events
GET/api/v2/sessions/quotaGet quota
POST/api/v2/sessions/{id}/feedbackSubmit session feedback
POST / DELETE/api/v2/sessions/{id}/shareShare / unshare a session
GET/api/v2/sessions/{id}/resources/{bucket}/{key}Get a session resource