SynapseX API Reference

Complete REST API documentation for the SynapseX LLM Platform.

Base URL

https://api.synapsex.ai/v1

Authentication

All API requests require authentication via the Authorization header:

curl -H "Authorization: Bearer sk-synapsex-your-key" \
     https://api.synapsex.ai/v1/chat/completions

For licensed features, also include the license key:

curl -H "Authorization: Bearer sk-synapsex-your-key" \
     -H "X-License-Key: SQXL-XXXX-XXXX-XXXX" \
     https://api.synapsex.ai/v1/chat/completions

Authentication Methods

Method	Header	Format	Use Case
API Key	`Authorization`	`Bearer sk-xxx`	Standard access
License Key	`X-License-Key`	`SQXL-xxx`	License validation
Tenant ID	`X-Tenant-ID`	`tenant_slug`	Multi-tenant access

Rate Limits

Plan	Requests/min	Tokens/day
Free	20	10,000
Pro	100	100,000
Business	500	1,000,000
Enterprise	Custom	Unlimited

Chat Completions

Create Chat Completion

Generate a chat response, optionally with quantum reranking.

POST /v1/chat/completions

Request Body:

{
  "model": "synapsex-chat",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What is quantum computing?"}
  ],
  "temperature": 0.7,
  "max_tokens": 512,
  "stream": false,
  "use_rerank": "quantum_cpu",
  "rerank_k": 4
}

Field	Type	Required	Description
`model`	string	Yes	Model ID
`messages`	array	Yes	Conversation messages
`temperature`	float	No	Sampling temperature (0-2, default: 1)
`max_tokens`	integer	No	Max response tokens
`stream`	boolean	No	Enable streaming
`use_rerank`	string	No	`"classic"`, `"quantum_cpu"`, `"quantum_gpu"`
`rerank_k`	integer	No	Candidate count for reranking (default: 4)
`top_p`	float	No	Nucleus sampling (0-1)
`stop`	array	No	Stop sequences

Response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1703683200,
  "model": "synapsex-chat",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing is..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  },
  "meta": {
    "rerank_tier": "quantum_cpu",
    "candidates": 4,
    "quality_score": 0.92,
    "turbo_on": true,
    "entropy": 4.2
  }
}

Embeddings

Create Embeddings

Generate vector embeddings for text.

POST /v1/embeddings

Request Body:

{
  "input": ["Hello world", "Quantum computing is fascinating"],
  "model": "synapsex-embed"
}

Field	Type	Required	Description
`input`	string/array	Yes	Text(s) to embed
`model`	string	No	Embedding model (default: `synapsex-embed`)

Response:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "index": 0,
      "embedding": [0.0023, -0.0045, ...]
    },
    {
      "object": "embedding",
      "index": 1,
      "embedding": [0.0012, -0.0078, ...]
    }
  ],
  "model": "synapsex-embed",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

Rerank

Rerank Documents

Rerank documents using quantum-enhanced scoring.

POST /v1/rerank

Request Body:

{
  "query": "What are the side effects of aspirin?",
  "documents": [
    "Aspirin can cause stomach upset...",
    "The weather today is sunny...",
    "Common side effects include bleeding..."
  ],
  "top_k": 2,
  "tier": "quantum_cpu"
}

Field	Type	Required	Description
`query`	string	Yes	Search query
`documents`	array	Yes	Documents to rerank
`top_k`	integer	No	Return top K results
`tier`	string	No	Reranking tier

Response:

{
  "results": [
    {
      "index": 2,
      "document": "Common side effects include bleeding...",
      "score": 0.95
    },
    {
      "index": 0,
      "document": "Aspirin can cause stomach upset...",
      "score": 0.87
    }
  ],
  "meta": {
    "tier": "quantum_cpu",
    "latency_ms": 45
  }
}

Tenants

Create Tenant

Create a new tenant (customer).

POST /v1/tenants

Request Body:

{
  "name": "Farmácia Santa Casa",
  "slug": "farmacia_santa_casa",
  "tier": "pro",
  "settings": {
    "default_model": "synapsex-chat",
    "max_tokens_per_request": 2048,
    "enable_rerank": true,
    "rerank_tier": "quantum_cpu"
  }
}

Response:

{
  "id": "tenant_abc123",
  "name": "Farmácia Santa Casa",
  "slug": "farmacia_santa_casa",
  "tier": "pro",
  "api_key": "sk-farmacia-santa-casa-xxx",
  "created_at": "2024-01-15T10:30:00Z",
  "settings": {
    "default_model": "synapsex-chat",
    "max_tokens_per_request": 2048,
    "enable_rerank": true,
    "rerank_tier": "quantum_cpu"
  }
}

List Tenants

GET /v1/tenants

Query Parameters:

Parameter	Type	Description
`limit`	integer	Max results (default: 50)
`offset`	integer	Pagination offset
`tier`	string	Filter by tier

Get Tenant

GET /v1/tenants/{tenant_id}

Update Tenant

PATCH /v1/tenants/{tenant_id}

Delete Tenant

DELETE /v1/tenants/{tenant_id}

Get Tenant Settings

GET /v1/tenants/{tenant_id}/settings

Update Tenant Settings

PATCH /v1/tenants/{tenant_id}/settings

Request Body:

{
  "enable_rerank": true,
  "rerank_tier": "quantum_gpu",
  "custom_system_prompt": "You are a pharmacy assistant..."
}

Feedback

Collect user feedback for model improvement.

Submit Feedback

POST /v1/tenants/{tenant_id}/feedback

Request Body:

{
  "conversation_id": "conv_abc123",
  "message_id": "msg_xyz789",
  "type": "thumbs_down",
  "correction": "The correct dosage is 500mg, not 250mg",
  "metadata": {
    "user_id": "user_123"
  }
}

Feedback Type	Description
`thumbs_up`	Positive feedback
`thumbs_down`	Negative feedback
`correction`	User-provided correction
`rating`	Numeric rating (1-5)
`report`	Content report

List Feedback

GET /v1/tenants/{tenant_id}/feedback

Get Feedback Stats

GET /v1/tenants/{tenant_id}/feedback/stats

Response:

{
  "total": 1500,
  "thumbs_up": 1200,
  "thumbs_down": 200,
  "corrections": 100,
  "average_rating": 4.2,
  "ready_for_training": true
}

Datasets (DataHub)

Manage documents and tables for RAG.

Register Dataset

POST /v1/tenants/{tenant_id}/datasets/register

Request Body:

{
  "name": "product_catalog",
  "type": "documents",
  "description": "Product information database",
  "data_use": {
    "allow_rag": true,
    "allow_private_training": true
  }
}

Upload Documents

POST /v1/tenants/{tenant_id}/datasets/{dataset_id}/upload/docs

Request Body:

{
  "docs": [
    {
      "doc_id": "prod_001",
      "title": "Aspirin 500mg",
      "text": "Pain reliever and anti-inflammatory...",
      "metadata": {
        "category": "analgesics",
        "price": 12.99
      }
    }
  ]
}

Upload Table

POST /v1/tenants/{tenant_id}/datasets/{dataset_id}/upload/table

Request Body:

{
  "table_name": "inventory",
  "columns": ["product_id", "name", "quantity", "price"],
  "rows": [
    ["prod_001", "Aspirin 500mg", 150, 12.99],
    ["prod_002", "Ibuprofen 400mg", 200, 15.50]
  ]
}

Search Dataset

GET /v1/tenants/{tenant_id}/datasets/{dataset_id}/search?q=aspirin&top_k=5

List Datasets

GET /v1/tenants/{tenant_id}/datasets

List RAG-Enabled Datasets

GET /v1/tenants/{tenant_id}/datasets/rag-enabled

Training

Trigger model fine-tuning jobs.

Trigger LoRA Training

POST /v1/tenants/{tenant_id}/train/lora

Request Body:

{
  "min_feedback_count": 100,
  "lora_r": 16,
  "lora_alpha": 32,
  "epochs": 3,
  "learning_rate": 2e-4,
  "batch_size": 4
}

Response:

{
  "job_id": "train_job_abc123",
  "status": "queued",
  "estimated_duration_minutes": 45,
  "feedback_samples": 150,
  "created_at": "2024-01-15T10:30:00Z"
}

Get Training Job Status

GET /v1/tenants/{tenant_id}/train/{job_id}

Response:

{
  "job_id": "train_job_abc123",
  "status": "running",
  "progress": 0.65,
  "current_epoch": 2,
  "total_epochs": 3,
  "metrics": {
    "loss": 0.234,
    "learning_rate": 1.8e-4
  }
}

List Training Jobs

GET /v1/tenants/{tenant_id}/train

Models

List Available Models

GET /v1/models

Response:

{
  "data": [
    {
      "id": "synapsex-chat",
      "object": "model",
      "created": 1703683200,
      "owned_by": "softquantus",
      "context_length": 8192,
      "capabilities": ["chat", "rerank"]
    },
    {
      "id": "synapsex-chat-32k",
      "object": "model",
      "created": 1703683200,
      "owned_by": "softquantus",
      "context_length": 32768,
      "capabilities": ["chat", "rerank"]
    }
  ]
}

Admin

Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "2.1.0",
  "components": {
    "api": "healthy",
    "database": "healthy",
    "inference": "healthy",
    "quantum": "healthy"
  }
}

Usage Statistics

GET /v1/admin/usage

Requires admin API key.

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Rate limit exceeded
`INVALID_REQUEST`	400	Invalid request body
`MODEL_NOT_FOUND`	400	Unknown model
`TENANT_NOT_FOUND`	404	Tenant not found
`TRAINING_FAILED`	500	Training job failed
`INTERNAL_ERROR`	500	Server error

Error Response Format:

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "retry_after": 60
  },
  "request_id": "req_abc123"
}

Webhooks

Configure Webhook

POST /v1/webhooks

Request Body:

{
  "url": "https://your-server.com/webhook",
  "events": ["training.completed", "feedback.received"],
  "secret": "your-webhook-secret"
}

Events:

Event	Description
`training.completed`	Training job finished
`training.failed`	Training job failed
`feedback.received`	New feedback submitted
`tenant.created`	New tenant created

SDKs

Official SDKs and integrations:

Python (OpenAI SDK): Use with custom base_url
JavaScript: Standard fetch or OpenAI SDK
LangChain: Compatible with ChatOpenAI class
LobeChat: Native integration available

Changelog

v2.1.0 (2024-01)

Added quantum GPU reranking tier
Improved streaming performance
New feedback analytics

v2.0.0 (2023-10)

Multi-tenant architecture
QCOS integration
DataHub v2

See full changelog for details.

Base URL​

Authentication​

Authentication Methods​

Rate Limits​

Chat Completions​

Create Chat Completion​

Embeddings​

Create Embeddings​

Rerank​

Rerank Documents​

Tenants​

Create Tenant​

List Tenants​

Get Tenant​

Update Tenant​

Delete Tenant​

Get Tenant Settings​

Update Tenant Settings​

Feedback​

Submit Feedback​

List Feedback​

Get Feedback Stats​

Datasets (DataHub)​

Register Dataset​

Upload Documents​

Upload Table​

Search Dataset​

List Datasets​

List RAG-Enabled Datasets​

Training​

Trigger LoRA Training​

Get Training Job Status​

List Training Jobs​

Models​

List Available Models​

Admin​

Health Check​

Usage Statistics​

Error Codes​

Webhooks​

Configure Webhook​

SDKs​

Changelog​

v2.1.0 (2024-01)​

v2.0.0 (2023-10)​

Base URL

Authentication

Authentication Methods

Rate Limits

Chat Completions

Create Chat Completion

Embeddings

Create Embeddings

Rerank

Rerank Documents

Tenants

Create Tenant

List Tenants

Get Tenant

Update Tenant

Delete Tenant

Get Tenant Settings

Update Tenant Settings

Feedback

Submit Feedback

List Feedback

Get Feedback Stats

Datasets (DataHub)

Register Dataset

Upload Documents

Upload Table

Search Dataset

List Datasets

List RAG-Enabled Datasets

Training

Trigger LoRA Training

Get Training Job Status

List Training Jobs

Models

List Available Models

Admin

Health Check

Usage Statistics

Error Codes

Webhooks

Configure Webhook

SDKs

Changelog

v2.1.0 (2024-01)

v2.0.0 (2023-10)