# Fishtank — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access clips, episodes, contestant information, and live stream updates from Fishtank.live to browse content, check leaderboard rankings, and track live broadcast status. Get detailed information about specific clips and episodes, or discover random clips and current stox data.

**Category:** Streaming Video | **Website:** [fishtank.live/](https://fishtank.live/) | **Docs:** [parse.bot/marketplace/3189d8fe-1a41-4431-9b8f-c7b3e453a4b3/fishtank-live-api](https://parse.bot/marketplace/3189d8fe-1a41-4431-9b8f-c7b3e453a4b3/fishtank-live-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Get clip detail

Retrieve full details and comments for a specific clip by its numeric ID. Returns the clip metadata, the creator's display name, and a paginated list of comments with user profiles and nested replies.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `clip_id` | string | Yes | The numeric ID of the clip (e.g., '398178'). Obtainable from get_clips results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-clip-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"clip_id":"<string>"}'
```

### Get clips

Search and retrieve clips with paginated results and optional filters. Supports sorting by engagement (hot_score) or view count. Filters by room, season, and text search can be combined. Returns a page of clips and the total matching count for pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number (1-indexed). |
| `page_size` | integer | No | Number of clips per page. |
| `room` | string | No | Filter by room name (e.g., 'Bedroom 1', 'Director Mode', 'Laundry Room', 'Bar', 'Cameraman'). |
| `search` | string | No | Text search query to filter clips by name. |
| `season` | string | No | Filter by season (e.g., 'Season 4', 'Season 5'). |
| `sort` | string | No | Sort order for clips. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-clips \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","page_size":"<integer>","room":"<string>","search":"<string>","season":"<string>","sort":"<string>"}'
```

### Get episode detail

Retrieve comments for a specific episode by its UUID. Returns the episode UUID and a list of comments with full user profiles and nested replies.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `uuid` | string | Yes | The UUID of the episode (e.g., '3a682dce-bf86-4d40-8601-89d0cfcd3b6a'). Obtainable from get_episodes results. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-episode-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"uuid":"<string>"}'
```

### Get episodes

Retrieve the complete list of all available episodes organized by season or category. Each category maps to an array of episodes with metadata including title, duration, and thumbnail URL.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-episodes \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get initial data

Retrieve site metadata including active contestants, current poll state, recent TTS messages, feature toggles, and the current site announcement. Returns all bootstrap data needed to render the site's initial state.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-initial-data \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get leaderboard

Retrieve the top users leaderboard ranked by XP. Returns the top 30 users with their display name, XP total, token balance, and medal counts.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-leaderboard \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get live streams

Retrieve current live stream definitions and their online statuses. Returns the stream list with playback IDs, season, access level, and interactive flag, plus load balancer mappings and status per stream.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-live-streams \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get random clip

Retrieve a random clip from the entire clip library. Returns a single clip object with full metadata. Useful for discovery or random content surfacing.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-random-clip \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Get stox

Retrieve contestant stock prices (Stox) including current price, IPO price, average price, total shares, and order book data. Orders array is empty when unauthenticated.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/fishtank/get-stox \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.