AchiralAchiral

Docs · LLMs and developers

Version3.12.1

API reference

Current inference gateway contract, authentication, and response conventions.

This page covers the current public inference surface that is backed by the app as of Wednesday, July 22, 2026.

Today, the supported contract is the OpenAI-compatible memory inference gateway plus the agent-scoped inference variant.

Base URL

Use your organization's workspace endpoint for memory-aware inference, for example:

  • https://your-org-slug.achiral.ai/v1

The product also exposes a memory endpoint to admins when they create Context Access Tokens.

Custom domains use the same /v1 path on the approved hostname when custom-domain setup is active.

Authentication

Authenticate requests with a Context Access Token.

Use the token in the Authorization header:

export ACHIRAL_TOKEN="acm_..."
curl https://your-org-slug.achiral.ai/v1/models \
  -H "Authorization: Bearer $ACHIRAL_TOKEN"

Context Access Tokens are created by an owner or admin in the organization settings UI.

The current token scopes exposed in the product are:

  • knowledge:read
  • insights:read
  • actions:request
  • inference:chat

For the inference routes on this page, the token needs the inference:chat scope.

Rate Limiting

API requests are rate-limited based on your plan:

Plan bucketLimit model
FreeLowest message and storage limits
SparkSmall-team paid limits
Seed / RiseHigher message and storage limits
Boost and aboveContract-specific API limits

The current pricing config is the source of truth for public plan buckets. Operational rate limits may also include abuse controls, contract limits, and per-route limits.

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 for organization-scoped memory inference.

Endpoint: POST /v1/chat/completions

curl https://your-org-slug.achiral.ai/v1/chat/completions \
  -H "Authorization: Bearer $ACHIRAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chiro",
    "messages": [
      {"role": "user", "content": "Summarize what changed in our workspace today."}
    ],
    "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
  }
}

Agent-scoped Chat Completions

Use the agent-scoped route when you want the request to run inside a specific agent boundary.

Endpoint: POST /v1/agents/{agentSlug}/chat/completions

curl https://your-org-slug.achiral.ai/v1/agents/release-readiness/chat/completions \
  -H "Authorization: Bearer $ACHIRAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chiro",
    "messages": [
      {"role": "user", "content": "Prepare the next rollout review with prior migration context."}
    ]
  }'

You may also see agent-scoped examples in the app that use the X-Achiral-Agent header. The route above is the clearest public contract to document.

Request Parameters

Common Parameters

ParameterTypeDescriptionDefault
modelstringModel identifierRequired
temperaturefloatSampling temperature (0-2)1.0
max_tokensintegerMaximum tokens to generate2048
top_pfloatNucleus sampling threshold1.0
frequency_penaltyfloatPenalize repeated tokens (-2 to 2)0.0
presence_penaltyfloatPenalize token presence (-2 to 2)0.0
stoparrayStop sequencesnull
streambooleanStream response tokensfalse

Streaming API

The current inference gateway supports streaming on the chat completions route.

Server-Sent Events

Stream responses using SSE:

curl https://your-org-slug.achiral.ai/v1/chat/completions \
  -H "Authorization: Bearer $ACHIRAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chiro",
    "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://your-org-slug.achiral.ai/v1/chat/completions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.ACHIRAL_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "chiro",
    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);
    }
  }
}

Model Management

List Models

Endpoint: GET /v1/models

curl https://your-org-slug.achiral.ai/v1/models \
  -H "Authorization: Bearer $ACHIRAL_TOKEN"

Response:

{
  "object": "list",
  "data": [
    {
      "id": "chiro",
      "object": "model",
      "created": 1699564800,
      "owned_by": "achiral",
      "context_length": 8192
    }
  ]
}

The gateway currently advertises a single client-facing model id: chiro.

Health Check

Use the health route for a basic liveness check.

Endpoint: GET /v1/health

curl https://your-org-slug.achiral.ai/v1/health

Error Handling

Error Response Format

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

HTTP Status Codes

CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error
503Service 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)

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ACHIRAL_TOKEN"],
    base_url="https://your-org-slug.achiral.ai/v1"
)

response = client.chat.completions.create(
    model="chiro",
    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: process.env.ACHIRAL_TOKEN,
  baseURL: "https://your-org-slug.achiral.ai/v1",
});

const response = await client.chat.completions.create({
  model: "chiro",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Hello!" },
  ],
});

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

cURL

curl https://your-org-slug.achiral.ai/v1/chat/completions \
  -H "Authorization: Bearer $ACHIRAL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "chiro",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

Continue from here

  • Custom domains: review hosted custom-domain setup.
  • Getting Started: set up the workspace before making the first API call.
  • Memory API: see the broader memory-related surface.
  • Agents: use agent-scoped memory and runtime calls.

Learn more