> ## 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:

<CodeGroup>
  ```python Python icon="python" theme={"theme":{"light":"ayu-dark","dark":"catppuccin-latte"}}
  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":"ayu-dark","dark":"catppuccin-latte"}}
  import OpenAI from "openai";

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

## 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":"ayu-dark","dark":"catppuccin-latte"}}
-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":"ayu-dark","dark":"catppuccin-latte"}}
-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":"ayu-dark","dark":"catppuccin-latte"}}
{
  "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.        |


## Related topics

- [Chat Completions](/en/gateway/chat-completions.md)
- [OpenResponses API](/en/gateway/responses-api.md)
- [Anthropic Messages API](/en/gateway/anthropic-messages.md)
- [Frequently Asked Questions](/en/guides/faq.md)