Skip to main content

​
Overview

Trainly provides a comprehensive GraphRAG (Graph Retrieval-Augmented Generation) API that enables you to build intelligent applications with privacy-first document processing and AI-powered question answering.

​
API Architecture

The Trainly API is organized into several major categories:

V1 Trusted Issuer API

OAuth-based authentication for external applications with complete user data isolation

Chat API

Query and interact with your knowledge base using AI models

File Management

Upload, process, and manage documents with automatic embedding generation

Scope Management

Advanced data filtering with custom scopes for multi-tenant applications

​
Authentication Methods

Trainly supports multiple authentication approaches depending on your use case: For external applications that want to integrate with Trainly while maintaining complete user privacy: 
# User authenticates with their OAuth provider (Clerk, Auth0, etc.)
# Your app gets an ID token from the OAuth provider
# Send that token to Trainly for validation

curl -X POST https://api.trainlyai.com/v1/me/chats/query \
  -H "Authorization: Bearer <USER_OAUTH_ID_TOKEN>" \
  -H "X-App-ID: app_your_app_id" \
  -H "Content-Type: application/json" \
  -d '{"messages": "[{\"role\": \"user\", \"content\": \"What is AI?\"}]"}'
With V1 auth, users maintain complete control over their data. Files are stored in permanent private subchats that only they can access.

​
2. Chat API Keys

For direct chat access with API keys: 
curl -X POST https://api.trainlyai.com/v1/{chat_id}/answer_question \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"question": "What are the main findings?"}'

​
3. Privacy-First OAuth (Legacy)

For applications requiring stricter privacy controls: 
# Step 1: Get authorization URL
# Step 2: User authorizes
# Step 3: Exchange code for token
# Step 4: Use token for queries

​
Base URLs

https://api.trainlyai.com

​
Rate Limiting

All API endpoints are rate-limited to ensure fair usage:
  • Default: 60 requests per minute per API key
  • Streaming: 30 requests per minute per API key
Rate limit headers are included in all responses: 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1609459200

​
Response Format

All API responses follow a consistent JSON format: 
{
  "success": true,
  "data": {
    // Response data
  },
  "error": null
}
Error responses include detailed information: 
{
  "success": false,
  "data": null,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid chat_id format",
    "details": {}
  }
}

​
Privacy Guarantees

Trainly is built with privacy at its core:
Each user’s data is stored in isolated subchats. Developers can only access AI-generated responses, never raw files or documents.
Citations are automatically filtered based on the access method. Direct user access gets full citations, while developer API calls get limited snippets.
All access attempts are logged for security and compliance purposes.
Users maintain ownership of their data and can request deletion at any time.

​
SDKs and Libraries

JavaScript/TypeScript

Official SDK for Node.js and browser applications

Python

Official SDK for Python applications

cURL Examples

Complete cURL examples for all endpoints

Postman Collection

Import ready-to-use Postman collection

​
Getting Started

  1. Create an account at trainlyai.com
  2. Create a chat and upload some documents
  3. Enable API access in chat settings
  4. Generate an API key or register your OAuth app
  5. Make your first API call

Quick Start Guide

Get up and running in 5 minutes

​
Support

Need help? We’re here for you: