API reference

Every call, its request and its answer.

Base address: https://assistant-gateway-399603337787.me-central2.run.app/v1/agent. Send the agent's API key as Authorization: Bearer hai_ag_…. Requests and answers are JSON unless noted. Every error is {"error": "<code>", "message": "…"}, with the HTTP status (see Limits and errors).

Call	What it does
`GET /v1/agent`	The agent and its groups.
`GET /v1/agent/chats`	Its chats, newest first (200): `id`, `type`, a group's `name`, and for a direct chat `with` (the person's `uid` and `name`). The list may be up to 30 seconds old.
`POST /v1/agent/chats/{chat}/messages`	Send text, a poll, a location or a contact card.
`POST /v1/agent/chats/{chat}/media`	Send a photo, video, GIF, voice note, file or sticker (multipart).
`GET /v1/agent/chats/{chat}/messages/{id}/media`	Download a message's media (add `?variant=thumbnail` for its picture).
`PUT /v1/agent/chats/{chat}/messages/{id}/reaction`	`{"emoji": "👍"}`; empty removes it.
`PATCH /v1/agent/chats/{chat}/messages/{id}`	Edit its own text within 15 minutes: `{"text": "…"}`.
`DELETE /v1/agent/chats/{chat}/messages/{id}`	Delete for everyone: its own within 5 minutes, anyone's as a group admin.
`POST /v1/agent/chats/{chat}/messages/{id}/vote`	Vote on a poll: `{"options": [0, 2]}`; empty withdraws.
`GET /v1/agent/chats/{chat}/messages/{id}/votes`	A poll's results (up to 10 seconds old).
`POST /v1/agent/chats/{chat}/typing`	Show the agent typing for a few seconds.
`POST /v1/agent/groups`	Make a group with the agent as creator and admin: `{"name": "…"}`.
`POST /v1/agent/groups/{group}/close`	Remove everyone from a group it made, then leave.
`POST /v1/agent/groups/{group}/sync`	Keep the members in line with a list (Managing members).
`GET /v1/agent/runs/{run}`	A sync's outcome.

Sending text

POST /v1/agent/chats/{chat}/messages
{"text": "Welcome, @Sara!", "reply_to": "M3x…",
 "mentions": [{"uid": "u1", "offset": 9, "length": 5}]}
→ 201 {"id": "Q8b…", "chat": "{chat}"}

Mention offsets and lengths are in UTF-16 units of the text. "uid": "all" mentions everyone.

A poll

{"poll": {"question": "Lunch?", "options": ["Kabsa", "Salad"], "multiple": false,
          "hide_voters": false, "ends_at": "2026-10-24T12:00:00Z"}}

A location, a contact card

{"location": {"lat": 24.7136, "lng": 46.6753, "name": "HUMAIN HQ", "address": "Riyadh"}}
{"contact": {"name": "IT Help Desk", "phones": ["+966112345678"], "emails": ["it@example.com"]}}

Media

curl -X POST https://assistant-gateway-399603337787.me-central2.run.app/v1/agent/chats/{chat}/media \
  -H "Authorization: Bearer $HAI_AGENT_KEY" \
  -F type=image -F caption="This week's menu" -F file=@menu.jpg

Form fields: file (required), type (image, video, gif, audio, file, sticker; guessed when absent), caption, file_name, duration (seconds, for audio that is not M4A or WAV), waveform (comma-separated 0 to 100), poster (a JPEG for a video), reply_to.