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

# API Reference Overview

> Complete reference for the Shinzo Platform REST API for authentication, telemetry ingestion, AI agents, and analytics.

# API Reference

The Shinzo Platform provides a RESTful API for programmatic access to authentication, telemetry ingestion, AI agent management, and analytics. This reference documents all available endpoints and their usage.

## Base URL

All API requests are made to the following base URL:

```
https://api.app.shinzo.ai
```

## API Categories

<CardGroup cols={2}>
  <Card title="Authentication" icon="lock" href="/api/auth/login">
    User registration, login, OAuth, and token management.
  </Card>

  <Card title="AI Agents" icon="robot" href="/api/agents/create">
    Deploy, manage, and interact with AI agents.
  </Card>

  <Card title="Spotlight" icon="eye" href="/api/spotlight/overview">
    AI model proxy, session analytics, and token tracking.
  </Card>

  <Card title="Telemetry" icon="signal" href="/api/telemetry/ingest-traces">
    Send OpenTelemetry data from your MCP servers.
  </Card>

  <Card title="Tokens" icon="key" href="/api/tokens/ingest">
    Manage ingest tokens and platform API keys.
  </Card>

  <Card title="Provider Keys" icon="plug" href="/api/provider-keys/list">
    Configure AI provider credentials (Anthropic, etc.).
  </Card>
</CardGroup>

## Authentication Methods

The Shinzo Platform supports multiple authentication methods depending on the endpoint:

| Auth Type            | Use Case                                              | Header Format                                                      |
| -------------------- | ----------------------------------------------------- | ------------------------------------------------------------------ |
| **JWT Token**        | User authentication for dashboard and management APIs | `Authorization: Bearer <jwt_token>`                                |
| **Ingest Token**     | Sending telemetry data from SDKs                      | `Authorization: <ingest_token>`                                    |
| **Platform API Key** | Programmatic access to agent and spotlight APIs       | `x-shinzo-api-key: <api_key>` or `Authorization: Bearer <api_key>` |

JWT tokens are obtained by logging in via `/auth/login` or OAuth. Ingest tokens and platform API keys are generated from the dashboard or via API.

## Request Format

All API requests should include:

```bash theme={null}
Content-Type: application/json
Authorization: Bearer <your_token>
```

## Response Format

All responses are JSON-formatted and include standard fields:

```json theme={null}
{
  "success": true,
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}
```

### Error Responses

Error responses include an `error` object with details:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The request body is missing required field 'server_name'",
    "details": {
      "field": "server_name",
      "reason": "required"
    }
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2025-01-15T10:30:00Z"
  }
}
```

## HTTP Status Codes

| Code  | Description                             |
| ----- | --------------------------------------- |
| `200` | Success                                 |
| `201` | Resource created                        |
| `400` | Bad request (invalid parameters)        |
| `401` | Unauthorized (invalid or missing token) |
| `403` | Forbidden (insufficient permissions)    |
| `404` | Resource not found                      |
| `429` | Rate limit exceeded                     |
| `500` | Internal server error                   |

## Rate Limiting

API endpoints are rate-limited to ensure fair usage:

| Endpoint Category | Rate Limit           |
| ----------------- | -------------------- |
| All endpoints     | 1000 requests/minute |

Rate limit headers are included in all responses:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 995
X-RateLimit-Reset: 1705315800
```

## SDKs and Libraries

While you can use the API directly for MCP telemetry ingestion, we recommend using our official SDKs:

* [TypeScript SDK](/sdk/typescript/installation)
* [Python SDK](/sdk/python/installation)

The SDKs handle authentication, batching, retries, and error handling automatically.

## Getting Started

1. [Create an account](https://app.shinzo.ai) on the Shinzo Platform
2. Verify your email address
3. Make your first API call to verify connectivity

```bash theme={null}
curl -X GET https://api.app.shinzo.ai/health
```

Expected response:

```json theme={null}
{
  "status": "healthy",
  "database": "healthy"
}
```

For authenticated endpoints, first log in to get a JWT token:

```bash theme={null}
curl -X POST https://api.app.shinzo.ai/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "your@email.com", "password": "your_password"}'
```