Chat SDK

💭 PageIndex Chat API (beta)

The PageIndex Chat API (beta) allows you to have conversations with your PageIndex-processed documents, with the ability to scope to specific documents. You can also try the Chat service directly in our PageIndex Chat platform .

Chat with Documents

Parameters

Name	Type	Required	Description	Default
messages	`Array<{ role: string; content: string }>`	yes	Conversation messages with ‘role’ and ‘content’ keys.	-
stream	`boolean`	no	Enable streaming responses for real-time output.	false
doc_id	`string` or `string[]`	no	Document ID(s) to scope the conversation. Can be a single ID or array of IDs.	-
temperature	`number`	no	Sampling temperature (0.0 to 1.0). Lower is more deterministic.	-
stream_metadata	`boolean`	no	If true with stream=true, return chunks with intermediate metadata.	false
enable_citations	`boolean`	no	Enable inline citations in responses (e.g., `<doc=file.pdf;page=1>`).	false

Non-Streaming Chat

Example Request with Single Document


const response = await client.api.chatCompletions({
  messages: [
    { role: "user", content: "What are the key findings in this document?" }
  ],
  doc_id: "pi-abc123def456",
});
 
console.log(response.choices[0].message.content);

Example Request with Multiple Documents


const response = await client.api.chatCompletions({
  messages: [
    { role: "user", content: "Compare the findings across these documents" }
  ],
  doc_id: ["pi-abc123def456", "pi-xyz789ghi012"],
});
 
console.log(response.choices[0].message.content);

Example Response


{
  "id": "chatcmpl-xyz789",
  "object": "chat.completion",
  "created": 1234567890,
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Based on the document, the key findings are..."
    },
    "finish_reason": "end_turn"
  }],
  "usage": {
    "prompt_tokens": 1234,
    "completion_tokens": 567,
    "total_tokens": 1801
  }
}

Streaming Chat

Stream PageIndex Chat API responses in real-time for better user experience.

Example Request


const stream = await client.api.chatCompletions({
  messages: [
    { role: "user", content: "Summarize this document" }
  ],
  doc_id: "pi-abc123def456",
  stream: true,
});
 
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content ?? "";
  if (content) {
    process.stdout.write(content);
  }
}

Example with Multi-Turn Conversation


const stream = await client.api.chatCompletions({
  messages: [
    { role: "user", content: "What is the main topic of this document?" },
    { role: "assistant", content: "The main topic is climate change and its effects on agriculture." },
    { role: "user", content: "What solutions does it propose?" },
  ],
  doc_id: "pi-abc123def456",
  stream: true,
});
 
for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content ?? "";
  if (content) {
    process.stdout.write(content);
  }
}

Advanced: Streaming with Intermediate Metadata

Track tool calls and intermediate steps using raw streaming mode.

Example Request


const stream = await client.api.chatCompletions({
  messages: [
    { role: "user", content: "What are the main findings?" }
  ],
  doc_id: "pi-abc123def456",
  stream: true,
  stream_metadata: true,
});
 
for await (const chunk of stream) {
  // Check for metadata about tool calls
  const metadata = chunk.block_metadata;
  if (metadata) {
    const blockType = metadata.type;
 
    // Tool call started
    if (blockType === "mcp_tool_use_start") {
      console.log(`\n[Searching document using ${metadata.tool_name}]\n`);
    }
 
    // Tool result received
    if (blockType === "mcp_tool_result_start") {
      console.log("\n[Retrieved relevant content]\n");
    }
  }
 
  // Get content
  const content = chunk.choices[0]?.delta?.content ?? "";
  if (content) {
    process.stdout.write(content);
  }
}

Available Block Types

text_block_start / text_stop - Text content blocks
mcp_tool_use_start / mcp_tool_use_stop - PageIndex tool being called
mcp_tool_result_start / mcp_tool_result_stop - Tool results received

With Citations

Enable inline citations to trace answers back to source pages:


const response = await client.api.chatCompletions({
  messages: [
    { role: "user", content: "What are the revenue numbers?" }
  ],
  doc_id: "pi-abc123def456",
  enable_citations: true,
});
 
// Response may include citations like: <doc=report.pdf;page=15>
console.log(response.choices[0].message.content);

Want to build a customized agentic retrieval API by prompting the Chat API? See this notebook for an example.

Document Management

Before chatting, you may want to check document status and metadata. See Document Processing for:

client.api.getDocument() — Check processing status
client.api.listDocuments() — List all documents