Skip to main content

​
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

  • Browse the full REST API Reference for detailed parameter docs and the interactive playground.
  • Visit the Console to manage your assistants.
  • Join our Discord if you have questions.