### Local Development Setup and Backend Start

Source: https://github.com/shinzo-labs/shinzo/blob/main/README.md

These commands outline the steps to set up Shinzo for local development. It includes installing backend dependencies using pnpm and then starting the backend server. This setup requires Node.js 18+ and pnpm.

```bash
# Install dependencies
cd backend && pnpm install

# Start the backend
pnpm start
```

--------------------------------

### Ubuntu PostgreSQL Installation Commands

Source: https://github.com/shinzo-labs/shinzo/blob/main/db/README.md

Commands to install and configure a PostgreSQL database on an Ubuntu system. This includes setting the password for the postgres user, updating access control and configuration files, and restarting the PostgreSQL service.

```bash
sudo -u postgres psql template1
alter user postgres with encrypted password 'postgres';
sudo sh -c "echo 'host    all             all             0.0.0.0/0               md5' >> /etc/postgresql/12/main/pg_hba.conf"
vim /etc/postgresql/12/main/postgresql.conf
# Inside vim, set listen_addresses = '*'
sudo systemctl restart postgresql.service
```

--------------------------------

### Shinzo Environment Database Configuration

Source: https://github.com/shinzo-labs/shinzo/blob/main/db/README.md

Example environment variable settings for connecting to the Shinzo PostgreSQL database. It shows the format for both the default 'postgres' user and a custom user.

```bash
# In backend/.env or your environment
DATABASE_URL=postgresql://postgres:password@localhost:5432/shinzo_platform
# Or for custom user:
# DATABASE_URL=postgresql://shinzo_user:your_secure_password@localhost:5432/shinzo_platform
```

--------------------------------

### Shinzo Database and User Creation

Source: https://github.com/shinzo-labs/shinzo/blob/main/db/README.md

SQL commands to create a new database named 'shinzo_platform' and an optional user 'shinzo_user' for the Shinzo application. It also shows how to connect to the database and set a password for the custom user, granting necessary privileges.

```bash
sudo -u postgres createdb shinzo_platform
sudo -u postgres createuser shinzo_user
sudo -u postgres psql shinzo_platform
alter user shinzo_user with encrypted password 'your_secure_password';
grant all privileges on database shinzo_platform to shinzo_user;
```

--------------------------------

### GET /telemetry/fetch_traces

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Query traces with filtering options.

```APIDOC
## GET /telemetry/fetch_traces

### Description
Query traces with filtering options.

### Method
GET

### Endpoint
`/telemetry/fetch_traces`

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer JWT token for authentication.

#### Query Parameters
- **start_date** (string) - Optional - Start date for filtering traces (YYYY-MM-DD format).
- **end_date** (string) - Optional - End date for filtering traces (YYYY-MM-DD format).
- **service_name** (string) - Optional - Filter traces by service name.

### Request Example
```bash
curl "http://localhost:8000/telemetry/fetch_traces?start_date=2026-01-01&end_date=2026-01-08&service_name=my-ai-agent" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **traces** (array) - An array of trace objects.
  - **uuid** (string) - Unique identifier for the trace.
  - **trace_id** (string) - The trace identifier.
  - **service_name** (string) - The name of the service associated with the trace.
  - **operation_name** (string) - The name of the operation performed.
  - **start_time** (string) - The start time of the trace (ISO 8601 format).
  - **end_time** (string) - The end time of the trace (ISO 8601 format).
  - **status** (string) - The status of the trace (e.g., `ok`).
  - **span_count** (integer) - The number of spans in the trace.

#### Response Example
```json
{
  "traces": [
    {
      "uuid": "trace-uuid-1",
      "trace_id": "0123456789abcdef0123456789abcdef",
      "service_name": "my-ai-agent",
      "operation_name": "llm.completion",
      "start_time": "2026-01-08T10:00:00.000Z",
      "end_time": "2026-01-08T10:00:02.000Z",
      "status": "ok",
      "span_count": 5
    }
  ]
}
```
```

--------------------------------

### Start Specific Docker Service

Source: https://github.com/shinzo-labs/shinzo/blob/main/README.md

Starts a specific service defined in the docker-compose.yml file in detached mode. Replace `<backend|frontend|redis|kafka>` with the actual service name.

```bash
docker-compose up -d <backend|frontend|redis|kafka>
```

--------------------------------

### Docker Deployment for Shinzo Services

Source: https://github.com/shinzo-labs/shinzo/blob/main/README.md

This snippet shows how to deploy Shinzo services using Docker Compose. It covers starting supporting services like Redis and Kafka in detached mode, or launching all services including the backend and frontend with a build command.

```bash
# Start supporting services (Redis, Kafka)
docker-compose up -d redis kafka

# Or start all services including backend and frontend
docker-compose up --build -d
```

--------------------------------

### Fetch Traces with cURL

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Queries and fetches trace data, supporting filtering by start date, end date, and service name. The request is a GET to /telemetry/fetch_traces, requiring an Authorization header. The response includes trace details such as UUID, trace ID, service name, operation name, time range, status, and span count.

```bash
curl "http://localhost:8000/telemetry/fetch_traces?start_date=2026-01-01&end_date=2026-01-08&service_name=my-ai-agent" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

```json
{
  "traces": [
    {
      "uuid": "trace-uuid-1",
      "trace_id": "0123456789abcdef0123456789abcdef",
      "service_name": "my-ai-agent",
      "operation_name": "llm.completion",
      "start_time": "2026-01-08T10:00:00.000Z",
      "end_time": "2026-01-08T10:00:02.000Z",
      "status": "ok",
      "span_count": 5
    }
  ]
}
```

--------------------------------

### Backend and Frontend Environment Configuration

Source: https://github.com/shinzo-labs/shinzo/blob/main/README.md

This snippet demonstrates how to configure environment variables for the backend and frontend of the Shinzo application. It involves copying example files and editing them with specific settings like database URLs and API endpoints. The backend runs on port 8000, frontend on 3000, and OpenTelemetry on ports 4317 (GRPC) and 4318 (HTTP).

```bash
cp backend/.env.example backend/.env
# Edit backend/.env with your database URL and other settings

cp frontend/.env.example frontend/.env
# Edit frontend/.env with your API URL and other frontend settings
```

--------------------------------

### GET /telemetry/fetch_resources

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieve all resources (services) that have sent telemetry data.

```APIDOC
## GET /telemetry/fetch_resources

### Description
Retrieve all resources (services) that have sent telemetry data.

### Method
GET

### Endpoint
`/telemetry/fetch_resources`

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer JWT token for authentication.

### Request Example
```bash
curl http://localhost:8000/telemetry/fetch_resources \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **resources** (array) - An array of resource objects.
  - **uuid** (string) - Unique identifier for the resource.
  - **service_name** (string) - Name of the service.
  - **service_version** (string) - Version of the service.
  - **service_namespace** (string) - Namespace of the service.
  - **first_seen** (string) - Timestamp when the resource was first seen (ISO 8601 format).
  - **last_seen** (string) - Timestamp when the resource was last seen (ISO 8601 format).

#### Response Example
```json
{
  "resources": [
    {
      "uuid": "resource-uuid-1",
      "service_name": "my-ai-agent",
      "service_version": "1.0.0",
      "service_namespace": "production",
      "first_seen": "2026-01-01T00:00:00.000Z",
      "last_seen": "2026-01-08T23:16:00.000Z"
    }
  ]
}
```
```

--------------------------------

### GET /auth/fetch_user_quota

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Check the current usage quota and limits for the authenticated user.

```APIDOC
## GET /auth/fetch_user_quota

### Description
Check current usage quota and limits.

### Method
GET

### Endpoint
/auth/fetch_user_quota

### Request Example
```bash
curl http://localhost:8000/auth/fetch_user_quota \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **subscription_tier** (string) - The user's current subscription tier.
- **monthly_quota** (integer) - The total monthly quota allowed.
- **monthly_counter** (integer) - The current usage counter for the month.
- **remaining_quota** (integer) - The remaining quota for the month.
- **last_counter_reset** (string) - Timestamp when the counter was last reset.
- **next_reset** (string) - Timestamp for the next counter reset.

#### Response Example
```json
{
  "subscription_tier": "free",
  "monthly_quota": 10000,
  "monthly_counter": 3500,
  "remaining_quota": 6500,
  "last_counter_reset": "2026-01-01T00:00:00.000Z",
  "next_reset": "2026-02-01T00:00:00.000Z"
}
```
```

--------------------------------

### GET /spotlight/analytics/sessions/{SESSION_UUID}

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieve detailed information for a specific AI agent session, including interactions.

```APIDOC
## GET /spotlight/analytics/sessions/{SESSION_UUID}

### Description
Retrieve detailed information for a specific AI agent session, including its interactions.

### Method
GET

### Endpoint
/spotlight/analytics/sessions/{SESSION_UUID}

#### Path Parameters
- **SESSION_UUID** (string) - Required - The unique identifier of the session to retrieve.

### Request Example
```bash
curl http://localhost:8000/spotlight/analytics/sessions/SESSION_UUID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **session** (object) - Details of the requested session.
  - **uuid** (string) - Unique identifier for the session.
  - **session_id** (string) - The session ID.
  - **started_at** (string) - Timestamp when the session started.
  - **ended_at** (string) - Timestamp when the session ended.
- **interactions** (array) - An array of interaction objects within the session.
  - **uuid** (string) - Unique identifier for the interaction.
  - **timestamp** (string) - Timestamp of the interaction.
  - **model** (string) - The AI model used for the interaction.
  - **input_tokens** (integer) - Input tokens for this interaction.
  - **output_tokens** (integer) - Output tokens for this interaction.
  - **messages** (array) - An array of messages exchanged in the interaction.
    - **role** (string) - The role of the message sender (user or assistant).
    - **content** (string) - The content of the message.
  - **tools_used** (array) - A list of tools used in the interaction.

#### Response Example
```json
{
  "session": {
    "uuid": "session-uuid-1",
    "session_id": "sess_abc123",
    "started_at": "2026-01-08T10:00:00.000Z",
    "ended_at": "2026-01-08T10:15:00.000Z"
  },
  "interactions": [
    {
      "uuid": "interaction-uuid-1",
      "timestamp": "2026-01-08T10:00:00.000Z",
      "model": "claude-3-opus-20240229",
      "input_tokens": 250,
      "output_tokens": 125,
      "messages": [
        {
          "role": "user",
          "content": "Hello, how can I help you?"
        },
        {
          "role": "assistant",
          "content": "I'm here to assist you with any questions."
        }
      ],
      "tools_used": []
    }
  ]
}
```
```

--------------------------------

### Get User Preferences

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieves a user's preferences, optionally filtering by a specific preference key. Requires JWT authentication. Returns a list of matching preferences.

```bash
# Get user preferences
curl "http://localhost:8000/user/preferences?preference_key=theme" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Dbmate Database Operations

Source: https://github.com/shinzo-labs/shinzo/blob/main/db/README.md

Common database operations for the Shinzo project using the dbmate command-line tool. This includes migrating the database schema, rolling back migrations, generating schema dumps, and creating new migration files.

```bash
dbmate up
dbmate down
dbmate dump
dbmate new <migration_name>
```

--------------------------------

### GET /spotlight/analytics/sessions

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieve a list of AI agent session analytics within a specified date range.

```APIDOC
## GET /spotlight/analytics/sessions

### Description
Retrieve and analyze AI agent session data within a specified date range.

### Method
GET

### Endpoint
/spotlight/analytics/sessions

#### Query Parameters
- **start_date** (string) - Required - The start date for the session analytics period (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the session analytics period (YYYY-MM-DD).

### Request Example
```bash
curl "http://localhost:8000/spotlight/analytics/sessions?start_date=2026-01-01&end_date=2026-01-08" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **sessions** (array) - An array of session analytics objects.
  - **uuid** (string) - Unique identifier for the session.
  - **session_id** (string) - The session ID.
  - **started_at** (string) - Timestamp when the session started.
  - **ended_at** (string) - Timestamp when the session ended.
  - **duration_seconds** (integer) - Duration of the session in seconds.
  - **interaction_count** (integer) - Number of interactions in the session.
  - **total_input_tokens** (integer) - Total input tokens for the session.
  - **total_output_tokens** (integer) - Total output tokens for the session.
  - **models_used** (array) - A list of models used during the session.

#### Response Example
```json
{
  "sessions": [
    {
      "uuid": "session-uuid-1",
      "session_id": "sess_abc123",
      "started_at": "2026-01-08T10:00:00.000Z",
      "ended_at": "2026-01-08T10:15:00.000Z",
      "duration_seconds": 900,
      "interaction_count": 12,
      "total_input_tokens": 3000,
      "total_output_tokens": 1500,
      "models_used": ["claude-3-opus-20240229"]
    }
  ]
}
```
```

--------------------------------

### GET /user/preferences

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieve user preferences, optionally filtering by a specific preference key.

```APIDOC
## GET /user/preferences

### Description
Retrieve user preferences.

### Method
GET

### Endpoint
/user/preferences

#### Query Parameters
- **preference_key** (string) - Optional - The key of the preference to retrieve.

### Request Example
```bash
curl "http://localhost:8000/user/preferences?preference_key=theme" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **preferences** (array) - An array of preference objects.
  - **preference_key** (string) - The key identifying the preference.
  - **preference_value** (string) - The value of the preference.
  - **updated_at** (string) - Timestamp when the preference was last updated.

#### Response Example
```json
{
  "preferences": [
    {
      "preference_key": "theme",
      "preference_value": "dark",
      "updated_at": "2026-01-08T23:16:00.000Z"
    }
  ]
}
```
```

--------------------------------

### GET /spotlight/analytics/tokens

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieve token usage analytics for a specified period and model. Supports filtering by date range and model.

```APIDOC
## GET /spotlight/analytics/tokens

### Description
Retrieve token usage analytics with filtering and aggregation.

### Method
GET

### Endpoint
/spotlight/analytics/tokens

#### Query Parameters
- **start_date** (string) - Required - The start date for the analytics period (YYYY-MM-DD).
- **end_date** (string) - Required - The end date for the analytics period (YYYY-MM-DD).
- **model** (string) - Optional - The specific model to filter analytics by.

### Request Example
```bash
curl "http://localhost:8000/spotlight/analytics/tokens?start_date=2026-01-01&end_date=2026-01-08&model=claude-3-opus-20240229" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **analytics** (array) - An array of token usage data for each day.
  - **date** (string) - The date of the analytics entry.
  - **model** (string) - The AI model used.
  - **total_input_tokens** (integer) - Total input tokens for the day.
  - **total_output_tokens** (integer) - Total output tokens for the day.
  - **total_cost** (number) - Total cost incurred for the day.
  - **request_count** (integer) - Number of requests made.
- **summary** (object) - A summary of the total token usage and cost for the period.
  - **total_input_tokens** (integer) - Total input tokens for the period.
  - **total_output_tokens** (integer) - Total output tokens for the period.
  - **total_cost** (number) - Total cost for the period.
  - **total_requests** (integer) - Total number of requests for the period.

#### Response Example
```json
{
  "analytics": [
    {
      "date": "2026-01-08",
      "model": "claude-3-opus-20240229",
      "total_input_tokens": 15000,
      "total_output_tokens": 8000,
      "total_cost": 0.75,
      "request_count": 50
    },
    {
      "date": "2026-01-07",
      "model": "claude-3-opus-20240229",
      "total_input_tokens": 12000,
      "total_output_tokens": 6500,
      "total_cost": 0.62,
      "request_count": 42
    }
  ],
  "summary": {
    "total_input_tokens": 27000,
    "total_output_tokens": 14500,
    "total_cost": 1.37,
    "total_requests": 92
  }
}
```
```

--------------------------------

### GET /spotlight/analytics/sessions/shared/{share_token}

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieve details of a shared session using its share token. No authentication required.

```APIDOC
## GET /spotlight/analytics/sessions/shared/{share_token}

### Description
Retrieve shared session details using a public link. No authentication is required.

### Method
GET

### Endpoint
/spotlight/analytics/sessions/shared/{share_token}

#### Path Parameters
- **share_token** (string) - Required - The token identifying the shared session.

### Request Example
```bash
curl http://localhost:8000/spotlight/analytics/sessions/shared/share_abcdef123456
```

### Response
#### Success Response (200)
- **session** (object) - Details of the shared session.
  - **session_id** (string) - The session ID.
  - **started_at** (string) - Timestamp when the session started.
  - **ended_at** (string) - Timestamp when the session ended.
- **interactions** (array) - An array of interaction objects within the session.

#### Response Example
```json
{
  "session": {
    "session_id": "sess_abc123",
    "started_at": "2026-01-08T10:00:00.000Z",
    "ended_at": "2026-01-08T10:15:00.000Z"
  },
  "interactions": [...] 
}
```
```

--------------------------------

### Fetch Resources with cURL

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieves a list of all resources (services) that have sent telemetry data to the system. This is done via a GET request to the /telemetry/fetch_resources endpoint, requiring an Authorization header with a JWT token.

```bash
curl http://localhost:8000/telemetry/fetch_resources \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

```json
{
  "resources": [
    {
      "uuid": "resource-uuid-1",
      "service_name": "my-ai-agent",
      "service_version": "1.0.0",
      "service_namespace": "production",
      "first_seen": "2026-01-01T00:00:00.000Z",
      "last_seen": "2026-01-08T23:16:00.000Z"
    }
  ]
}
```

--------------------------------

### OAuth Authentication - Google API

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Facilitates user authentication via Google OAuth. Includes endpoints to get the OAuth URL and to handle the callback with an authorization code.

```bash
# Get Google OAuth URL
curl http://localhost:8000/auth/oauth/google?returnTo=/dashboard

# Response
{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
}

# Handle OAuth callback
curl -X POST http://localhost:8000/auth/oauth/google/callback \
  -H "Content-Type: application/json" \
  -d '{
    "code": "4/0AY0e-g7...",
    "returnTo": "/dashboard"
  }'

# Success response (200)
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@gmail.com",
    "oauth_provider": "google"
  }
}
```

--------------------------------

### Get Shared Session Detail

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieves details of a shared session using its share token. No authentication is required for this endpoint. Returns session and interaction data.

```bash
# Get shared session detail (no auth required)
curl http://localhost:8000/spotlight/analytics/sessions/shared/share_abcdef123456
```

--------------------------------

### Verify Backend Health

Source: https://github.com/shinzo-labs/shinzo/blob/main/README.md

This command is used to verify that the Shinzo backend service is running correctly after deployment or startup. It sends an HTTP GET request to the backend's health endpoint.

```bash
curl http://localhost:8000/health
```

--------------------------------

### User Authentication - Create User API

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Allows for the creation of new user accounts. Requires email, password, first name, and last name. Returns a success message with a user UUID or an error if the email already exists.

```bash
# Create new user
curl -X POST http://localhost:8000/auth/create_user \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!",
    "first_name": "John",
    "last_name": "Doe"
  }'

# Success response (200)
{
  "message": "User created successfully. Please check your email to verify your account.",
  "userUuid": "550e8400-e29b-41d4-a716-446655440000"
}

# Error response (400)
{
  "error": "Email already exists"
}
```

--------------------------------

### GET /telemetry/fetch_spans

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Query spans for a specific trace.

```APIDOC
## GET /telemetry/fetch_spans

### Description
Query spans for a specific trace.

### Method
GET

### Endpoint
`/telemetry/fetch_spans`

### Parameters
#### Header Parameters
- **Authorization** (string) - Required - Bearer JWT token for authentication.

#### Query Parameters
- **trace_id** (string) - Required - The unique identifier of the trace for which to fetch spans.

### Request Example
```bash
curl "http://localhost:8000/telemetry/fetch_spans?trace_id=0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (200)
- **spans** (array) - An array of span objects associated with the trace.
  - **uuid** (string) - Unique identifier for the span.
  - **trace_id** (string) - The trace identifier.
  - **span_id** (string) - The span identifier.
  - **parent_span_id** (string) - The parent span identifier.
  - **operation_name** (string) - The name of the operation performed by the span.
  - **service_name** (string) - The name of the service associated with the span.
  - **start_time** (string) - The start time of the span (ISO 8601 format).
  - **end_time** (string) - The end time of the span (ISO 8601 format).
  - **status** (string) - The status of the span (e.g., `ok`).
  - **attributes** (object) - Key-value pairs of attributes associated with the span.

#### Response Example
```json
{
  "spans": [
    {
      "uuid": "span-uuid-1",
      "trace_id": "0123456789abcdef0123456789abcdef",
      "span_id": "0123456789abcdef",
      "parent_span_id": "",
      "operation_name": "llm.completion",
      "service_name": "my-ai-agent",
      "start_time": "2026-01-08T10:00:00.000Z",
      "end_time": "2026-01-08T10:00:02.000Z",
      "status": "ok",
      "attributes": {
        "llm.model": "claude-3-opus",
        "llm.token_count": 1500
      }
    }
  ]
}
```
```

--------------------------------

### Fetch Provider API Keys

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieves a list of configured AI provider API keys. Requires a JWT token for authentication.

```bash
curl http://localhost:8000/spotlight/provider_keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Fetch All Shinzo API Keys

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieves a list of all existing Shinzo API keys associated with the authenticated user. Requires a JWT token for authentication.

```bash
curl http://localhost:8000/spotlight/shinzo_keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Create Provider API Key

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Creates a new entry for an AI provider API key. Requires authentication with a JWT token. The request body includes the provider, API key, and an optional label.

```bash
curl -X POST http://localhost:8000/spotlight/provider_keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "anthropic",
    "provider_api_key": "sk-ant-api03-…",
    "provider_base_url": null,
    "label": "My Anthropic Key"
  }'
```

--------------------------------

### Fetch Session Detail

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieves detailed information for a specific AI agent session using its UUID. Requires JWT authentication. Includes session metadata and a list of interactions.

```bash
# Fetch session detail
curl http://localhost:8000/spotlight/analytics/sessions/SESSION_UUID \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### User Authentication API

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Handles user registration and login, including JWT token generation.

```APIDOC
## POST /auth/create_user

### Description
Registers a new user account with email, password, and name.

### Method
POST

### Endpoint
`/auth/create_user`

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.
- **first_name** (string) - Required - The user's first name.
- **last_name** (string) - Required - The user's last name.

### Request Example
```json
{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "first_name": "John",
  "last_name": "Doe"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message.
- **userUuid** (string) - The unique identifier for the newly created user.

#### Response Example
```json
{
  "message": "User created successfully. Please check your email to verify your account.",
  "userUuid": "550e8400-e29b-41d4-a716-446655440000"
}
```

#### Error Response (400)
- **error** (string) - Error message, e.g., "Email already exists".

#### Response Example
```json
{
  "error": "Email already exists"
}
```

## POST /auth/login

### Description
Authenticates an existing user and returns a JWT token upon successful login.

### Method
POST

### Endpoint
`/auth/login`

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "email": "user@example.com",
  "password": "SecurePassword123!"
}
```

### Response
#### Success Response (200)
- **token** (string) - The JSON Web Token for authenticated requests.
- **user** (object) - User details.
  - **uuid** (string) - The user's unique identifier.
  - **email** (string) - The user's email address.
  - **first_name** (string) - The user's first name.
  - **last_name** (string) - The user's last name.
  - **subscription_tier** (string) - The user's subscription tier.

#### Response Example
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "subscription_tier": "free"
  }
}
```

#### Error Response (401)
- **error** (string) - Error message, e.g., "Invalid credentials".

#### Response Example
```json
{
  "error": "Invalid credentials"
}
```
```

--------------------------------

### OAuth Authentication API

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Handles initiation and callback for OAuth authentication flows, including Google.

```APIDOC
## GET /auth/oauth/google

### Description
Initiates the Google OAuth 2.0 authentication flow by redirecting the user to Google's authorization server.

### Method
GET

### Endpoint
`/auth/oauth/google`

### Parameters
#### Query Parameters
- **returnTo** (string) - Optional - The URL to redirect to after successful authentication.

### Request Example
```bash
curl http://localhost:8000/auth/oauth/google?returnTo=/dashboard
```

### Response
#### Success Response (200)
- **url** (string) - The URL to redirect the user to for Google authentication.

#### Response Example
```json
{
  "url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=..."
}
```

## POST /auth/oauth/google/callback

### Description
Handles the callback from Google after the user has authorized the application, exchanging the authorization code for tokens.

### Method
POST

### Endpoint
`/auth/oauth/google/callback`

### Parameters
#### Request Body
- **code** (string) - Required - The authorization code received from Google.
- **returnTo** (string) - Optional - The URL to redirect to after successful authentication.

### Request Example
```json
{
  "code": "4/0AY0e-g7...",
  "returnTo": "/dashboard"
}
```

### Response
#### Success Response (200)
- **token** (string) - The JWT token for the authenticated user.
- **user** (object) - User details.
  - **uuid** (string) - The user's unique identifier.
  - **email** (string) - The user's email address.
  - **oauth_provider** (string) - The OAuth provider used for authentication (e.g., "google").

#### Response Example
```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@gmail.com",
    "oauth_provider": "google"
  }
}
```
```

--------------------------------

### POST /spotlight/analytics/sessions/{SESSION_UUID}/share

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Create a shareable public link for a given session.

```APIDOC
## POST /spotlight/analytics/sessions/{SESSION_UUID}/share

### Description
Share session details via a public link.

### Method
POST

### Endpoint
/spotlight/analytics/sessions/{SESSION_UUID}/share

#### Path Parameters
- **SESSION_UUID** (string) - Required - The unique identifier of the session to share.

### Request Example
```bash
curl -X POST http://localhost:8000/spotlight/analytics/sessions/SESSION_UUID/share \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

### Response
#### Success Response (201)
- **share_token** (string) - The token used to access the shared session.
- **share_url** (string) - The public URL to view the shared session.
- **created_at** (string) - Timestamp when the share link was created.

#### Response Example
```json
{
  "share_token": "share_abcdef123456",
  "share_url": "https://app.shinzo.ai/shared/share_abcdef123456",
  "created_at": "2026-01-08T23:16:00.000Z"
}
```
```

--------------------------------

### Create Session Share Link

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Generates a public shareable link for a specific session using its UUID. Requires JWT authentication. Returns a share token and URL.

```bash
# Create session share link
curl -X POST http://localhost:8000/spotlight/analytics/sessions/SESSION_UUID/share \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Create Shinzo API Key

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Creates a new API key for accessing AI model proxy services. Requires a JWT token for authentication. The request body specifies the key name and type.

```bash
curl -X POST http://localhost:8000/spotlight/shinzo_keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "key_name": "Production Agent",
    "key_type": "live"
  }'
```

--------------------------------

### View Docker Service Logs

Source: https://github.com/shinzo-labs/shinzo/blob/main/README.md

Streams the logs of a specific Docker service in real-time. Replace `<service-name>` with the name of the service whose logs you want to view.

```bash
docker-compose logs -f <service-name>
```

--------------------------------

### Provider Key Management

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Configure and test API keys for various AI providers.

```APIDOC
## POST /spotlight/provider_keys/test

### Description
Test an AI provider API key for validity without saving it.

### Method
POST

### Endpoint
`/spotlight/provider_keys/test`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **provider** (string) - Required - The name of the AI provider (e.g., 'anthropic').
- **provider_api_key** (string) - Required - The API key for the provider.
- **provider_base_url** (string) - Optional - The base URL for the provider's API.

### Request Example
```json
{
  "provider": "anthropic",
  "provider_api_key": "sk-ant-api03-...",
  "provider_base_url": null
}
```

### Response
#### Success Response (200)
- **valid** (boolean) - True if the key is valid, false otherwise.
- **message** (string) - A message indicating the result of the test.

#### Response Example
```json
{
  "valid": true,
  "message": "Provider key is valid"
}
```

## POST /spotlight/provider_keys

### Description
Create and save a new AI provider API key.

### Method
POST

### Endpoint
`/spotlight/provider_keys`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **provider** (string) - Required - The name of the AI provider (e.g., 'anthropic').
- **provider_api_key** (string) - Required - The API key for the provider.
- **provider_base_url** (string) - Optional - The base URL for the provider's API.
- **label** (string) - Required - A label for the provider key.

### Request Example
```json
{
  "provider": "anthropic",
  "provider_api_key": "sk-ant-api03-...",
  "provider_base_url": null,
  "label": "My Anthropic Key"
}
```

### Response
#### Success Response (201)
- **uuid** (string) - The unique identifier for the provider key.
- **provider** (string) - The name of the AI provider.
- **label** (string) - The label assigned to the key.
- **status** (string) - The status of the provider key (e.g., 'active').
- **created_at** (string) - The timestamp when the key was created.

#### Response Example
```json
{
  "uuid": "provider-key-uuid",
  "provider": "anthropic",
  "label": "My Anthropic Key",
  "status": "active",
  "created_at": "2026-01-08T23:16:00.000Z"
}
```

## GET /spotlight/provider_keys

### Description
Fetch all configured provider API keys.

### Method
GET

### Endpoint
`/spotlight/provider_keys`

### Parameters
None

### Response
#### Success Response (200)
- (Array of provider key objects)
```

--------------------------------

### Fetch User Quota

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Retrieves the current user's quota information, including limits, usage, and reset dates. Requires JWT authentication. Provides insights into subscription tier and remaining quota.

```bash
# Fetch user quota
curl http://localhost:8000/auth/fetch_user_quota \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### Fetch Spans for a Trace with cURL

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Fetches detailed span information for a specific trace, identified by its trace ID. This is achieved via a GET request to the /telemetry/fetch_spans endpoint, which requires the trace ID as a query parameter and an Authorization header.

```bash
curl "http://localhost:8000/telemetry/fetch_spans?trace_id=0123456789abcdef0123456789abcdef" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

--------------------------------

### User Authentication - Login API

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Authenticates a user using their email and password, returning a JWT token upon successful login. Handles credential validation and user information retrieval.

```bash
# Login
curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePassword123!"
  }'

# Success response (200)
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "subscription_tier": "free"
  }
}

# Error response (401)
{
  "error": "Invalid credentials"
}
```

--------------------------------

### POST /user/preferences

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Save or update a user's preference. Requires a preference key and value.

```APIDOC
## POST /user/preferences

### Description
Store and retrieve user-specific preferences.

### Method
POST

### Endpoint
/user/preferences

#### Request Body
- **preference_key** (string) - Required - The key identifying the preference.
- **preference_value** (string) - Required - The value of the preference.

### Request Example
```json
{
  "preference_key": "theme",
  "preference_value": "dark"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the preference was saved.

#### Response Example
```json
{
  "message": "Preference saved successfully"
}
```
```

--------------------------------

### Shinzo API Key Management

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Create, retrieve, update, and delete API keys for accessing AI models through Shinzo.

```APIDOC
## POST /spotlight/shinzo_keys

### Description
Create a new Shinzo API key.

### Method
POST

### Endpoint
`/spotlight/shinzo_keys`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **key_name** (string) - Required - The name for the API key.
- **key_type** (string) - Required - The type of key, e.g., 'live'.

### Request Example
```json
{
  "key_name": "Production Agent",
  "key_type": "live"
}
```

### Response
#### Success Response (201)
- **uuid** (string) - The unique identifier for the API key.
- **key_name** (string) - The name of the API key.
- **api_key** (string) - The generated API key.
- **key_prefix** (string) - The prefix of the API key.
- **key_type** (string) - The type of the API key.
- **status** (string) - The status of the API key (e.g., 'active').
- **created_at** (string) - The timestamp when the key was created.

#### Response Example
```json
{
  "uuid": "key-uuid-1",
  "key_name": "Production Agent",
  "api_key": "sk_live_shinzo_abcdef123456",
  "key_prefix": "sk_live_shinzo",
  "key_type": "live",
  "status": "active",
  "created_at": "2026-01-08T23:16:00.000Z"
}
```

## GET /spotlight/shinzo_keys

### Description
Fetch all Shinzo API keys associated with the account.

### Method
GET

### Endpoint
`/spotlight/shinzo_keys`

### Parameters
None

### Response
#### Success Response (200)
- (Array of Shinzo API key objects)

## PUT /spotlight/shinzo_keys/{KEY_UUID}

### Description
Update an existing Shinzo API key.

### Method
PUT

### Endpoint
`/spotlight/shinzo_keys/{KEY_UUID}`

### Parameters
#### Path Parameters
- **KEY_UUID** (string) - Required - The UUID of the API key to update.

#### Query Parameters
None

#### Request Body
- **key_name** (string) - Optional - The new name for the API key.
- **status** (string) - Optional - The new status for the API key (e.g., 'inactive').

### Request Example
```json
{
  "key_name": "Updated Name",
  "status": "inactive"
}
```

### Response
#### Success Response (200)
- (Updated Shinzo API key object)

## DELETE /spotlight/shinzo_keys/{KEY_UUID}

### Description
Delete a Shinzo API key.

### Method
DELETE

### Endpoint
`/spotlight/shinzo_keys/{KEY_UUID}`

### Parameters
#### Path Parameters
- **KEY_UUID** (string) - Required - The UUID of the API key to delete.

#### Query Parameters
None

### Response
#### Success Response (204)
No content on successful deletion.
```

--------------------------------

### Retrieve Token Usage Analytics

Source: https://context7.com/shinzo-labs/shinzo/llms.txt

Fetches token usage analytics with options for date range and model filtering. Requires JWT authentication. Returns a list of daily analytics and a summary.

```bash
# Fetch token analytics
curl "http://localhost:8000/spotlight/analytics/tokens?start_date=2026-01-01&end_date=2026-01-08&model=claude-3-opus-20240229" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```