---
name: neosantara
description: Use when building AI applications that need unified access to multiple LLM providers, integrating with coding agents and IDEs, deploying autonomous agents, or implementing advanced AI features like tool calling, structured outputs, and multimodal processing. Agents should reach for this skill when working with chat completions, managing API keys, handling rate limits, integrating with frameworks like LangChain or CrewAI, or configuring MCP servers.
metadata:
    mintlify-proj: neosantara
    version: "1.0"
---

# Neosantara Skill

## Product Summary

Neosantara is Indonesia's unified AI Gateway providing OpenAI and Anthropic-compatible routing to 100+ foundation models with native Rupiah (IDR) billing. It offers three main endpoints: `/v1/chat/completions` (OpenAI protocol), `/anthropic/v1/messages` (Anthropic protocol), and `/v1/responses` (asynchronous jobs). Key files and configuration: set `NEOSANTARA_API_KEY` environment variable with format `nsk_` + 32-char hex for standard inference, or `nsk_mcp_` for Model Context Protocol servers. Base URL is `https://api.neosantara.xyz/v1` for OpenAI endpoints and `https://api.neosantara.xyz/anthropic` for Anthropic endpoints. Primary documentation: https://docs.neosantara.xyz

## When to Use

Reach for this skill when:
- Building chat applications or AI agents that need access to multiple LLM providers (OpenAI, Anthropic, Gemini, DeepSeek, etc.)
- Integrating with coding IDEs (Cursor, Claude Code, Cline, VS Code) or Claude Desktop
- Deploying autonomous agents (OpenClaw, Hermes) or cloud agents
- Implementing tool calling, structured JSON outputs, vision/multimodal, or reasoning features
- Handling batch processing, streaming responses, or asynchronous job execution
- Configuring MCP (Model Context Protocol) servers for agent tool discovery
- Optimizing costs via prompt caching or rate limit management
- Integrating with frameworks: LangChain, CrewAI, LlamaIndex, Pydantic AI, AutoGen, Vercel AI SDK, or LiteLLM

## Quick Reference

### API Key Management
| Key Type | Prefix | Scope | Header |
|-----------|--------|-------|--------|
| Standard | `nsk_` | Inference (`/v1/*`, `/anthropic/*`) | `Authorization: Bearer nsk_...` or `x-api-key: nsk_...` |
| MCP | `nsk_mcp_` | MCP servers (`/v1/mcp/*`) | `Authorization: Bearer nsk_mcp_...` |

Manage keys in the [Neosantara Dashboard](https://app.neosantara.xyz/api-keys).

### Core Endpoints
| Endpoint | Protocol | Use Case |
|----------|----------|----------|
| `/v1/chat/completions` | OpenAI | Chat, streaming, tool calling, JSON schema |
| `/anthropic/v1/messages` | Anthropic | Full Anthropic Messages API parity |
| `/v1/responses` | OpenResponses | Persistent async jobs, status polling |
| `/v1/models` | OpenAI | List active models, context limits, IDR pricing |
| `/v1/audio/*` | OpenAI | Whisper speech-to-text and text-to-speech |
| `/v1/images/*` | OpenAI | Image generation with multiple models |
| `/v1/embeddings` | OpenAI | Text vector embeddings for RAG/semantic search |
| `/v1/ocr` | Specialized | Structured text and table extraction |

### Request Headers (OpenAI Endpoints)
```bash
-H "Authorization: Bearer $NEOSANTARA_API_KEY"
-H "Content-Type: application/json"
-H "X-Guard: on"  # Optional: enable PII redaction
-H "x-request-id: <uuid>"  # Optional: custom request tracking
```

### Request Headers (Anthropic Endpoints)
```bash
-H "x-api-key: $NEOSANTARA_API_KEY"
-H "anthropic-version: 2023-06-01"
-H "Content-Type: application/json"
```

### Rate Limits by Tier (Gateway)
| Tier | RPM | ITPM | OTPM |
|------|-----|------|------|
| Free | 10 | 30,000 | 30,000 |
| Basic | 20 | 60,000 | 60,000 |
| Standard | 40 | 120,000 | 120,000 |
| Pro | 80 | 240,000 | 240,000 |
| Enterprise | 200 | 600,000 | 600,000 |

For bulk workloads, use Batch Processing (operates outside RPM limits with 50% discount).

### MCP Rate Limits by Tier
| Tier | RPM | Daily Requests | Max Summary Tokens |
|------|-----|-----------------|-------------------|
| Free | 20 | 500 | 900 |
| Basic | 40 | 1,500 | 1,200 |
| Standard | 60 | 3,000 | 1,600 |
| Pro | 120 | 8,000 | 2,200 |
| Enterprise | 240 | 20,000 | 3,200 |

## Decision Guidance

### When to Use Chat Completions vs Responses API
| Aspect | Chat Completions (`/v1/chat/completions`) | Responses API (`/v1/responses`) |
|--------|-------------------------------------------|-------------------------------|
| **Latency** | Real-time, synchronous | Asynchronous, background jobs |
| **Tool Execution** | Manual client-side orchestration | Automatic gateway execution |
| **Use Case** | Interactive chat, streaming, immediate responses | Batch processing, long-running tasks, MCP integration |
| **Async Support** | No | Yes (`background: true`) |
| **State Persistence** | No | Yes (`store: true`) |

### When to Use JSON Mode vs Structured Outputs
| Aspect | JSON Mode (`type: "json_object"`) | Structured Outputs (`type: "json_schema"`) |
|--------|----------------------------------|------------------------------------------|
| **Schema Guarantee** | Valid JSON syntax only | 100% adherence to schema, types, keys |
| **Prompt Requirement** | Requires "JSON" in prompt | No prompt requirement |
| **Strict Enforcement** | Not supported | Fully supported (`strict: true`) |
| **Use Case** | Quick JSON generation | Production systems requiring exact schema |

### When to Use Batch Processing vs Real-Time
| Aspect | Real-Time Requests | Batch Processing |
|--------|-------------------|------------------|
| **Throughput** | Limited by RPM/ITPM | Unlimited (outside RPM) |
| **Cost** | Standard pricing | 50% token discount |
| **Latency** | Immediate | Hours to days |
| **Use Case** | Interactive apps, chat | Data processing, bulk analysis |

## Workflow

### 1. Initialize Client and Make First Request
1. Retrieve API key from [Neosantara Dashboard](https://app.neosantara.xyz/api-keys)
2. Set `NEOSANTARA_API_KEY` environment variable
3. Configure OpenAI or Anthropic SDK with Neosantara base URL
4. Send chat completion request with model ID from the [Model Catalog](https://docs.neosantara.xyz/en/gateway/models)
5. Parse response and check `usage` object for token counts

### 2. Implement Tool Calling
1. Define tools array with function schemas in request
2. Set `tool_choice` to `"auto"` (default), `"none"`, `"required"`, or specific function
3. Receive `tool_calls` in response with `function.name` and `function.arguments`
4. Execute function locally and return results in next message with `role: "tool"`
5. Continue conversation loop until model stops calling tools

### 3. Enable Streaming
1. Set `stream: true` in request
2. Iterate over Server-Sent Events (SSE) chunks
3. Accumulate `delta.content` for text tokens
4. Handle `tool_calls` in streaming chunks (check `delta.tool_calls`)
5. Collect final `usage` from `stream_options.include_usage: true`

### 4. Use Structured Outputs
1. Define JSON schema using `response_format.json_schema`
2. Set `response_format.type: "json_schema"` and `strict: true`
3. Model response will strictly adhere to schema
4. Parse `choices[0].message.content` as valid JSON
5. No additional validation needed

### 5. Integrate with Framework (LangChain Example)
1. Import `ChatOpenAI` from `langchain_openai`
2. Set `openai_api_base="https://api.neosantara.xyz/v1"`
3. Set `openai_api_key=os.environ["NEOSANTARA_API_KEY"]`
4. Specify model from catalog (e.g., `"gemini-3.8-flash"`)
5. Use standard LangChain chains and agents

### 6. Handle Rate Limits
1. Check response for HTTP 429 status
2. Read `retry-after` header for wait duration
3. Implement exponential backoff with jitter
4. For bulk workloads, use Batch Processing instead
5. Monitor tier limits in [Dashboard](https://app.neosantara.xyz)

### 7. Configure MCP Gateway (IDE Integration)
1. Generate MCP API key (`nsk_mcp_...`) in dashboard
2. In IDE settings (Cursor, Claude Code, etc.), set:
   - MCP Server URL: `https://api.neosantara.xyz/v1/mcp`
   - API Key header: `x-api-key: nsk_mcp_...`
3. IDE can now call Neosantara tools (chat, image generation, model listing)
4. Verify connection by testing tool discovery

### 8. Connect MCP Servers (Agent Integration)
1. Deploy your MCP server (GitHub, database, Slack, etc.)
2. In chat request, add `mcp_servers` array with `url`, `name`, `authorization_token`
3. Gateway automatically discovers tools from your server
4. Model can invoke tools; gateway handles execution and response synthesis
5. No client-side tool orchestration needed

## Common Gotchas

- **Missing API Key Format**: Keys must start with `nsk_` (standard) or `nsk_mcp_` (MCP). Verify in dashboard; invalid keys return 401.
- **Wrong Base URL**: OpenAI endpoints use `/v1`, Anthropic use `/anthropic`. Mixing them causes 404 errors.
- **Anthropic Header Mismatch**: Anthropic endpoints require `x-api-key` header and `anthropic-version: 2023-06-01`. Using `Authorization: Bearer` will fail.
- **Context Window Exceeded**: Check model's context limit in catalog before sending long prompts. Exceeding limit returns 400 error.
- **Tool Calling Without Streaming**: When `stream: true`, tool calls appear in delta chunks; handle separately from text tokens.
- **Structured Outputs Not Strict**: Using `type: "json_schema"` without `strict: true` doesn't guarantee schema adherence. Always set `strict: true` for production.
- **Rate Limit Tier Mismatch**: Free tier has 5 RPM for promotional models until you deposit IDR 50,000. Verify tier in dashboard.
- **MCP Key Limit**: Each account can provision max 5 active MCP keys. Deactivate old keys before creating new ones.
- **Batch Processing Discount**: 50% discount applies only to batch jobs; real-time requests use standard pricing.
- **Prompt Caching Minimum**: Requires ≥1,024 tokens in prefix. Shorter prompts won't trigger caching.
- **Image Size Limit**: Maximum 20 MB per image for vision endpoints. Larger images return 400 error.
- **Streaming Usage Object**: Include `stream_options.include_usage: true` to get final token counts in streaming responses.

## Verification Checklist

Before submitting work:
- [ ] API key is set in environment and starts with `nsk_` or `nsk_mcp_`
- [ ] Base URL matches endpoint type (OpenAI vs Anthropic)
- [ ] Request headers include required authentication header
- [ ] Model ID exists in [Model Catalog](https://docs.neosantara.xyz/en/gateway/models)
- [ ] Messages array has at least one user message with valid role
- [ ] Tool schemas (if used) have required `name` and `parameters` fields
- [ ] Structured outputs include `response_format.json_schema` and `strict: true`
- [ ] Streaming requests set `stream: true` and handle SSE chunks
- [ ] Rate limit handling includes exponential backoff for 429 responses
- [ ] MCP servers (if used) have valid `url` and `name` fields
- [ ] Response parsing checks `choices[0].message.content` for text output
- [ ] Token usage is tracked via `usage` object for billing verification
- [ ] Error responses are checked for `error.code` and `error.message`

## Resources

**Comprehensive Documentation Index**: https://docs.neosantara.xyz/llms.txt

**Critical Pages**:
1. [Gateway Overview](https://docs.neosantara.xyz/en/gateway/overview) — Endpoints, authentication, request headers
2. [Model Catalog](https://docs.neosantara.xyz/en/gateway/models) — 100+ models, context windows, IDR pricing
3. [Chat Completions](https://docs.neosantara.xyz/en/gateway/chat-completions) — Core API, parameters, usage object
4. [Integrations Overview](https://docs.neosantara.xyz/en/integrations/overview) — Framework patterns, native providers, coding agents
5. [Rate Limits & Throughput](https://docs.neosantara.xyz/en/guides/rate-limits) — RPM/ITPM/OTPM limits, handling 429 errors
6. [MCP & Agent Architecture](https://docs.neosantara.xyz/en/agents/overview) — MCP Gateway vs Connector, IDE setup

---

> For additional documentation and navigation, see: https://docs.neosantara.xyz/llms.txt