API Reference

Complete Arachne gateway and portal API reference

Arachne exposes three API surfaces: the Gateway for LLM inference, the Portal API for tenant self-service, and the Admin API for system-wide operations.

Gateway API

The gateway is OpenAI-compatible. Any client that works with the OpenAI API works with Arachne.

POST /v1/chat/completions

Send a chat completion request through the gateway. The agent, model, and provider are resolved from the API key.

Authentication: Bearer token or x-api-key header with your Arachne API key.

Request Body:

{
  "messages": [
    { "role": "user", "content": "What is Arachne?" }
  ],
  "stream": true,
  "conversation_id": "conv_abc123",
  "partition_id": "user_42"
}

Response (non-streaming):

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Arachne is an AI runtime..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 24,
    "completion_tokens": 89,
    "total_tokens": 113
  },
  "rag_sources": [
    {
      "chunk_id": "chunk_001",
      "content": "Arachne is a multi-tenant AI gateway...",
      "similarity": 0.92,
      "knowledge_base": "product-docs"
    }
  ]
}

RAG Sources: When the agent has an attached knowledge base, the response includes a rag_sources array with the retrieved chunks, their similarity scores, and the source knowledge base. This enables citation and transparency in RAG-powered responses.

Streaming Response: When stream: true, the response is delivered as server-sent events in OpenAI-compatible format:

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":"Arachne"},"index":0}]}

data: {"id":"chatcmpl-abc","choices":[{"delta":{"content":" is"},"index":0}]}

data: [DONE]

Portal API

The portal API powers the self-service UI. All endpoints require a Portal JWT token obtained via login.

Base path: /v1/portal

Authentication: Authorization: Bearer <portal_jwt>

Authentication

Agents

Knowledge Bases

API Keys

Members

Settings

Admin API

The admin API is for system operators managing the Arachne instance. All endpoints require an Admin JWT.

Base path: /v1/admin

Authentication: Authorization: Bearer <admin_jwt>

Error Responses

All APIs return errors in a consistent format:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Common HTTP status codes: