Skip to main content

​
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

ProviderBase PathFeatures
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 (recommended)
  2. Pass credentials directly in the request using the x-api-key header
Subscription-based access is not supported. Spotlight requires API keys from the Anthropic Console. OAuth tokens from Claude subscriptions (e.g., Claude Pro/Team subscriptions) cannot be used and will return a 403 Forbidden error.

​
Endpoints

​
Model Proxy

MethodEndpointDescription
POST/spotlight/anthropic/v1/messagesSend messages to Claude (streaming supported)
POST/spotlight/anthropic/v1/messages/count_tokensCount tokens for a request

​
Analytics

MethodEndpointDescription
GET/spotlight/analytics/tokensToken usage analytics by model
GET/spotlight/analytics/usage-summaryQuick usage summary (today/week/month)
GET/spotlight/analytics/sessionsList sessions with aggregates
GET/spotlight/analytics/sessions/{sessionUuid}Detailed session view

​
Session Sharing

MethodEndpointDescription
POST/spotlight/analytics/sessions/{sessionUuid}/shareCreate shareable link
GET/spotlight/analytics/sessions/{sessionUuid}/shareGet share status
DELETE/spotlight/analytics/sessions/{sessionUuid}/shareRemove sharing
GET/spotlight/analytics/sessions/shared/{shareToken}View shared session (public)

​
Session Tracking

Requests are grouped into sessions using the metadata.user_id field in your API requests: 
{
  "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.