API Messaging

Send messages to your assistant programmatically via the REST API.

New here? Start with the Product Overview or watch the demo videos.

Authentication

All API requests require a Bearer token. Pass your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

You can find your API key and assistant id in the Console.

The base URL for all endpoints is:

https://api.unify.ai/v0

Sending a Message

To send a message to your assistant, make a POST request to /messages:

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

The response includes a message_id you can use to poll for the assistant’s reply:

{
  "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-03-08T12:00:00Z",
    "completed_at": null
  }
}

Polling for a Response

The assistant processes your message asynchronously. Poll GET /messages/{message_id} until status changes from "processing" to "completed":

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

Once complete, the response field contains the assistant’s reply:

{
  "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-03-08T12:00:00Z",
    "completed_at": "2026-03-08T12:00:05Z"
  }
}

Sending Attachments

To include files with your message, first upload each file via POST /messages/attachments, then reference them in the message.

Step 1 — 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=42"

This returns metadata for the uploaded file:

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

Step 2 — Send the message with attachments:

Pass the returned metadata in the attachments array:

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

Then poll for the response as before. You can attach up to 10 files per message.

Tags

You can attach tags to messages for routing and context. Tags are arbitrary strings — use them however you like:

curl -X POST https://api.unify.ai/v0/messages \
  -H "Authorization: Bearer $UNIFY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": 42,
    "message": "Summarise today'\''s sales figures.",
    "tags": ["source:slack", "channel:#analytics"]
  }'

Tags are echoed back in the response as response_tags, so you can use them to route replies back to the right place.

Next Steps

• Visit the Console to manage your assistants.
• Join our Discord if you have questions.