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

# Spotlight Overview

> AI model proxy with built-in analytics, token tracking, and session management.

# Spotlight

Spotlight is the Shinzo Platform's AI model proxy service. It forwards requests to AI providers (like Anthropic) while automatically tracking usage, tokens, costs, and session analytics.

## Features

* **Model Proxy**: Forward requests to AI providers with automatic retry and error handling
* **Token Tracking**: Track input/output tokens, cache hits, and costs
* **Session Analytics**: Group API calls into sessions for analysis
* **Streaming Support**: Full support for streaming responses with Server-Sent Events
* **Multi-Auth**: Authenticate with JWT tokens or Platform API keys

## Supported Providers

| Provider  | Base Path               | Features                            |
| --------- | ----------------------- | ----------------------------------- |
| Anthropic | `/spotlight/anthropic/` | Messages, token counting, streaming |

## Authentication

Spotlight endpoints accept either:

* **JWT Token**: `Authorization: Bearer <jwt_token>`
* **Platform API Key**: `x-shinzo-api-key: <api_key>` or `Authorization: Bearer <api_key>`

## Provider Credentials

Spotlight needs credentials to make requests to AI providers. You can:

1. **Store credentials** in Shinzo using [Provider Keys](/api/provider-keys/overview) (recommended)
2. **Pass credentials** directly in the request using the `x-api-key` header

<Warning>
  **Subscription-based access is not supported.** Spotlight requires API keys from the [Anthropic Console](https://console.anthropic.com/settings/keys). OAuth tokens from Claude subscriptions (e.g., Claude Pro/Team subscriptions) cannot be used and will return a `403 Forbidden` error.
</Warning>

## Endpoints

### Model Proxy

| Method | Endpoint                                                                       | Description                                   |
| ------ | ------------------------------------------------------------------------------ | --------------------------------------------- |
| `POST` | [`/spotlight/anthropic/v1/messages`](/api/spotlight/messages)                  | Send messages to Claude (streaming supported) |
| `POST` | [`/spotlight/anthropic/v1/messages/count_tokens`](/api/spotlight/count-tokens) | Count tokens for a request                    |

### Analytics

| Method | Endpoint                                                                    | Description                            |
| ------ | --------------------------------------------------------------------------- | -------------------------------------- |
| `GET`  | [`/spotlight/analytics/tokens`](/api/spotlight/token-analytics)             | Token usage analytics by model         |
| `GET`  | [`/spotlight/analytics/usage-summary`](/api/spotlight/usage-summary)        | Quick usage summary (today/week/month) |
| `GET`  | [`/spotlight/analytics/sessions`](/api/spotlight/list-sessions)             | List sessions with aggregates          |
| `GET`  | [`/spotlight/analytics/sessions/{sessionUuid}`](/api/spotlight/get-session) | Detailed session view                  |

### Session Sharing

| Method   | Endpoint                                                                               | Description                  |
| -------- | -------------------------------------------------------------------------------------- | ---------------------------- |
| `POST`   | [`/spotlight/analytics/sessions/{sessionUuid}/share`](/api/spotlight/create-share)     | Create shareable link        |
| `GET`    | [`/spotlight/analytics/sessions/{sessionUuid}/share`](/api/spotlight/get-share-status) | Get share status             |
| `DELETE` | [`/spotlight/analytics/sessions/{sessionUuid}/share`](/api/spotlight/remove-share)     | Remove sharing               |
| `GET`    | [`/spotlight/analytics/sessions/shared/{shareToken}`](/api/spotlight/view-shared)      | View shared session (public) |

## Session Tracking

Requests are grouped into sessions using the `metadata.user_id` field in your API requests:

```json theme={null}
{
  "model": "claude-sonnet-4-20250514",
  "messages": [...],
  "metadata": {
    "user_id": "my-session-id"
  }
}
```

If no `user_id` is provided, requests are grouped under a `default-session`.