Developers

Developer source of truth for API, headers, and discovery

The external API, API key workflow, MCP transport, and machine-readable discovery files are documented here with the live paths used by the product.

API keys

Create and revoke keys in Dashboard > Settings > API Keys, or use the signed-in management routes.

Professional and Enterprise only.

REST API

Call https://www.tubeanalytics.net/api/external/v1 with Bearer auth.

JSON responses with structured errors.

MCP transport

Connect agents to https://www.tubeanalytics.net/api/mcp or use npm run mcp:stdio.

Streamable HTTP and stdio supported.

Discovery files

Use /openapi.json, /mcp.json, /ai-pricing.json, and /ai.txt as the machine-readable source of truth.

Always current with the live routes.

How to connect

Connect a YouTube channel in the dashboard

External API data comes from connected channels. Sign in, connect a channel, and wait for the initial sync to complete before making server-to-server calls.

Create an API key

Open Dashboard > Settings > API Keys on a Professional or Enterprise account, or call POST /api/v1/keys from an authenticated session.

Send Bearer-authenticated requests

Use Authorization: Bearer <api_key> on every external request. Keep keys server-side and do not embed them in client code.

Use discovery files for tools and agents

Pull the OpenAPI spec, MCP manifest, ai-pricing manifest, and ai.txt file when generating clients, connecting agents, or validating integrations.

Canonical cURL example

Live endpoint

curl -X GET "https://www.tubeanalytics.net/api/external/v1/analytics?channel_id=<channel_id>&range=28d" \
  -H "Authorization: Bearer <api_key>" \
  -H "Accept: application/json"

channel_id accepts either the TubeAnalytics channel ID or the YouTube channel ID. The same Bearer key also works for the other external endpoints below.

Reference endpoints

Endpoint

Method

Description

https://www.tubeanalytics.net/api/external/v1/channels

GET

List connected channels for the authenticated account

https://www.tubeanalytics.net/api/external/v1/channels/:channelId

GET

Fetch one connected channel by internal ID or YouTube channel ID

https://www.tubeanalytics.net/api/external/v1/analytics?channel_id=...

GET

Aggregate channel analytics for a selected time range

https://www.tubeanalytics.net/api/external/v1/videos?channel_id=...

GET

List channel videos with paging and sorting

https://www.tubeanalytics.net/api/external/v1/audience?channel_id=...

GET

Get audience demographics, subscriber health, and segments

https://www.tubeanalytics.net/api/external/v1/competitors

GET

List tracked competitor channels

The discovery files at /openapi.json,/mcp.json, and/ai.txt are the machine-readable source of truth.

Authentication and headers

External requests use the Bearer API key scheme in the Authorization header. Keep the key server-side. Create and rotate keys from Dashboard > Settings > API Keys or the signed-in management routes.

Authorization: Bearer <api_key>
Accept: application/json
Content-Type: application/json
Rate-limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Retry header: Retry-After on 429 responses

Signed-in management routes

These routes are for authenticated dashboard sessions, not server-to-server API clients:

GET /api/v1/keys list API keys
POST /api/v1/keys create a new API key
DELETE /api/v1/keys/:keyId revoke a key
GET /api/v1/users/profile and related dashboard session routes remain separate

API keys are available on Professional and Enterprise plans only. Starter users see an upgrade prompt in Settings.

Access and limits

The pricing surface advertises monthly API call allowances by plan, while the live external API enforces a sliding-window request limit and returns rate-limit headers on every response. Keep both in mind when building client retries and quota dashboards.

Plan

API access

Monthly allowance

Request limit

Starter

1 channel max channels

Unavailable

Upgrade required

No external API access

Professional

3 channels max channels

Enabled

5,000 calls / month

1,000 requests/hour

Enterprise

5 channels max channels

Enabled

20,000 calls / month

10,000 requests/hour

In the current implementation, the external API returns X-RateLimit-Limit,X-RateLimit-Remaining, andX-RateLimit-Reset on successful responses, plusRetry-After when a request is limited.

Error format

External API routes return structured JSON errors with error.code anderror.message. Use the code to branch on error handling and the message for human-readable logs.

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "channel_id query parameter is required"
  }
}

Common statuses

400 Missing or invalid request parameters
401 Missing or invalid API key
403 API key valid but the plan is not eligible
404 Connected channel or resource not found
429 Rate limit exceeded
500 Unexpected server error

Need to manage keys quickly?

Jump straight to the dashboard settings area to create, copy, or revoke API keys on supported plans.

Open API Keys View OpenAPI