> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Messaging

> Send messages to your assistant programmatically via the REST API.

<Note>
  New here? Start with the [Product Overview](/basics/overview) or watch the [demo videos](/basics/demos).
</Note>

## Authentication

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

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

You can find your API key and assistant id in the [Console](https://console.unify.ai).

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`:

```bash theme={null}
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:

```json theme={null}
{
  "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"`:

```bash theme={null}
curl https://api.unify.ai/v0/messages/msg_abc123 \
  -H "Authorization: Bearer $UNIFY_KEY"
```

Once complete, the `response` field contains the assistant's reply:

```json theme={null}
{
  "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:**

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```bash theme={null}
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](https://console.unify.ai) to manage your assistants.
* Join our [Discord](https://discord.com/invite/sXyFF8tDtm) if you have questions.