Skip to main content
The REST API works with any programming language or platform. Send HTTP requests to track conversations and receive analysis results.

​
Authentication

All requests require an API key in the Authorization header: 
Authorization: Bearer your-api-key
Get your API key from the chatbot settings page under the API Keys tab.

​
Base URL

https://api.openbat.dev/v1

​
Track a conversation

Endpoint: POST /v1/track Request body: 
{
  "conversationId": "conv-abc-123",
  "messages": [
    {
      "role": "user",
      "content": "How do I reset my password?"
    },
    {
      "role": "assistant",
      "content": "Go to Settings > Security and click 'Reset password'."
    }
  ],
  "user": {
    "id": "user-456",
    "email": "jane@acme.com",
    "name": "Jane Smith"
  },
  "organization": {
    "id": "org-789",
    "name": "Acme Corp"
  },
  "metadata": {
    "plan": "pro",
    "source": "web-chat"
  }
}

​
cURL example

curl -X POST https://api.openbat.dev/v1/track \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "conversationId": "conv-abc-123",
    "messages": [
      {"role": "user", "content": "How do I reset my password?"},
      {"role": "assistant", "content": "Go to Settings > Security and click Reset password."}
    ],
    "user": {"id": "user-456", "email": "jane@acme.com"},
    "organization": {"id": "org-789", "name": "Acme Corp"}
  }'

​
Response

A successful request returns: 
{
  "success": true,
  "conversationId": "conv-abc-123"
}
Error responses:
StatusDescription
400Invalid request body (missing required fields)
401Invalid or missing API key
429Rate limit exceeded
500Internal server error

​
Request body reference

FieldTypeRequiredDescription
conversationIdstringYesUnique conversation identifier
messagesarrayYesArray of message objects
messages[].rolestringYesEither "user" or "assistant"
messages[].contentstringYesThe message text
userobjectNoUser information
user.idstringRecommendedUnique user identifier
user.emailstringRecommendedUser email address
user.namestringNoUser display name
organizationobjectNoOrganization information
organization.idstringRecommendedUnique organization identifier
organization.namestringRecommendedOrganization display name
metadataobjectNoCustom key-value metadata
Including user and organization data unlocks user-level and org-level analytics on your dashboard. Custom metadata fields are auto-discovered and can be tracked in analysis configuration.

​
Rate limits

Rate limits vary by plan. If you receive a 429 response, reduce your request frequency or contact support@openbat.dev for higher limits.