# SpotCheck — Full Technical Specification for AI Agents

> SpotCheck is a Spotify playlist validation and curator bot-detection tool designed to help artists and promoters identify fake, botted playlists before spending money on placement campaigns. Live at https://spotcheck.cc.

## System Architecture & Endpoints

### 1. Bot Risk Scoring
- **Endpoint**: `GET /api/check?playlist={url_or_id}`
- **Response Format**: JSON
- **Output Fields**:
  - `playlist`: Object containing `{ id, name, curator, followers, tracks, url }`
  - `botRisk`: Object containing `{ score, level, factors, historical }`
    - `score`: Integer 0-100 (0 = low risk/legit, 100 = critical bot risk).
    - `level`: String (`"low"`, `"medium"`, `"high"`).
    - `factors`: Array of triggered risk flags:
      - `round_followers`: Followers end in exact multiples of 1,000 or 10,000.
      - `thin_description`: No curator info or suspicious placement terms.
      - `follower_track_ratio`: Extreme follower count with very few tracks.
      - `generic_naming`: Generic playlist title matching known bot farm templates.

### 2. Curator Contact Extraction
- **Endpoint**: `POST /api/curator-contacts`
- **Payload**: `{ "playlist_id": "1PmwMQY86pJuAm7veFt3u2" }`
- **Authentication**: Bearer Token (Premium Plan) or x402 Payment Protocol (`0.10 GBP`).
- **Output Fields**:
  - `found`: Boolean
  - `curator`: String (Spotify owner display name)
  - `emails`: Array of parsed email addresses
  - `socials`: Array of `{ platform, handle, url }`
  - `links`: Array of submission URLs
  - `curatedTip`: Pitching tip string (if present in directory)

### 3. Machine Payment Protocols (x402 & MPP)
- **x402**: Standard HTTP 402 responses containing `X-402-Price`, `X-402-Currency`, and `X-402-Facilitator`.
- **MPP**: Operations in `https://spotcheck.cc/openapi.json` are annotated with `x-payment-info`.

### 4. Discovery Standards
- API Catalog: `https://spotcheck.cc/.well-known/api-catalog`
- MCP Server Card: `https://spotcheck.cc/.well-known/mcp/server-card.json`
- Agent Skills Index: `https://spotcheck.cc/.well-known/agent-skills/index.json`
- OAuth Protected Resource: `https://spotcheck.cc/.well-known/oauth-protected-resource`
- OpenAPI Specification: `https://spotcheck.cc/openapi.json`
- ChatGPT Plugin Manifest: `https://spotcheck.cc/.well-known/ai-plugin.json`