---
title: "Assistant API Reference"
description: "Context-aware assistant that delegates to specialized sub-assistants based on the resource being edited."
canonical: "https://linkbreakers.com/help/api/assistant"
---

# Assistant

Context-aware assistant that delegates to specialized sub-assistants based on the resource being edited.

## Assistant

## [#](#assistant-object)The AssistantDisplayMessageAttachment is a file attached to a message object

AssistantDisplayMessageAttachment is a file attached to a message

mimeType

string

name

string

Example object

```json
{
  "mimeType": "string",
  "name": "string"
}
```

GET

`/v1/assistant/conversation`

Requires auth

## [#](#get-assistant-conversation)Get assistant conversation

Get the display-ready chat history for a specific context. Requires the \`assistant:read\` scope.

### [#](#get-assistant-conversation-parameters)Parameters

#### query parameters

contextType

string

query

dashboard id — the dashboard does not exist yet while the user and the assistant are still agreeing on what it should show. Once it exists, editing it happens under ASSISTANT\_CONTEXT\_TYPE\_ANALYTICS\_DASHBOARD instead. the WORKSPACE id: this thread is not about any one link, dashboard or design, and every capability the resource-scoped assistants have is available from it. One conversation per workspace, so it survives navigation.

##### Allowed values

`ASSISTANT_CONTEXT_TYPE_LINK_ANALYTICS`

Building a link's analytics dashboard. context\_id is the LINK id, not a

`ASSISTANT_CONTEXT_TYPE_WORKSPACE`

The workspace-wide assistant, with no resource selected. The context id is

contextId

string

query

### [#](#get-assistant-conversation-response)Response

200

Everything worked as expected.

messages

array<object>

unreadCount

integer (int32)

Assistant messages in this conversation the member has not seen yet.

### [#](#get-assistant-conversation-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X GET "https://api.linkbreakers.com/v1/assistant/conversation?contextType={contextType}&contextId={contextId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Typical response

```json
{
  "messages": [
    {
      "attachments": [
        {}
      ],
      "id": "string",
      "readAt": "2026-10-22T22:05:12.820Z",
      "sender": "string",
      "text": "string",
      "timestamp": "2026-10-22T22:05:12.820Z",
      "uiActions": [
        {}
      ]
    }
  ],
  "unreadCount": 0
}
```

Base URL: `https://api.linkbreakers.com`

POST

`/v1/assistant/conversation/read`

Requires auth

## [#](#mark-assistant-conversation-read)Mark assistant conversation read

Record that the member has seen every assistant reply in this conversation. Call it when the thread is actually on screen, not when history is fetched. Requires the \`assistant:write\` scope.

### [#](#mark-assistant-conversation-read-parameters)Parameters

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#mark-assistant-conversation-read-request)Request body

contextId

string

contextType

string (enum)

dashboard id — the dashboard does not exist yet while the user and the assistant are still agreeing on what it should show. Once it exists, editing it happens under ASSISTANT\_CONTEXT\_TYPE\_ANALYTICS\_DASHBOARD instead. the WORKSPACE id: this thread is not about any one link, dashboard or design, and every capability the resource-scoped assistants have is available from it. One conversation per workspace, so it survives navigation.

##### Allowed values

`ASSISTANT_CONTEXT_TYPE_UNSPECIFIED`

`ASSISTANT_CONTEXT_TYPE_ANALYTICS_DASHBOARD`

`ASSISTANT_CONTEXT_TYPE_WORKFLOW`

`ASSISTANT_CONTEXT_TYPE_LINK`

`ASSISTANT_CONTEXT_TYPE_QRCODE_DESIGN`

`ASSISTANT_CONTEXT_TYPE_PAGE_THEME`

`ASSISTANT_CONTEXT_TYPE_LINK_ANALYTICS`

Building a link's analytics dashboard. context\_id is the LINK id, not a

`ASSISTANT_CONTEXT_TYPE_WORKSPACE`

The workspace-wide assistant, with no resource selected. The context id is

### [#](#mark-assistant-conversation-read-response)Response

200

Everything worked as expected.

markedCount

integer (int32)

### [#](#mark-assistant-conversation-read-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X POST "https://api.linkbreakers.com/v1/assistant/conversation/read" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{"contextId":"string","contextType":"ASSISTANT_CONTEXT_TYPE_UNSPECIFIED"}'
```

Sample payload (application/json)

```json
{
  "contextId": "string",
  "contextType": "ASSISTANT_CONTEXT_TYPE_UNSPECIFIED"
}
```

Typical response

```json
{
  "markedCount": 0
}
```

Base URL: `https://api.linkbreakers.com`

POST

`/v1/assistant/upload`

Requires auth

## [#](#upload-file-for-assistant-chat)Upload file for assistant chat

Upload a small file, base64 encoded, to attach to the next assistant message. Returns a temporary file ID. Larger files go through CreateAttachmentUpload. Requires the \`assistant:write\` scope.

### [#](#upload-file-for-assistant-chat-parameters)Parameters

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#upload-file-for-assistant-chat-request)Request body

content

string

File content (base64-encoded in JSON)

mimeType

string

MIME type (e.g. "image/png", "application/pdf")

name

string

Original filename

### [#](#upload-file-for-assistant-chat-response)Response

200

Everything worked as expected.

fileId

string

Temporary file ID to include in assistant message attachments

mimeType

string

MIME type (echoed back)

name

string

Original filename (echoed back)

### [#](#upload-file-for-assistant-chat-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X POST "https://api.linkbreakers.com/v1/assistant/upload" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{"content":"string","mimeType":"string","name":"string"}'
```

Sample payload (application/json)

```json
{
  "content": "string",
  "mimeType": "string",
  "name": "string"
}
```

Typical response

```json
{
  "fileId": "string",
  "mimeType": "string",
  "name": "string"
}
```

Base URL: `https://api.linkbreakers.com`

POST

`/v1/assistant/uploads`

Requires auth

## [#](#start-a-direct-attachment-upload)Start a direct attachment upload

Reserve an attachment of up to 50 MB and get a presigned upload\_url to PUT its bytes to, then call CompleteAttachmentUpload. Requires the \`assistant:write\` scope.

### [#](#start-a-direct-attachment-upload-parameters)Parameters

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#start-a-direct-attachment-upload-request)Request body

fileName

string

Required

The file's name, shown with the message and kept if the file is stored as media

mimeType

string

The file's MIME type. Empty is application/octet-stream. An image (PNG, JPEG, WebP, SVG), PDF or MP4 video must really be that format.

size

integer (int64)

Required

The file's exact size in bytes, at most 50 MB. The PUT must send exactly this many bytes.

### [#](#start-a-direct-attachment-upload-response)Response

200

Everything worked as expected.

fileId

string

The attachment's id: what CompleteAttachmentUpload and a message's file ids take

uploadExpiresAt

string (date-time)

When upload\_url stops accepting the file

uploadHeaders

object

Headers the upload must carry, exactly as given. The Content-Length must equal the declared size.

uploadMethod

string

The HTTP method to send them with: always PUT

uploadUrl

string

Where to send the file's bytes, directly to storage. Short-lived.

### [#](#start-a-direct-attachment-upload-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X POST "https://api.linkbreakers.com/v1/assistant/uploads" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{"fileName":"menu.pdf","mimeType":"application/pdf","size":"7340032"}'
```

Sample payload (application/json)

```json
{
  "fileName": "menu.pdf",
  "mimeType": "application/pdf",
  "size": "7340032"
}
```

Typical response

```json
{
  "fileId": "string",
  "uploadExpiresAt": "2026-10-22T22:05:12.820Z",
  "uploadHeaders": {},
  "uploadMethod": "string",
  "uploadUrl": "https://example.com"
}
```

Base URL: `https://api.linkbreakers.com`

POST

`/v1/assistant/uploads/{fileId}:complete`

Requires auth

## [#](#complete-a-direct-attachment-upload)Complete a direct attachment upload

Check the file PUT to the upload\_url and make the attachment ready to send with a message. Requires the \`assistant:write\` scope.

### [#](#complete-a-direct-attachment-upload-parameters)Parameters

#### path parameters

fileId

string

Required

path

The attachment's id, from CreateAttachmentUpload

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#complete-a-direct-attachment-upload-request)Request body

No structured schema available for this section.

### [#](#complete-a-direct-attachment-upload-response)Response

200

Everything worked as expected.

fileId

string

The attachment's id, to include in a message's file ids

mimeType

string

The file's MIME type

name

string

The file's name

size

integer (int64)

The file's size in bytes

### [#](#complete-a-direct-attachment-upload-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X POST "https://api.linkbreakers.com/v1/assistant/uploads/{fileId}:complete" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{}'
```

Sample payload (application/json)

```json
{}
```

Typical response

```json
{
  "fileId": "string",
  "mimeType": "string",
  "name": "string",
  "size": 0
}
```

Base URL: `https://api.linkbreakers.com`

DELETE

`/v1/assistant/conversation`

Requires auth

## [#](#clear-assistant-conversation)Clear assistant conversation

Clear the conversation history for a specific context. Requires the \`assistant:write\` scope.

### [#](#clear-assistant-conversation-parameters)Parameters

#### query parameters

contextType

string

query

dashboard id — the dashboard does not exist yet while the user and the assistant are still agreeing on what it should show. Once it exists, editing it happens under ASSISTANT\_CONTEXT\_TYPE\_ANALYTICS\_DASHBOARD instead. the WORKSPACE id: this thread is not about any one link, dashboard or design, and every capability the resource-scoped assistants have is available from it. One conversation per workspace, so it survives navigation.

##### Allowed values

`ASSISTANT_CONTEXT_TYPE_LINK_ANALYTICS`

Building a link's analytics dashboard. context\_id is the LINK id, not a

`ASSISTANT_CONTEXT_TYPE_WORKSPACE`

The workspace-wide assistant, with no resource selected. The context id is

contextId

string

query

### [#](#clear-assistant-conversation-response)Response

200

Everything worked as expected.

No structured schema available for this section.

### [#](#clear-assistant-conversation-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X DELETE "https://api.linkbreakers.com/v1/assistant/conversation?contextType={contextType}&contextId={contextId}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Typical response

```json
{}
```

Base URL: `https://api.linkbreakers.com`

---

Source: https://linkbreakers.com/help/api/assistant