Introduction

BrightBean is a YouTube intelligence API for AI agents and developer tools. It scores titles and thumbnails for click-through potential, classifies video hooks, surfaces ranked content gaps inside niches, and benchmarks channels and individual videos against their niche baselines.

Three ways to consume it

You can reach the same intelligence surface through three transports:

REST API at api.brightbean.xyz/v1/* — standard HTTP for backend services, batch jobs, and pipelines.
MCP server at api.brightbean.xyz/mcp — for Claude Desktop, Cursor, and other MCP-aware agent runtimes. Same intelligence, agent-friendly response envelopes.
SDKs and CLI — typed clients for Python and TypeScript, plus a CLI for ops and scripting.

What’s in this site

Quickstart →

Get an API key and make your first scoring call in under five minutes.

Authentication →

Bearer tokens, key rotation, and environment conventions.

API Reference →

All eight endpoints with schemas, code samples, and "Try it" requests.

MCP server →

Six tools, transport, auth, and client setup for Claude Desktop and Cursor.

SDKs & CLI →

Python, TypeScript, and the brightbean command-line tool.

Guides →

Recipes for batching, credits budgeting, and error handling.

Credits, in one paragraph

Every call deducts credits from your account balance. Free-tier accounts start with 350 credits. Cost ranges from 1 credit for the lightest scoring call up to 10 credits for hook analysis. Credits deduct only on success (2xx responses); anything else is free. You can check your balance with GET /v1/usage/ or by reading credits_remaining on any MCP response.

A note on response shapes

The REST API and MCP server document the same intelligence, but their response envelopes differ on purpose. MCP tool responses include score_id (an immutable call identifier) and credits_remaining inline; REST responses do not. See the divergence callout on the MCP overview for details.