# Vid0 developers: API and MCP

> The Vid0 API is a JSON REST API at https://api.vid0.in. It's the same API the Vid0 Chrome extension and MCP server use. Authenticate with a personal API token.

The endpoints below are described in an OpenAPI 3.1 spec at https://vid0.in/openapi.json, with typed parameters and response schemas, ready for API tools and LLM function calling. The API isn't versioned for third parties yet: endpoints live under `/v1` and can change. For anything you'd like stable, email support@vid0.in.

## Authentication

1. Sign in at https://vid0.in/login and open **Settings → API tokens**.
2. Name a token and click **Create token**. It starts with `yti_` and is shown once. Revoke it on the same card.
3. Send it on every request: `Authorization: Bearer yti_…`

A token acts as you in your current workspace. Creator tools need a token from a creator workspace, and brand tools one from a brand workspace; the API answers `403` when a token is used on the other side's routes.

```bash
curl -H "Authorization: Bearer $VID0_TOKEN" https://api.vid0.in/v1/me
```

## Endpoints

| Method and path | What it returns |
|---|---|
| `GET /health` | Service status (no token needed) |
| `GET /v1/me` | Your user, workspace and plan |
| `GET /v1/quota` | Today's YouTube API quota buckets |
| `GET /v1/videos/{id}/insights` | One video vs. its channel baseline: outlier ×, expected views, views per hour, engagement |
| `GET /v1/channels/{ref}` | Channel stats, top outliers and latest uploads. ref is an @handle, a UC… channel id or a channel URL (URL-encoded) |
| `GET /v1/channels/{ref}/best-time` | Best weekdays and hours to post, from public uploads |
| `GET /v1/outliers` | Videos beating their channel's baseline. Query: channels (comma-separated ids; defaults to your tracked competitors), format (long, short or all), minScore (default 2), maxAgeDays (1–365, default 90), limit (1–200, default 60) |
| `GET /v1/keywords?q={keyword}` | Competition, demand and opportunity scores for a keyword, plus the videos ranking for it. Optional mySubs (your subscriber count) adds "winnable for you". Uses one keyword lookup from your plan |

Derived numbers (outlier ×, expected views, scores, prices) are labelled "Vid0 estimate, not YouTube data".

## Errors

Errors are JSON with a code, a message and a request id you can quote back to us:

```json
{ "error": { "code": "unauthorized", "message": "Sign in to continue.", "requestId": "…" } }
```

- `400` `bad_request`: invalid parameters or body
- `401` `unauthorized`: missing, invalid or revoked token
- `402` `limit_reached`: the workspace's plan limit for this feature is used up
- `403` `forbidden`: the token's workspace kind (creator or brand) can't use this route
- `404` `not_found`: unknown route, video or channel
- `429` `quota_exhausted`: today's YouTube API quota is used up, or you're sending too many requests

## MCP server

Vid0 has an MCP server with 34 tools: outliers, video and channel analysis, keyword research, your channel's analytics, title and thumbnail scoring, scripts, the content calendar, the ideas board and sponsorships. It speaks stdio and Streamable HTTP (`POST /mcp`, `Authorization: Bearer yti_…`). A hosted endpoint isn't public yet; email support@vid0.in for early access.

## For agents

Every public page has a Markdown version: send `Accept: text/markdown` or add `.md` to the path. The site map for agents, with when to use Vid0, is at https://vid0.in/llms.txt. The API is listed in the RFC 9727 API catalog at https://vid0.in/.well-known/api-catalog, which points to the OpenAPI spec, these docs and the health check.

## Links

- [OpenAPI spec](https://vid0.in/openapi.json)
- [API catalog](https://vid0.in/.well-known/api-catalog)
- [llms.txt](https://vid0.in/llms.txt)
- [Contact](https://vid0.in/contact.md)
- [Terms of Service](https://vid0.in/terms.md)