> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neosantara.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Interactive OpenAPI specification for Neosantara AI Gateway endpoints and MCP services.

Neosantara provides a unified API interface compatible with both OpenAI and Anthropic Messages protocols. You can test endpoints directly using the interactive OpenAPI playground in the right-hand panel.

## Gateway Base URL

Configure the official gateway URL as the base URL for your client SDK:

```python Python icon="python" theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
from openai import OpenAI
import os

client = OpenAI(
    base_url="https://api.neosantara.xyz/v1",
    api_key=os.environ.get("NEOSANTARA_API_KEY")
)
```

```typescript TypeScript icon="js" theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.neosantara.xyz/v1",
  apiKey: process.env.NEOSANTARA_API_KEY
});
```

## Authentication & API Key Formats

All requests to the gateway are authenticated using Neosantara API key tokens. Keys are scoped into two distinct prefixes:

| Key Type | Prefix Format | Scope | Header Specification |
| :- | :- | :- | :- |
| **Standard API Key** | `nsk_` + 32-char hex | Inference endpoints (`/v1/*`, `/anthropic/*`) | `Authorization: Bearer nsk_...` or `x-api-key: nsk_...` |
| **MCP API Key** | `nsk_mcp_` + 32-char hex | Model Context Protocol servers (`/v1/mcp/*`) | `Authorization: Bearer nsk_mcp_...` |

Manage and provision API keys in the [API Keys Dashboard](https://app.neosantara.xyz/api-keys).

## Core Request Headers

Include the required headers based on the endpoint protocol:

### 1. OpenAI-Compatible Endpoints (`/v1/*`)

```bash theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
-H "Authorization: Bearer $NEOSANTARA_API_KEY" \
-H "Content-Type: application/json"
```

Optional headers:

* `X-Guard: on` (Enables automated UU PDP PII redaction for paid users).
* `x-request-id: <uuid>` (Custom identifier for end-to-end request tracing).

### 2. Anthropic Messages Endpoints (`/anthropic/*`)

```bash theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
-H "x-api-key: $NEOSANTARA_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json"
```

## Error Response Structure

When a request encounters an error, the gateway returns a standard OpenAI error JSON payload:

```json theme={"theme":{"light":"catppuccin-latte","dark":"ayu-dark"}}
{
  "error": {
    "message": "Model 'claude-sonnet-4-6' context length exceeded.",
    "type": "invalid_request_error",
    "code": "context_length_exceeded",
    "param": null
  }
}
```

Standard HTTP status codes:

| HTTP Status | Meaning |
| :- | :- |
| `200 OK` | The request executed successfully. |
| `400 Bad Request` | Missing or invalid parameters in the request payload. |
| `401 Unauthorized` | Invalid, expired, or missing API key. |
| `402 Payment Required` | Insufficient PAYG balance to process the request. |
| `429 Too Many Requests` | Exceeded RPM, ITPM, or OTPM limits for your account tier. |
| `503 Service Unavailable` | Upstream provider error or active circuit breaker. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.