Chat endpoint

The chat endpoint provides an interactive conversational interface with AI-powered search and research capabilities. It returns streaming responses with structured blocks for a rich chat experience.

Endpoint

http://localhost:3000/api/chat

Replace localhost:3000 with your Perplexica instance URL if running on a different host or port.

Request body

object

required

The message object containing the user’s input and metadata.

Show properties

string

required

A unique identifier for this message.

string

required

The ID of the chat conversation.

string

required

The message content from the user.

object

required

Defines the chat model to be used. Get available providers and models from the /api/providers endpoint.

Show properties

string

required

The UUID of the provider.

string

required

The model key/identifier (e.g., gpt-4o-mini).

object

required

Defines the embedding model for similarity-based searching.

Show properties

string

required

The UUID of the embedding provider.

string

required

The embedding model key (e.g., text-embedding-3-large).

string

required

Optimization mode to control performance and quality balance. Available values: speed, balanced, quality.

array

default:[]

Which search sources to enable. Available values: web, academic, discussions.

array

default:[]

An array of message pairs representing the conversation history. Each pair consists of a role (either human or assistant) and the message content.

array

default:[]

An array of file IDs to include in the context for this message.

string

default:""

Custom instructions to guide the AI’s response. Set to null or empty string for default behavior.

Response

The chat endpoint returns a streaming response with Content-Type: text/event-stream. Each line contains a newline-delimited JSON object representing different types of events.

Stream event types

object

A new content block has been created. Contains the block object with its initial state.

object

An existing block has been updated.

Show properties

string

The ID of the block being updated.

object

A JSON patch object describing the changes to apply to the block.

object

Indicates that the research phase is complete and the AI is ready to generate the final response.

object

Indicates the message stream has completed successfully.

object

An error occurred during processing.

Show properties

any

Error details.

Request example

curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "messageId": "msg-123",
      "chatId": "chat-456",
      "content": "What is the latest news about AI?"
    },
    "chatModel": {
      "providerId": "550e8400-e29b-41d4-a716-446655440000",
      "key": "gpt-4o-mini"
    },
    "embeddingModel": {
      "providerId": "550e8400-e29b-41d4-a716-446655440000",
      "key": "text-embedding-3-large"
    },
    "optimizationMode": "balanced",
    "sources": ["web"],
    "history": [],
    "files": [],
    "systemInstructions": ""
  }'

const response = await fetch('http://localhost:3000/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: {
      messageId: 'msg-123',
      chatId: 'chat-456',
      content: 'What is the latest news about AI?'
    },
    chatModel: {
      providerId: '550e8400-e29b-41d4-a716-446655440000',
      key: 'gpt-4o-mini'
    },
    embeddingModel: {
      providerId: '550e8400-e29b-41d4-a716-446655440000',
      key: 'text-embedding-3-large'
    },
    optimizationMode: 'balanced',
    sources: ['web'],
    history: [],
    files: [],
    systemInstructions: ''
  })
});

// Handle streaming response
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n').filter(line => line.trim());
  
  for (const line of lines) {
    const event = JSON.parse(line);
    console.log(event);
  }
}

import requests
import json

response = requests.post(
    'http://localhost:3000/api/chat',
    json={
        'message': {
            'messageId': 'msg-123',
            'chatId': 'chat-456',
            'content': 'What is the latest news about AI?'
        },
        'chatModel': {
            'providerId': '550e8400-e29b-41d4-a716-446655440000',
            'key': 'gpt-4o-mini'
        },
        'embeddingModel': {
            'providerId': '550e8400-e29b-41d4-a716-446655440000',
            'key': 'text-embedding-3-large'
        },
        'optimizationMode': 'balanced',
        'sources': ['web'],
        'history': [],
        'files': [],
        'systemInstructions': ''
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        event = json.loads(line)
        print(event)

Response example

{"type":"block","block":{"id":"block-1","type":"text","content":""}}
{"type":"updateBlock","blockId":"block-1","patch":{"content":"Here are the latest "}}
{"type":"updateBlock","blockId":"block-1","patch":{"content":"Here are the latest developments in AI..."}}
{"type":"researchComplete"}
{"type":"messageEnd"}

All request body fields must pass validation. The endpoint uses Zod schemas to validate input and will return detailed error messages for invalid requests.

Error responses

Bad Request

Returned if the request body is invalid or missing required fields. The response will include detailed error information with field paths and validation messages.

Internal Server Error

Returned if an error occurs while processing the chat request.

Getting Started

Endpoints

Advanced

Endpoint

Request body

Response

Stream event types

Request example

Response example

Error responses

​Endpoint

​Request body

​Response

​Stream event types

​Request example

​Response example

​Error responses

Endpoint

Request body

Response

Stream event types

Request example

Response example

Error responses