Document Cognition Service API

Overview

The Document Cognition Service provides AI-powered chat functionality and document analysis capabilities. It processes user queries with document context, supports multiple AI models, and enables intelligent conversations about documents. Key Features:

Stream-based AI chat responses
Document attachment analysis
Multi-model support (Claude, GPT)
Tool-augmented AI interactions
Real-time notification delivery

Architecture:

RESTful HTTP API with streaming endpoints
WebSocket support via connection gateway
Asynchronous AI processing
Integration with search, email, and notification services

Chat Management

Create Chat

curl -X POST https://api.macro.com/v1/chats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Discussion",
    "model": "claude-4-5-sonnet",
    "projectId": "proj_123",
    "attachments": [
      {
        "entityType": "document",
        "entityId": "doc_456"
      }
    ],
    "isPersistent": true
  }'

name

string

Display name for the chat session

model

string

AI model to use. Options: claude-4-5-sonnet, claude-4-5-opus, gpt-4

projectId

string

Project to associate this chat with

attachments

array

Document attachments to include in chat context

isPersistent

boolean

default:"true"

Whether to save chat history

chatId

string

Unique identifier for the created chat

name

string

Chat display name

model

string

AI model configured for this chat

createdAt

timestamp

Chat creation time

Get Chat

Retrieve chat details and metadata.

curl https://api.macro.com/v1/chats/chat_123 \
  -H "Authorization: Bearer YOUR_TOKEN"

chatId

string

Unique chat identifier

name

string

Chat display name

model

string

AI model for this chat

projectId

string

Associated project ID

attachments

array

Documents attached to this chat

messageCount

integer

Total number of messages in chat

Update Chat

curl -X PATCH https://api.macro.com/v1/chats/chat_123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Chat Name",
    "model": "claude-4-5-opus"
  }'

name

string

New chat name

model

string

Switch AI model

projectId

string

Move chat to different project

Delete Chat

Soft-delete a chat (can be reverted).

curl -X DELETE https://api.macro.com/v1/chats/chat_123 \
  -H "Authorization: Bearer YOUR_TOKEN"

AI Chat Streaming

Send Chat Message

Send a message and receive a streaming AI response. The response is delivered via the connection gateway WebSocket.

curl -X POST https://api.macro.com/v1/stream/chat/message \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Summarize the key findings in this document",
    "chatId": "chat_123",
    "model": "claude-4-5-sonnet",
    "attachments": [
      {
        "entityType": "document",
        "entityId": "doc_456",
        "name": "Research Report.pdf"
      }
    ],
    "toolset": "all"
  }'

content

string

required

The user message content

chatId

string

Chat ID. If not provided, a new chat is created automatically

model

string

required

AI model: claude-4-5-sonnet, claude-4-5-opus, gpt-4-turbo

additionalInstructions

string

Custom system instructions appended to the base prompt

attachments

array

Documents to include in the conversation context

toolset

string

default:"all"

Tools available to AI: all, search, email, none

streamId

string

Stream identifier to subscribe to for receiving response chunks

messageId

string

Unique ID for the AI response message

chatId

string

The chat ID (may differ from request if a new chat was created)

Stream Response Format: The WebSocket stream delivers JSON messages with these event types:

{
  "type": "ChatUserMessage",
  "streamId": "stream_123",
  "chatId": "chat_123",
  "messageId": "msg_456",
  "content": "User's message",
  "attachments": []
}

{
  "type": "ChatMessageResponse",
  "streamId": "stream_123",
  "chatId": "chat_123",
  "messageId": "msg_789",
  "content": {
    "Text": { "text": "AI response chunk" }
  }
}

{
  "type": "StreamEnd",
  "streamId": "stream_123"
}

Chat History

Get Chat History

Retrieve message history for a chat.

curl https://api.macro.com/v1/chats/history/chat_123?limit=50 \
  -H "Authorization: Bearer YOUR_TOKEN"

limit

integer

default:"20"

Maximum number of messages to return

before

string

Cursor for pagination - get messages before this ID

messages

array

Array of chat messages

messages[].messageId

string

Unique message identifier

messages[].role

string

Message role: user or assistant

messages[].content

string

Message text content

messages[].createdAt

timestamp

When the message was created

hasMore

boolean

Whether more messages are available

Models

List Available Models

Get list of supported AI models.

curl https://api.macro.com/v1/models \
  -H "Authorization: Bearer YOUR_TOKEN"

models

array

Available AI models

models[].id

string

Model identifier (e.g., claude-4-5-sonnet)

models[].name

string

Human-readable model name

models[].contextWindow

integer

Maximum context size in tokens

Document Attachments

Get Chats for Attachment

Find all chats that reference a specific document.

curl https://api.macro.com/v1/attachments/doc_123/chats \
  -H "Authorization: Bearer YOUR_TOKEN"

chats

array

Chats containing this attachment

chats[].chatId

string

Chat identifier

chats[].name

string

Chat name

chats[].lastMessageAt

timestamp

Most recent message timestamp

Processing Patterns

Async AI Processing

The Document Cognition Service uses asynchronous streaming for AI responses:

Initiate: POST to /stream/chat/message returns streamId
Subscribe: Connect to WebSocket with streamId
Stream: Receive incremental response chunks
Complete: Final StreamEnd event signals completion
Persist: Messages saved to chat history

Tool Integration

AI responses can invoke tools for enhanced capabilities:

Search: Query document search service
Email: Access email content and metadata
Scribe: Document summarization
Soup: Web content extraction

Tools execute during streaming and results are incorporated into AI responses.

Error Handling

error

string

Error message for stream failures

streamId

string

Associated stream ID if available

Common errors:

ModelContextOverflow: Message exceeds model’s context window
InternalError: AI service failure
Unauthorized: Invalid or missing authentication
Forbidden: Insufficient permissions for chat access

Rate Limits

Chat endpoints are subject to user quota limits:

Message rate: Based on user plan
Context size: Model-dependent (see /models)
Concurrent streams: 5 per user

Rate limit headers:

X-RateLimit-Remaining: Messages remaining in quota
X-RateLimit-Reset: Quota reset timestamp

Overview

Core Services

Processing Services

Document Cognition Service API

Overview

Chat Management

Create Chat

Get Chat

Update Chat

Delete Chat

AI Chat Streaming

Send Chat Message

Chat History

Get Chat History

Models

List Available Models

Document Attachments

Get Chats for Attachment

Processing Patterns

Async AI Processing

Tool Integration

Error Handling

Rate Limits

Build docs developers (and LLMs) love

Overview

Core Services

Processing Services

​Overview

​Chat Management

​Create Chat

​Get Chat

​Update Chat

​Delete Chat

​AI Chat Streaming

​Send Chat Message

​Chat History

​Get Chat History

​Models

​List Available Models

​Document Attachments

​Get Chats for Attachment

​Processing Patterns

​Async AI Processing

​Tool Integration

​Error Handling

​Rate Limits

Build docs developers (and LLMs) love

Overview

Chat Management

Create Chat

Get Chat

Update Chat

Delete Chat

AI Chat Streaming

Send Chat Message

Chat History

Get Chat History

Models

List Available Models

Document Attachments

Get Chats for Attachment

Processing Patterns

Async AI Processing

Tool Integration

Error Handling

Rate Limits