API Reference

Complete API reference for Quadrillian integration. All server-to-server API calls require your workspace's API key.

Base URL: https://quadrillian.com/api/chat
Authentication: API key required for all server-to-server calls
Content-Type: application/json

API Key Authentication

Include your API key in the request headers:

// Required headers for all API calls
api_key_name: your-api-key-name
api_key_val: your-api-key-value
Content-Type: application/json
                

Example with curl:
curl -H "api_key_name: your-api-key-name" -H "api_key_val: your-api-key-value" -H "Content-Type: application/json" ...

Authentication Endpoints

JWT Authentication Flow

The Quadrillian system uses JWT tokens for secure chat widget authentication.

What is a JWT?
A JWT (JSON Web Token) is a secure way to send information between parties. It contains:

Header: Algorithm used for signing (e.g., HS256)
Payload: The actual data (user info, expiration, etc.) - base64 encoded
Signature: A cryptographic signature that proves the token is authentic

The payload contains the user information in base64-encoded format, and the signature ensures the token hasn't been tampered with. When quadrillian.com receives the JWT, it can decode the payload to extract the user information and verify the signature to ensure authenticity.

Here's how the authentication flow works:

Complete Flow:

Your backend generates a JWT containing user info and signs it with your workspace secret
Your frontend gets the JWT from your backend
Quadrillian JS library calls quadrillian.com with the JWT to authenticate the user
quadrillian.com verifies the JWT and signs the user into chat

POST https://quadrillian.com/api/chat/auth/verify

Purpose

This endpoint is hosted on quadrillian.com and called by the Quadrillian JS library (running in the browser) to verify JWT tokens and authenticate users. The quadrillian.com server validates that:

The JWT was signed with the correct workspace secret
The JWT hasn't expired
The workspace ID in the JWT matches the signing secret

Important: This endpoint does NOT require API key authentication. It's designed to be called directly by the Quadrillian JS library from the browser.

API Request

The Quadrillian JS library sends the JWT token in the request body to quadrillian.com. The JWT already contains all the user data, so the request body only needs the JWT string:

// What the Quadrillian JS library sends to quadrillian.com
// The JWT string contains the user data inside it
{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJjdXN0b21lcl91c2VyX2lkIjoiMTIzNCIsIndvcmtzcGFjZV9pZCI6NDU2LCJleHBpcmVzX3RzIjoxNzA0MDY3MjAwfQ.signature"
}
                

Note: The JWT string above contains the user data (external_user_id, workspace_id, email, name, exp) encoded inside it. quadrillian.com will decode the JWT to extract this information.

JWT Token Structure

Before the Quadrillian JS library sends the JWT to quadrillian.com, your backend must create a JWT with this exact payload structure:

// What your backend puts inside the JWT (before signing)
{
  "workspace_id": 456,
  "external_user_id": "1234",
  "email": "user@example.com",
  "name": "John Doe",
  "iat": 1704067200,
  "exp": 1704153600
}
                

JWT Payload Fields:

workspace_id: Number - Your Quadrillian workspace ID (e.g., 456)
external_user_id: String - Your internal user ID (e.g., "1234", "user_abc123")
email: String - User's email address (optional, used for linking existing users)
name: String - User's display name (optional)
iat: Number - Issued at timestamp (when token was created)
exp: Number - Unix timestamp when token expires (recommended: 24 hours from now)

Signing: The JWT must be signed with your workspace secret using HS256 algorithm.

API Response

If the JWT is valid, quadrillian.com returns the user information:

// Success response from quadrillian.com
{
  "status": "ok",
  "user": {
    "user_id": 789,
    "user_email": "user@example.com",
    "user_name": "John Doe",
    "external_user_id": "1234"
  },
  "workspace_id": 456,
  "key_used": "production-key"
}
                

Error Responses

If something goes wrong, quadrillian.com returns an error:

// Invalid JWT signature
{
  "status": "error",
  "message": "JWT token verification failed with all available keys"
}

// Expired JWT
{
  "status": "error",
  "message": "JWT token has expired"
}

// Workspace mismatch
{
  "status": "error",
  "message": "No active JWT keys found for this workspace"
}

// Malformed request
{
  "status": "error",
  "message": "JWT token is required"
}
                

CORS Support: This endpoint supports CORS (Cross-Origin Resource Sharing) because the Quadrillian JS library runs in the browser on your website (e.g., yoursite.com) but needs to make requests to quadrillian.com. Without CORS, browsers would block these cross-origin requests for security reasons. The quadrillian.com server validates the JWT signature using your workspace secret and ensures the workspace ID matches.

User Provisioning

User provisioning happens automatically when users authenticate with JWT tokens. No separate API calls are required.

✅ Automatic User Provisioning: When a user authenticates with a JWT token via the /api/chat/auth/verify endpoint, Quadrillian automatically handles user creation and management.

How Automatic User Provisioning Works

When the JWT verification endpoint processes a valid token, it automatically:

Looks up the user by external_user_id and workspace_id
If user doesn't exist:
- Checks if a user with the same email already exists
- If found, links the existing user to your workspace with the external_user_id
- If not found, creates a new user with the provided information
Returns the user information for the chat widget to use

Benefits of Automatic Provisioning:

No need for separate user management API calls
Handles user linking automatically (same email = same user)
Works seamlessly with your existing user system
Reduces integration complexity

JWT Token Requirements for User Provisioning

To enable automatic user provisioning, include these fields in your JWT token:

// JWT payload for automatic user provisioning
{
  "workspace_id": 456,
  "external_user_id": "1234", // Required: Your internal user ID
  "email": "user@example.com", // Optional: For user linking
  "name": "John Doe", // Optional: Display name
  "exp": 1704153600
}
                

Topic Management

Manage chat topics using external keys for easy integration:

GET /api/topic/external-key

Look up a topic by its external key. This endpoint is used by the chat widget to resolve external keys to internal topic IDs.

Parameters

external_key (query parameter) - The external key for the topic (e.g., "support-general")
workspace_id (query parameter) - The workspace ID containing the topic

// Example request
GET /api/topic/external-key?external_key=support-general&workspace_id=456
                

Response

// Success response
{
  "status": "ok",
  "topic": {
    "topic_id": 123,
    "topic_external_key": "support-general",
    "topic_name": "General Support",
    "p2p_workspace_id": 456
  }
}
                

Topic Creation

POST /api/topic/create

Create a new topic with an external key. This endpoint requires JWT authentication and should be called from your backend server.

Parameters

external_key (required) - The external key for the topic (e.g., "support-ticket-12345")
workspace_id (required) - The workspace ID containing the topic
topic_name (optional) - Display name for the topic (defaults to external_key)
ai_user_id (optional) - AI user ID to automatically add to the topic

// Example request with AI user
POST /api/topic/create
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "external_key": "support-ticket-12345",
  "workspace_id": 456,
  "topic_name": "Support Request #12345",
  "ai_user_id": 5267
}
                

Set User and Topic (SDK Endpoint)

POST /api/chat/set-user-and-topic

Create or resolve a topic and ensure the user has access. This is the main endpoint used by the SDK for topic management. Automatically creates topics and users as needed.

Parameters

external_key (required) - The external key for the topic
workspace_id (required) - The workspace ID containing the topic
topic_name (optional) - Display name for the topic (defaults to external_key)
ai_user_id (optional) - AI user ID to automatically add to the topic

// Example request with AI user
POST /api/chat/set-user-and-topic
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "external_key": "support-ticket-12345",
  "workspace_id": 456,
  "topic_name": "Support Request #12345",
  "ai_user_id": 5267
}
                

Add User to Topic

POST /api/topic/add-user

Add a user to an existing topic. This endpoint requires JWT authentication and should be called from your backend server.

Parameters

external_key (required) - The external key for the topic
workspace_id (required) - The workspace ID containing the topic
user_id (optional) - User ID to add (defaults to the authenticated user from JWT)

// Example request
POST /api/topic/add-user
Authorization: Bearer <jwt_token>
Content-Type: application/json

{
  "external_key": "support-ticket-12345",
  "workspace_id": 456
}
                

⚠️ Security: All topic management operations must be performed from your backend server with proper JWT authentication. Never allow frontend users to directly create topics or add users.

Error Responses

All API endpoints return consistent error responses:

// Error response format
{
  "error": "error_code",
  "message": "Human readable error message",
  "details": {
    "field": "Additional error details"
  }
}
                

Common Error Codes

INVALID_API_KEY - API key is missing or invalid
INVALID_JWT - JWT token is malformed or expired
WORKSPACE_MISMATCH - JWT workspace ID doesn't match the signing secret
USER_NOT_FOUND - User doesn't exist in the workspace
TOPIC_NOT_FOUND - Topic doesn't exist or user doesn't have access
RATE_LIMITED - Too many requests, please slow down
INVALID_REQUEST - Request body is malformed or missing required fields
UNAUTHORIZED - User doesn't have permission for this action

Rate Limiting: API calls are rate limited to prevent abuse. If you receive a RATE_LIMITED error, wait a few seconds before retrying.