API Reference

The Hiloop REST API lets agents create sessions, send messages with composable components, and manage conversations with humans.

Base URL

https://api.hi-loop.com/v1

Authentication

Agents

Pass your API key in the X-API-Key header. Keys start with hlp_. 

curl -H "X-API-Key: hlp_your_api_key" \
  https://api.hi-loop.com/v1/agent/sessions
Humans

Pass a JWT in the Authorization header. 

curl -H "Authorization: Bearer eyJhbG..." \
  https://api.hi-loop.com/v1/human/feed

Session endpoints

Sessions are the primary API for agent-human communication. Agents create sessions, send messages with composable component trees, and manage participants. Authenticated with X-API-Key.

Method Path Description
POST /v1/agent/sessions Create session
GET /v1/agent/sessions List sessions
GET /v1/agent/sessions/:id Get session
POST /v1/agent/sessions/:id/messages Send message (with components)
GET /v1/agent/sessions/:id/timeline Get timeline
POST /v1/agent/sessions/:id/close Close session
POST /v1/agent/sessions/:id/archive Archive session
POST /v1/agent/sessions/:id/participants Add participant
GET /v1/agent/sessions/:id/participants List participants
POST /v1/agent/sessions/:id/guest-tokens Create guest token
POST /v1/agent/sessions/:id/typing Send typing indicator

Send message

Send a POST to send a message with optional composable components. The server returns the created message object.

Request 
POST /v1/agent/sessions/:id/messages
Content-Type: application/json
X-API-Key: hlp_your_api_key

{
  "encryptedContent": "...",
  "encryptedComponents": "...",
  "responseRequired": true,
  "priority": "High"
}
Response (201 Created) 
{
  "id": "a1b2c3d4-5678-4000-8000-000000000001",
  "sessionId": "b2c3d4e5-6789-4000-8000-000000000002",
  "senderType": "Agent",
  "senderAgentId": "c3d4e5f6-789a-4000-8000-000000000003",
  "encryptedContent": { "ciphertext": "...", "wrappings": [...] },
  "encryptedComponents": { "ciphertext": "...", "wrappings": [...] },
  "responseRequired": true,
  "status": "Pending",
  "priority": "High",
  "createdAt": "2026-03-25T10:30:00.000Z"
}

Note: encryptedContent and encryptedComponents are returned as encrypted envelopes. SDKs decrypt these automatically. Components use a composable ComponentNode tree for rich UI (buttons, forms, progress, approvals, etc.).

Message object

Session message endpoints return objects with this shape:

Field Type Description
id string (UUID) Unique identifier
sessionId string (UUID) Parent session
senderType string Agent, Human, or System
senderAgentId string (UUID) | null Agent ID (if sent by agent)
encryptedContent encrypted Encrypted text content envelope
encryptedComponents encrypted | null Encrypted ComponentNode tree (buttons, forms, progress, etc.)
responseRequired boolean Whether a human response is expected
status string Pending, Completed, Cancelled, Expired
priority string Low, Medium, High, Urgent
deadlineAt ISO 8601 | null Deadline (if set)
createdAt ISO 8601 Creation timestamp

Interaction endpoints (Legacy)

These endpoints are maintained for backward compatibility. New integrations should use sessions and messages above.

Legacy interaction endpoints for structured agent-to-human requests. Authenticated with X-API-Key.

Method Path Description
POST /v1/agent/interactions Create interaction
GET /v1/agent/interactions List interactions
GET /v1/agent/interactions/:id Get interaction
GET /v1/agent/interactions/:id/await Long-poll for response
POST /v1/agent/interactions/:id/cancel Cancel interaction
POST /v1/agent/interactions/:id/acknowledge Acknowledge interaction
POST /v1/agent/interactions/:id/messages Send message
GET /v1/agent/interactions/:id/messages List messages
POST /v1/agent/interactions/:id/blocks Push content blocks

Pagination

List endpoints support pagination via query parameters:

Parameter Default Description
page 1 Page number
pageSize 20 Items per page (max 100)

Responses include a total field with the total number of matching records.

Example 
GET /v1/agent/sessions?page=2&pageSize=10

{
  "data": [...],
  "total": 47,
  "page": 2,
  "pageSize": 10
}

Error responses

All errors follow a standard format with an HTTP status code and a JSON body:

Error response 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'encryptedContent' is required"
  }
}
Status Meaning
400 Bad request (validation error)
401 Missing or invalid authentication
403 Insufficient permissions
404 Resource not found
429 Rate limited
500 Internal server error

Full OpenAPI specification

The complete OpenAPI specification is available at /openapi.json on the API server, with interactive documentation at /docs.

OpenAPI JSON Swagger UI