Attachments & tags

Attach files

Upload each file first, then send the ids with the message.

POST /attachments
x-lex-client: my-app
Content-Type: application/json

{ "name": "q3-report.pdf", "mediaType": "application/pdf", "data": "<base64>" }

{ "id": "att_1", "name": "q3-report.pdf", "mediaType": "application/pdf", "size": 182044, "createdAt": "…" }

POST /agent-runs
{ "botId": "bot_123", "message": "What are the three biggest risks in this report?", "attachmentIds": ["att_1"] }

Types	Images (image/png, image/jpeg, image/gif, image/webp), PDF (application/pdf) and text (text/*, JSON, YAML, XML, SQL, code)
Size	Up to 10 MB per file
Per message	Up to 5 files

The model reads images and PDFs directly, and text files as text. Each file can be sent with one message; reusing it fails with VALIDATION_FAILED.

• GET /attachments/{id}/content downloads a file. Only its owner can. Images are served inline; everything else downloads, so files never render as web pages.
• DELETE /attachments/{id} removes a file that hasn't been sent.
• Sent messages list their files: GET /conversations/{id}/messages includes attachments: [{ id, name, mediaType, size }].

Tag connectors, plugins and Mini Programs

Point the bot at specific capabilities with mentions:

POST /agent-runs
{
  "botId": "bot_123",
  "message": "Summarise my unread email",
  "mentions": [{ "type": "connector", "ref": "gmail", "name": "Gmail" }]
}

type	ref
connector	Connector slug, e.g. gmail (from GET /catalog/connectors)
plugin	Plugin id (from GET /catalog/plugins)
mini_program	Mini Program slug (from GET /catalog/mini-programs)

Up to 10 tags per message. A tagged connector's tools are always offered to the bot for that message, ahead of anything else.

When something isn't set up

If a tagged connector isn't connected, or a tagged plugin isn't installed, the bot doesn't start working. It replies straight away, without spending any model usage, and asks you to set it up. The run completes with stopReason: "needs_setup", and the reply message carries actions:

{
  "role": "assistant",
  "content": "Before I start, I need you to connect Gmail. Shall we do that now? …",
  "actions": [{ "kind": "connect", "type": "connector", "ref": "gmail", "name": "Gmail" }]
}

Show a button for each action:

• connect: start the connect flow for ref. Pass returnTo so sign-in comes back to your chat.
• install: install the plugin with POST /plugin-installations (workspace owners and admins).

When everything is ready, send a follow-up such as "Gmail is ready. Please continue." with the same mentions; the bot picks up the original request from the chat. To go on without something, send the message without that tag.

Mini Programs never need setup.