API messages

Every other channel puts a person at one end — a phone, an inbox, a chat window. This one puts your code there instead. Send your assistant a message with an HTTP request, poll for its reply, and wire it into whatever you’re building. No browser, no phone number, no connected account — just your API key. It’s the same assistant either way. Something you ask for over the API is something you can follow up on in Chat an hour later, and it’ll know what you mean.

What you need

Your API key and your assistant’s ID, both from the Console.
The base URL: https://api.unify.ai/v0
A Bearer token header on every request:

Authorization: Bearer YOUR_API_KEY

Assistants running in a local deployment don’t receive API messages — this channel is for assistants hosted by Unify.

Sending a message

POST /messages with the assistant’s ID and your message:

curl -X POST https://api.unify.ai/v0/messages \
  -H "Authorization: Bearer $UNIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": <your-assistant-id>,
    "message": "Add milk to my shopping list."
  }'

You get back a message_id straight away, before your assistant has done anything with it:

{
  "info": {
    "message_id": "msg_abc123",
    "assistant_id": 42,
    "message": "Add milk to my shopping list.",
    "status": "processing",
    "response": null,
    "tags": [],
    "attachments": [],
    "response_tags": null,
    "response_attachments": null,
    "created_at": "2026-08-10T12:00:00Z",
    "completed_at": null
  }
}

Polling for the reply

Your assistant works on the message in the background — it might answer in a second, or go off and actually do the thing first. Poll GET /messages/{message_id} until status flips from processing to completed:

curl https://api.unify.ai/v0/messages/msg_abc123 \
  -H "Authorization: Bearer $UNIFY_KEY"

{
  "info": {
    "message_id": "msg_abc123",
    "assistant_id": 42,
    "message": "Add milk to my shopping list.",
    "status": "completed",
    "response": "Done! I've added milk to your shopping list.",
    "tags": [],
    "attachments": [],
    "response_tags": [],
    "response_attachments": null,
    "created_at": "2026-08-10T12:00:00Z",
    "completed_at": "2026-08-10T12:00:05Z"
  }
}

response can come back null on a completed message. That’s not an error — your assistant decides whether a reply is warranted, the same way it does on any other channel, and sometimes doing the task quietly is the right answer.

From Python

The SDK wraps both calls:

import unisdk

status = unisdk.agent.send_message(
    assistant_id=<your-assistant-id>,
    message="Add milk to my shopping list.",
)

status = unisdk.agent.get_message_status(status["message_id"])
print(status["status"], status["response"])

Sending files

Upload each file first, then reference it in the message.

Upload the file

curl -X POST https://api.unify.ai/v0/messages/attachments \
  -H "Authorization: Bearer $UNIFY_KEY" \
  -F "file=@report.pdf" \
  -F "assistant_id=<your-assistant-id>"

You get back the file’s metadata:

{
  "id": "att_xyz789",
  "filename": "report.pdf",
  "gs_url": "gs://bucket/path/report.pdf",
  "content_type": "application/pdf",
  "size_bytes": 204800
}

Send the message with the attachment

curl -X POST https://api.unify.ai/v0/messages \
  -H "Authorization: Bearer $UNIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": <your-assistant-id>,
    "message": "Please summarise this report.",
    "attachments": [
      {
        "id": "att_xyz789",
        "filename": "report.pdf",
        "gs_url": "gs://bucket/path/report.pdf"
      }
    ]
  }'

Files are capped at 25 MB each. Your assistant can send files back too — they arrive as response_attachments on the completed message, each with a download URL.

Getting Started

Local Deployment

Communication

Workspace

Integrations

Tasks

Learning

Canvas

Their Computer

Your Computer

Teams

Hiring

API messages

What you need

Sending a message

Polling for the reply

From Python

Sending files

Tags

​What you need

​Sending a message

​Polling for the reply

​From Python

​Sending files

​Tags

What you need

Sending a message

Polling for the reply

From Python

Sending files

Tags