Chat API

Overview

The Chat API allows you to query your Trainly knowledge base using natural language. It supports multiple AI models, streaming responses, and custom prompts with citation-backed answers.

All responses are powered by semantic search over your documents with GPT-4, Claude, or other AI models.

Authentication

Chat API endpoints require a valid API key from your chat settings:

Authorization: Bearer tk_your_api_key_here

Make sure API access is enabled in your chat settings and the chat has published settings before using these endpoints.

Answer Question

Standard Response

Query your knowledge base with a question and receive an AI-generated answer with citations:

POST /v1/{chat_id}/answer_question

curl -X POST https://api.trainlyai.com/v1/chat_abc123/answer_question \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What are the main findings from the research?",
    "selected_model": "gpt-4o-mini",
    "temperature": 0.7,
    "max_tokens": 1000
  }'

Path Parameters

chat_id

string

required

The ID of your chat/knowledge base

Request Body

question

string

required

The question to ask about your documents

selected_model

string

AI model to use. Options: gpt-4o-mini (default), gpt-4o, gpt-4, claude-3-sonnet, claude-3-opus

temperature

number

default:0.7

Sampling temperature (0.0 to 2.0). Higher values make output more random.

max_tokens

integer

default:1000

Maximum tokens in the response

custom_prompt

string

Optional custom system prompt to override default behavior

scope_filters

object

Filter results by custom scopes (e.g., {"playlist_id": "xyz"})

Response

{
  "answer": "Based on the research documents, the main findings are:\n\n1. The primary hypothesis was confirmed [^0]\n2. Secondary effects were observed [^1][^2]\n3. Future research directions include [^3]",
  "context": [
    {
      "chunk_id": "doc1_chunk_0",
      "chunk_text": "The primary hypothesis states that...",
      "score": 0.94
    },
    {
      "chunk_id": "doc1_chunk_5",
      "chunk_text": "Secondary observations revealed...",
      "score": 0.89
    }
  ],
  "chat_id": "chat_abc123",
  "model": "gpt-4o-mini",
  "usage": {
    "prompt_tokens": 1250,
    "completion_tokens": 342,
    "total_tokens": 1592
  }
}

Response Fields

answer

string

The AI-generated answer with inline citations (e.g., [^0], [^1])

context

array

Array of source chunks used to generate the answer, ordered by relevance

Show Context Object Properties

chunk_id

string

Unique identifier for the chunk

chunk_text

string

The actual text content from your documents

score

number

Relevance score (0.0 to 1.0)

chat_id

string

The chat ID that was queried

model

string

The AI model used for generation

usage

object

Token usage statistics for the request

Streaming Response

Get real-time streaming responses for a better user experience:

POST /v1/{chat_id}/answer_question_stream

curl -X POST https://api.trainlyai.com/v1/chat_abc123/answer_question_stream \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "question": "Explain the methodology used",
    "selected_model": "gpt-4o-mini"
  }'

Response Format (Server-Sent Events)

data: {"type": "content", "data": "Based"}

data: {"type": "content", "data": " on"}

data: {"type": "content", "data": " the"}

data: {"type": "content", "data": " methodology"}

data: {"type": "end"}

Event Types

content

event

Chunk of the AI response text

{"type": "content", "data": "text chunk"}

context

event

Source chunks used (sent at the beginning)

{
  "type": "context",
  "data": [
    {
      "chunk_id": "...",
      "chunk_text": "...",
      "score": 0.92
    }
  ]
}

end

event

Signals the end of the stream

{"type": "end"}

error

event

Error occurred during streaming

{"type": "error", "data": "Error message"}

Chat Information

Get Chat Info

Retrieve metadata about a chat:

GET /v1/{chat_id}/info

curl -X GET https://api.trainlyai.com/v1/chat_abc123/info \
  -H "Authorization: Bearer tk_your_api_key"

Response

{
  "chat_id": "chat_abc123",
  "title": "Research Analysis",
  "created_at": 1609459200000,
  "has_api_access": true,
  "visibility": "private",
  "context_files": 12,
  "api_version": "1.0.0"
}

Health Check

API Health Status

Check if the API is operational:

GET /v1/health

curl -X GET https://api.trainlyai.com/v1/health

Response

{
  "status": "healthy",
  "timestamp": 1609459200,
  "version": "1.0.0",
  "services": {
    "neo4j": "connected",
    "openai": "configured"
  }
}

Internal Endpoints

These endpoints are used internally by the Trainly dashboard and require additional authentication:

Create Nodes and Embeddings

POST /create_nodes_and_embeddings

curl -X POST https://api.trainlyai.com/create_nodes_and_embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "pdf_text": "Document content here...",
    "pdf_id": "unique_file_id",
    "chat_id": "chat_abc123",
    "filename": "research.pdf",
    "scope_values": {"workspace_id": "ws_123"}
  }'

This endpoint is for internal use. Use the V1 file upload endpoints for external integrations.

Standard Query (Internal)

POST /answer_question

curl -X POST https://api.trainlyai.com/answer_question \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is the conclusion?",
    "chat_id": "chat_abc123",
    "selected_model": "gpt-4o-mini",
    "temperature": 0.7,
    "max_tokens": 1000,
    "custom_prompt": "Optional custom prompt",
    "scope_filters": {}
  }'

Streaming Query (Internal)

POST /answer_question_stream

curl -X POST https://api.trainlyai.com/answer_question_stream \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Summarize the findings",
    "chat_id": "chat_abc123",
    "selected_model": "gpt-4o-mini"
  }'

Model Selection

Trainly supports multiple AI models with different capabilities and pricing:

OpenAI Models

gpt-4o-mini (Recommended)

Fastest and most cost-effective
Great for most use cases
1x credit multiplier (baseline)

gpt-4o

Advanced reasoning capabilities
Better for complex analysis
15x credit multiplier

gpt-4-turbo

High performance
Extended context window
12x credit multiplier

gpt-4

Most powerful OpenAI model
Best quality responses
18x credit multiplier

Anthropic Claude Models

claude-3-haiku

Fast and efficient
Similar to gpt-4o-mini
1x credit multiplier

claude-3-sonnet

Balanced performance
Good for analysis tasks
8x credit multiplier

claude-3.5-sonnet

Latest Sonnet version
Improved capabilities
10x credit multiplier

claude-3-opus

Most powerful Claude model
Best for complex reasoning
20x credit multiplier

Google Gemini Models

gemini-pro

Good general purpose model
3x credit multiplier

gemini-1.5-pro

Extended context window
4x credit multiplier

Advanced Features

Custom Prompts

Override the default system prompt to customize AI behavior:

{
  "question": "Analyze the data",
  "custom_prompt": "You are a data scientist. Analyze the following information with a focus on statistical significance and practical implications. Always cite your sources using [^N] notation."
}

Scope Filtering

Filter results to specific subsets of your data:

{
  "question": "What features were added?",
  "scope_filters": {
    "playlist_id": "playlist_abc",
    "version": "2.0"
  }
}

Conversation History

The API automatically uses published chat settings including conversation history limits:

History Limit: Configurable per chat (default: 20 messages)
Context Preservation: Recent messages are included for continuity
Token Management: Automatically managed to stay within model limits

Published Settings

Important: External API calls only work with published chat settings. You must publish your chat configuration before API access works.

When you publish chat settings, the following are locked for API use:

AI Model: The model selection for all API queries
Temperature: Response randomness setting
Max Tokens: Maximum response length
Custom Prompt: System instructions for the AI
Conversation History Limit: How many previous messages to include
Context Files: Which documents are accessible

Publishing Settings

Go to your chat settings
Configure your preferred model, prompt, and other options
Click “Publish Settings”
Enable API access
Generate an API key

If settings aren’t published, API calls will return: "This chat has no published settings. Please publish your chat settings first to enable API access."

Citation Format

Trainly uses inline citations in markdown format:

The research shows promising results [^0]. Further analysis revealed [^1][^2].

Key findings include:

1. Primary outcome was significant [^0]
2. Secondary effects were observed [^3]
3. No adverse events reported [^4]

Citations correspond to the context array indices in the response.

Best Practices

Use Streaming

Streaming provides better UX for long responses

Set Appropriate Limits

Use max_tokens to control response length and costs

Handle Rate Limits

Implement exponential backoff for rate limit errors

Cache Responses

Cache common queries to reduce API calls

Error Handling Example

async function queryTrainly(question, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(
        `https://api.trainlyai.com/v1/${chatId}/answer_question`,
        {
          method: "POST",
          headers: {
            Authorization: `Bearer ${apiKey}`,
            "Content-Type": "application/json",
          },
          body: JSON.stringify({ question }),
        },
      );

      if (response.status === 429) {
        // Rate limited - wait and retry
        const retryAfter = response.headers.get("Retry-After") || 60;
        await new Promise((resolve) => setTimeout(resolve, retryAfter * 1000));
        continue;
      }

      if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise((resolve) =>
        setTimeout(resolve, 1000 * Math.pow(2, i)),
      );
    }
  }
}

Error Codes

400 Bad Request

error

Invalid request parameters or unpublished settings

401 Unauthorized

error

Invalid or missing API key

403 Forbidden

error

API access not enabled for this chat

404 Not Found

error

Chat not found

413 Payload Too Large

error

Request body exceeds size limit

429 Too Many Requests

error

Rate limit exceeded

500 Internal Server Error

error

Server error - contact support if persistent

Overview

Authentication

Core APIs

Endpoint Examples

Overview

Authentication

Answer Question

Standard Response

Streaming Response

Chat Information

Get Chat Info

Health Check

API Health Status

Internal Endpoints

Create Nodes and Embeddings

Standard Query (Internal)

Streaming Query (Internal)

Model Selection

Advanced Features

Custom Prompts

Scope Filtering

Conversation History

Published Settings

Publishing Settings

Citation Format

Best Practices

Use Streaming

Set Appropriate Limits

Handle Rate Limits

Cache Responses

Error Handling Example

Error Codes

Overview

Authentication

Core APIs

Endpoint Examples

​Overview

​Authentication

​Answer Question

​Standard Response

​Streaming Response

​Chat Information

​Get Chat Info

​Health Check

​API Health Status

​Internal Endpoints

​Create Nodes and Embeddings

​Standard Query (Internal)

​Streaming Query (Internal)

​Model Selection

​Advanced Features

​Custom Prompts

​Scope Filtering

​Conversation History

​Published Settings

​Publishing Settings

​Citation Format

​Best Practices

Use Streaming

Set Appropriate Limits

Handle Rate Limits

Cache Responses

​Error Handling Example

​Error Codes

Overview

Authentication

Answer Question

Standard Response

Streaming Response

Chat Information

Get Chat Info

Health Check

API Health Status

Internal Endpoints

Create Nodes and Embeddings

Standard Query (Internal)

Streaming Query (Internal)

Model Selection

Advanced Features

Custom Prompts

Scope Filtering

Conversation History

Published Settings

Publishing Settings

Citation Format

Best Practices

Error Handling Example

Error Codes