Skip to main content

​
Conversations API

The Conversations API allows you to retrieve conversation history for users.

​
Endpoints

MethodEndpointDescription
GET/api/ai/conversationsList user’s conversations
GET/api/ai/conversations/{id}Get conversation details

​
List Conversations

Retrieve a list of conversations for the current user.
​
Authorization
string
required
API key with ApiKey prefix
​
X-External-Org-Id
string
required
Your client’s organization identifier
​
X-External-User-Id
string
required
The user whose conversations to list
​
X-External-Roles
string
required
JSON array of user’s roles

​
Query Parameters

​
limit
integer
default:"20"
Maximum number of conversations to return (1-100)
​
offset
integer
default:"0"
Number of conversations to skip for pagination

​
Example Request

curl -X GET "https://api.docbit.ai/api/ai/conversations?limit=10" \
  -H "Authorization: ApiKey sk_yourpartner_abc123..." \
  -H "X-External-Org-Id: acme" \
  -H "X-External-User-Id: user-456" \
  -H "X-External-Roles: [\"employee\"]"

​
Response

{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Vacation policy questions",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:45:00Z",
      "messageCount": 4
    },
    {
      "id": "660e8400-e29b-41d4-a716-446655440001",
      "title": "Benefits enrollment",
      "createdAt": "2024-01-14T14:20:00Z",
      "updatedAt": "2024-01-14T14:25:00Z",
      "messageCount": 2
    }
  ],
  "total": 15,
  "limit": 10,
  "offset": 0
}

​
Response Fields

FieldTypeDescription
conversationsarrayList of conversation summaries
totalintegerTotal number of conversations
limitintegerRequested limit
offsetintegerRequested offset

​
Conversation Summary Object

FieldTypeDescription
idstringConversation identifier
titlestringAuto-generated title
createdAtstringISO 8601 timestamp
updatedAtstringLast message timestamp
messageCountintegerNumber of messages

​
Get Conversation

Retrieve full conversation details including all messages.

​
Example Request

curl -X GET "https://api.docbit.ai/api/ai/conversations/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: ApiKey sk_yourpartner_abc123..." \
  -H "X-External-Org-Id: acme" \
  -H "X-External-User-Id: user-456" \
  -H "X-External-Roles: [\"employee\"]"

​
Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Vacation policy questions",
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:45:00Z",
  "messages": [
    {
      "id": "msg-001",
      "role": "user",
      "content": "What is our vacation policy?",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "msg-002",
      "role": "assistant",
      "content": "According to the Employee Handbook, full-time employees receive 15 days of paid vacation per year...",
      "citations": [
        {
          "documentId": "doc-abc123",
          "documentTitle": "Employee Handbook",
          "page": 12,
          "excerpt": "Full-time employees are entitled to 15 days..."
        }
      ],
      "confidence": "High",
      "createdAt": "2024-01-15T10:30:15Z"
    },
    {
      "id": "msg-003",
      "role": "user",
      "content": "How do I request time off?",
      "createdAt": "2024-01-15T10:35:00Z"
    },
    {
      "id": "msg-004",
      "role": "assistant",
      "content": "To request time off, you should submit a request through the HR portal at least 2 weeks in advance...",
      "citations": [
        {
          "documentId": "doc-abc123",
          "documentTitle": "Employee Handbook",
          "page": 14,
          "excerpt": "Time off requests must be submitted..."
        }
      ],
      "confidence": "High",
      "createdAt": "2024-01-15T10:35:12Z"
    }
  ]
}

​
Message Object

FieldTypeDescription
idstringMessage identifier
rolestringuser or assistant
contentstringMessage content
citationsarraySources (assistant only)
confidencestringConfidence level (assistant only)
createdAtstringISO 8601 timestamp

​
Code Examples

​
JavaScript

async function getConversations(orgId, userId, roles) {
  const response = await axios.get(
    'https://api.docbit.ai/api/ai/conversations',
    {
      headers: {
        'Authorization': `ApiKey ${API_KEY}`,
        'X-External-Org-Id': orgId,
        'X-External-User-Id': userId,
        'X-External-Roles': JSON.stringify(roles)
      },
      params: { limit: 20 }
    }
  );
  
  return response.data.conversations;
}

async function getConversation(conversationId, orgId, userId, roles) {
  const response = await axios.get(
    `https://api.docbit.ai/api/ai/conversations/${conversationId}`,
    {
      headers: {
        'Authorization': `ApiKey ${API_KEY}`,
        'X-External-Org-Id': orgId,
        'X-External-User-Id': userId,
        'X-External-Roles': JSON.stringify(roles)
      }
    }
  );
  
  return response.data;
}

​
Python

def get_conversations(org_id, user_id, roles, limit=20):
    response = requests.get(
        'https://api.docbit.ai/api/ai/conversations',
        headers={
            'Authorization': f'ApiKey {API_KEY}',
            'X-External-Org-Id': org_id,
            'X-External-User-Id': user_id,
            'X-External-Roles': ','.join(roles)
        },
        params={'limit': limit}
    )
    response.raise_for_status()
    return response.json()['conversations']

def get_conversation(conversation_id, org_id, user_id, roles):
    response = requests.get(
        f'https://api.docbit.ai/api/ai/conversations/{conversation_id}',
        headers={
            'Authorization': f'ApiKey {API_KEY}',
            'X-External-Org-Id': org_id,
            'X-External-User-Id': user_id,
            'X-External-Roles': ','.join(roles)
        }
    )
    response.raise_for_status()
    return response.json()

​
User Isolation

Conversations are scoped to users. Each user only sees their own conversations:
  • User A cannot access User B’s conversations
  • The X-External-User-Id determines which user’s data is accessed
  • Attempting to access another user’s conversation returns 404

​
Error Responses

StatusErrorDescription
404Conversation not foundInvalid ID or no access
401Invalid API keyAuthentication failed
400Missing required headerRequired header not provided
See Error Codes for complete error documentation.