Generate Assistant Message

Embed the assistant, trained on your docs, into any application

POST /discovery/v2/assistant/{domain}/message

cURL

curl -X POST https://api.mintlify.com/discovery/v2/assistant/your-domain/message \
  -H "Authorization: Bearer mint_dsc_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "fp": "anonymous",
    "messages": [
      {
        "id": "msg1",
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "How do I get started?"
          }
        ]
      }
    ],
    "retrievalPageSize": 5
  }'

200 Response

{
  "type": "streaming",
  "description": "Streaming response compatible with AI SDK v5. Use the useChat hook from @ai-sdk/react to handle the response stream."
}

Generates a response message from the assistant for the specified domain. Compatible with AI SDK v5+. This endpoint enables you to embed Mintlify’s AI assistant into your product, support portal, or internal tools.

This is the v2 endpoint compatible with AI SDK v5+. If you use AI SDK v4, see the deprecated v1 endpoint in the source documentation.

Authentication

Requires an assistant API key (prefixed with mint_dsc_). Generate one on the API keys page in your dashboard.

The assistant API key is a public token that you can reference in frontend code.

Calls using the assistant API token can incur costs: either using your assistant credits or incurring overages.

Path Parameters

domain · string · required

The domain identifier from your domain.mintlify.app URL. Can be found at the end of your dashboard URL. For example, dashboard.mintlify.com/organization/domain has a domain identifier of domain.

Body Parameters

fp · string · required

Fingerprint identifier for tracking conversation sessions. Use anonymous for anonymous users or provide a unique user identifier.

messages · array · required

Array of messages in the conversation. Use the handleSubmit function from the @ai-sdk/react package’s useChat hook to manage messages and streaming responses.

Show Message object

id · string · required

Unique identifier for the message.

role · string · required

The role of the message sender. Possible values: system, assistant, user.

parts · array · required

Array of message parts. Each part has a type and type-specific fields (e.g., text, reasoning, source-url, file, step-start).

createdAt · string

Timestamp when the message was created (ISO 8601 format).

metadata · object

Optional metadata associated with the message.

threadId · string

An optional identifier used to maintain conversation continuity across multiple messages. When provided, it allows the system to associate follow-up messages with the same conversation thread. The threadId is returned in the response as event.threadId when event.type === 'finish'.

retrievalPageSize · number · default: 5

Number of documentation search results to use for generating the response. Higher values provide more context but may increase response time. Recommended: 5.

filter · object

Optional filter criteria for the search.

Show Filter object

version · string

Optional version filter.

language · string

Optional language filter.

groups · array

Optional array of group identifiers to filter results.

context · array

Optional array of contextual information to provide to the assistant.

Show Context object

type · string · required

The type of context being provided. Possible values: code, textSelection.

value · string · required

The code snippet or selected text content.

path · string

Optional path to the source file or page.

elementId · string

Optional identifier for the UI element containing the context.

currentPath · string

The path of the page the user is currently viewing. When provided, the assistant uses this context to provide more relevant answers. Maximum length: 200 characters.

Rate limits

The assistant API has the following limits:

• 10,000 uses per key per month
• 10,000 requests per Mintlify organization per hour
• 10,000 requests per IP per day

Integration with useChat

The useChat hook from Vercel’s AI SDK is the recommended way to integrate the assistant API into your application.

cURL

curl -X POST https://api.mintlify.com/discovery/v2/assistant/your-domain/message \
  -H "Authorization: Bearer mint_dsc_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "fp": "anonymous",
    "messages": [
      {
        "id": "msg1",
        "role": "user",
        "parts": [
          {
            "type": "text",
            "text": "How do I get started?"
          }
        ]
      }
    ],
    "retrievalPageSize": 5
  }'

200 Response

{
  "type": "streaming",
  "description": "Streaming response compatible with AI SDK v5. Use the useChat hook from @ai-sdk/react to handle the response stream."
}