API Reference

Achiral AI is a privacy-first AI platform for businesses with enterprise-grade, self-hosted, secure infrastructure. The Achiral API is RESTful, supports OpenAI-compatible endpoints, and provides WebSocket streaming for real-time inference.

Base URL

All API requests are made to the Achiral API endpoint:

https://api.achiral.ai/v1

For custom domains (Scale+ plans):

https://your-domain.com/v1

Authentication

API Keys

Authenticate requests using API keys in the Authorization header:

curl https://api.achiral.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Creating API Keys

Via Dashboard

Navigate to Settings → API Keys
Click Create New Key
Set permissions (read, write, admin)
Copy the key (shown only once)

Via API

curl -X POST https://api.achiral.ai/v1/organizations/{org_id}/api-keys \
  -H "Authorization: Bearer YOUR_ACCOUNT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Key",
    "permissions": ["inference", "training"],
    "rate_limit": 1000
  }'

Key Permissions

inference: Make inference requests
training: Train and fine-tune models
models: Upload and manage models
admin: Full access to all operations

Rate Limiting

API requests are rate-limited based on your plan:

Plan	Concurrent Requests	Tokens/Request	Tokens/Hour
Spark	5	2,048	10,000
Seed	20	4,096	100,000
Scale	100	8,192	Unlimited
Dedicated	Unlimited	16,384	Unlimited

Rate Limit Headers

Response headers indicate current limits:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699564800

Exceeding Limits

When rate limited, you'll receive a 429 response:

{
  "error": {
    "message": "Rate limit exceeded",
    "type": "rate_limit_error",
    "retry_after": 30
  }
}

Inference API

Chat Completions

OpenAI-compatible chat completions endpoint.

Endpoint: POST /v1/chat/completions

curl https://api.achiral.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chiro",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "What is machine learning?"}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Response:

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1699564800,
  "model": "chiro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Machine learning is a subset of artificial intelligence..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 150,
    "total_tokens": 175
  }
}

Text Completions

Legacy completions endpoint.

Endpoint: POST /v1/completions

curl https://api.achiral.ai/v1/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chiro",
    "prompt": "Once upon a time",
    "max_tokens": 100,
    "temperature": 0.8
  }'

Embeddings

Generate text embeddings.

Endpoint: POST /v1/embeddings

curl https://api.achiral.ai/v1/embeddings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chiro",
    "input": "Machine learning is amazing"
  }'

Response:

{
  "object": "list",
  "data": [
    {
      "object": "embedding",
      "embedding": [0.123, -0.456, 0.789, ...],
      "index": 0
    }
  ],
  "model": "bge-large-en",
  "usage": {
    "prompt_tokens": 6,
    "total_tokens": 6
  }
}

Request Parameters

Common Parameters

Parameter	Type	Description	Default
`model`	string	Model identifier	Required
`temperature`	float	Sampling temperature (0-2)	1.0
`max_tokens`	integer	Maximum tokens to generate	2048
`top_p`	float	Nucleus sampling threshold	1.0
`frequency_penalty`	float	Penalize repeated tokens (-2 to 2)	0.0
`presence_penalty`	float	Penalize token presence (-2 to 2)	0.0
`stop`	array	Stop sequences	null
`stream`	boolean	Stream response tokens	false

Streaming API

Server-Sent Events

Stream responses using SSE:

curl https://abc123xyz.nano.achiral.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-7b-instruct",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'

Response:

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":"Hello"}}]}

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":"!"}}]}

data: {"id":"chatcmpl-123","choices":[{"delta":{"content":" How"}}]}

data: [DONE]

JavaScript Example

const response = await fetch('https://abc123xyz.nano.achiral.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'mistral-7b-instruct',
    messages: [{ role: 'user', content: 'Hello!' }],
    stream: true,
  }),
})

const reader = response.body.getReader()
const decoder = new TextDecoder()

while (true) {
  const { done, value } = await reader.read()
  if (done) break

  const chunk = decoder.decode(value)
  const lines = chunk.split('\n').filter(line => line.trim())

  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = line.slice(6)
      if (data === '[DONE]') break
      const json = JSON.parse(data)
      console.log(json.choices[0].delta.content)
    }
  }
}

WebSocket API

Connection

Connect to WebSocket for bidirectional streaming:

const ws = new WebSocket('wss://abc123xyz.nano.achiral.ai/v1/ws')

ws.onopen = () => {
  // Authenticate
  ws.send(
    JSON.stringify({
      type: 'auth',
      api_key: 'YOUR_API_KEY',
    })
  )
}

ws.onmessage = event => {
  const data = JSON.parse(event.data)
  console.log(data)
}

Inference via WebSocket

// Send inference request
ws.send(
  JSON.stringify({
    type: 'inference',
    model: 'mistral-7b-instruct',
    messages: [{ role: 'user', content: 'Hello!' }],
    stream: true,
  })
)

// Receive tokens
ws.onmessage = event => {
  const data = JSON.parse(event.data)

  if (data.type === 'token') {
    process.stdout.write(data.content)
  } else if (data.type === 'done') {
    console.log('\nComplete!')
  }
}

Model Management

List Models

Endpoint: GET /v1/models

curl https://abc123xyz.nano.achiral.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "object": "list",
  "data": [
    {
      "id": "mistral-7b-instruct",
      "object": "model",
      "created": 1699564800,
      "owned_by": "mistralai",
      "parameters": "7B",
      "context_length": 8192
    }
  ]
}

Get Model Details

Endpoint: GET /v1/models/{model_id}

curl https://abc123xyz.nano.achiral.ai/v1/models/mistral-7b-instruct \
  -H "Authorization: Bearer YOUR_API_KEY"

Upload Custom Model

Endpoint: POST /v1/models

curl -X POST https://abc123xyz.nano.achiral.ai/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@model.safetensors" \
  -F "config=@config.json" \
  -F "model_id=custom-model" \
  -F "model_type=causal-lm"

Training API

Create Fine-tuning Job

Endpoint: POST /v1/fine-tuning/jobs

curl -X POST https://abc123xyz.nano.achiral.ai/v1/fine-tuning/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-7b",
    "training_file": "file-abc123",
    "hyperparameters": {
      "n_epochs": 3,
      "batch_size": 4,
      "learning_rate": 5e-5
    }
  }'

List Fine-tuning Jobs

Endpoint: GET /v1/fine-tuning/jobs

curl https://abc123xyz.nano.achiral.ai/v1/fine-tuning/jobs \
  -H "Authorization: Bearer YOUR_API_KEY"

Get Job Status

Endpoint: GET /v1/fine-tuning/jobs/{job_id}

curl https://abc123xyz.nano.achiral.ai/v1/fine-tuning/jobs/ftjob-abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

Error Response Format

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

HTTP Status Codes

Code	Description
200	Success
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error
503	Service Unavailable - Service temporarily unavailable

Error Types

authentication_error: Invalid API key
authorization_error: Insufficient permissions
invalid_request_error: Invalid parameters
rate_limit_error: Rate limit exceeded
model_error: Model loading or inference error
server_error: Internal server error

SDK Examples

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://abc123xyz.nano.achiral.ai/v1"
)

response = client.chat.completions.create(
    model="mistral-7b-instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)

Node.js

import OpenAI from 'openai'

const client = new OpenAI({
  apiKey: 'YOUR_API_KEY',
  baseURL: 'https://abc123xyz.nano.achiral.ai/v1',
})

const response = await client.chat.completions.create({
  model: 'mistral-7b-instruct',
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Hello!' },
  ],
})

console.log(response.choices[0].message.content)

cURL

curl https://abc123xyz.nano.achiral.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "mistral-7b-instruct",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Next Steps

Configuration - Configure your Chiro instance
Network Settings - API endpoint configuration
Getting Started - Quick start guide

Learn more

Explore Features: https://achiral.ai/features
View Pricing: https://achiral.ai/pricing

Base URL​

Authentication​

API Keys​

Creating API Keys​

Via Dashboard​

Via API​

Key Permissions​

Rate Limiting​

Rate Limit Headers​

Exceeding Limits​

Inference API​

Chat Completions​

Text Completions​

Embeddings​

Request Parameters​

Common Parameters​

Streaming API​

Server-Sent Events​

JavaScript Example​

WebSocket API​

Connection​

Inference via WebSocket​

Model Management​

List Models​

Get Model Details​

Upload Custom Model​

Training API​

Create Fine-tuning Job​

List Fine-tuning Jobs​

Get Job Status​

Error Handling​

Error Response Format​

HTTP Status Codes​

Error Types​

SDK Examples​

Python (OpenAI SDK)​

Node.js​

cURL​

Next Steps​

Learn more​

Base URL

Authentication

API Keys

Creating API Keys

Via Dashboard

Via API

Key Permissions

Rate Limiting

Rate Limit Headers

Exceeding Limits

Inference API

Chat Completions

Text Completions

Embeddings

Request Parameters

Common Parameters

Streaming API

Server-Sent Events

JavaScript Example

WebSocket API

Connection

Inference via WebSocket

Model Management

List Models

Get Model Details

Upload Custom Model

Training API

Create Fine-tuning Job

List Fine-tuning Jobs

Get Job Status

Error Handling

Error Response Format

HTTP Status Codes

Error Types

SDK Examples

Python (OpenAI SDK)

Node.js

cURL

Next Steps

Learn more