# FSB Sentinel Developer API — Specification & Telemetry Schema

> An open, keyless developer API providing real-time Twitter/X profile telemetry, algorithmic shadowban diagnostics, timeline performance intelligence, and reach metrics.

## Canonical Base URLs
- Primary Root: `https://visiuun.com/fsb/`
- Documentation: `https://visiuun.com/fsb/docs/`
- LLM Specification: `https://visiuun.com/fsb/docs/llms.txt`

## Authentication & Fair Use
- **Type**: Free / Public / No API Key Required.
- **Rate Limit**: 15 requests per 60-second rolling window per client IP.
- **Headers Returned**:
  - `X-RateLimit-Limit`: Maximum requests permitted per minute (15).
  - `X-RateLimit-Remaining`: Count of remaining requests in the active window.
  - `X-RateLimit-Reset`: Unix timestamp when the quota refreshes.
  - `Retry-After`: Seconds to wait before retry when 429 status is returned.

## Endpoints

### 1. Account Inspection & Telemetry
**GET** `https://visiuun.com/fsb/?api={username}`
**GET** `https://visiuun.com/fsb/?api&target={username}`

#### Query Parameters
| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `api` | string | Optional | Can pass handle inline: `?api=elonmusk` |
| `target` | string | Optional | Target Twitter handle without `@`: `?api&target=elonmusk` |
| `username` | string | Optional | Alias for `target`: `?api&username=elonmusk` |

#### Success Response Model (200 OK)
```json
{
  "success": true,
  "status": "ok",
  "data": {
    "profile": {
      "username": "elonmusk",
      "name": "Elon Musk",
      "avatar": "https://pbs.twimg.com/profile_images/.../image_400x400.jpg",
      "avatar_proxy": "https://visiuun.com/fsb/?ajax=avatar_proxy&target=elonmusk",
      "bio": "...",
      "location": "...",
      "joined": "June 2009",
      "verified": true,
      "is_blue_verified": true,
      "stats": {
        "followers": 195000000,
        "following": 720,
        "posts_count": 52000,
        "likes_count": 45000,
        "follower_to_following_ratio": 270833.33
      },
      "url": "https://x.com/elonmusk"
    },
    "shadowban": {
      "is_shadowbanned": false,
      "status": "Clean",
      "health_score": 100,
      "active_restrictions": [],
      "tests": {
        "search_ban": { "detected": false, "label": "Search Ban" },
        "search_suggestion_ban": { "detected": false, "label": "Search Suggestion Ban" },
        "ghost_ban": { "detected": false, "label": "Ghost Ban" },
        "reply_deboosting": { "detected": false, "label": "Reply Deboosting" },
        "possibly_sensitive": { "detected": false, "label": "Sensitive Profile" }
      }
    },
    "post_intelligence": {
      "sample_size": 40,
      "average_likes_per_post": 45210.5,
      "average_retweets_per_post": 6240.2,
      "average_replies_per_post": 3120.8,
      "average_views_per_post": 12500000,
      "engagement_rate_percent": 2.34,
      "link_penalty_exposure_percent": 12.5,
      "media_richness_percentage": 45.0,
      "outliers": {
        "best_performing": { ... },
        "highest_algorithmic_impact": { ... },
        "most_discussed": { ... },
        "lowest_performing": { ... }
      }
    },
    "telemetry": {
      "trackers_count": 12,
      "active_viewers_count": 3,
      "last_checked": 1728234900,
      "cached": true,
      "api_source": "direct_diagnostic"
    },
    "latest_posts": {
      "count": 40,
      "posts": [ ... ]
    }
  }
}
```

### 2. Error Responses
- **400 Bad Request**: Invalid username or empty input.
- **403 Forbidden**: Access through untrusted datacenter proxies, scraper user-agents, or Tor.
- **404 Not Found**: Account non-existent, deleted, or suspended.
- **429 Too Many Requests**: Hourly/minutely quota exceeded (15 req/min).
- **502 Bad Gateway**: Upstream Twitter/X diagnostics temporarily busy.