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

​
Endpoints

​
Model Proxy

EndpointMethodDescription
/spotlight/anthropic/v1/messagesPOSTSend messages to Claude (streaming supported)
/spotlight/anthropic/v1/messages/count_tokensPOSTCount tokens for a request
/spotlight/anthropic/api/event_logging/batchPOSTSend event logs to Anthropic

​
Analytics

EndpointMethodDescription
/spotlight/analytics/tokensGETToken usage analytics
/spotlight/analytics/sessionsGETList sessions with aggregates
/spotlight/analytics/sessions/:sessionUuidGETDetailed session view

​
Session Sharing

EndpointMethodDescription
/spotlight/analytics/sessions/:sessionUuid/sharePOSTCreate shareable link
/spotlight/analytics/sessions/:sessionUuid/shareGETGet share status
/spotlight/analytics/sessions/:sessionUuid/shareDELETERemove sharing
/spotlight/analytics/sessions/shared/:shareTokenGETView 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.