Quick Start

Getting started with the Subscribr API is straightforward. Within a few minutes, you can generate your first API token and make your first request.

The Subscribr API provides programmatic access to your team's channels, scripts, and YouTube intelligence data. All requests require Bearer token authentication and are subject to rate limits based on your subscription plan.

1

Generate an API token

Navigate to your Subscribr dashboard settings and generate an API token with the required permissions (abilities) for your use case. Tokens are tied to your team and inherit your plan's rate limits.

2

Make your first request

Use curl or any HTTP client to make a request to the API. Include your token in the Authorization header as a Bearer token.

3

Explore further

Check out the endpoint documentation below to see what you can do with the API. Most endpoints return JSON and include examples in their documentation.

bash

curl -X GET https://subscribr.ai/api/v1/team \
  -H "Authorization: Bearer sk_live_your_token_here" \
  -H "Accept: application/json"

Need help?

If you run into any issues getting started, check out the Authentication and Errors sections below, join our Discord community at discord.gg/ZdUA4jEnU2, or contact [email protected] for assistance.

Core Concepts

Understanding how Subscribr's key resources relate to each other and how to work with them via the API.

YouTube Intel

YouTube Intelligence endpoints provide data about YouTube channels and videos. Look up specific channels by URL or handle, search for channels and videos, and bookmark your findings. This data is sourced from YouTube and external intelligence services.

POST /api/v1/intel/channels/lookup

Teams

Teams are the top-level organization unit in Subscribr. All API tokens are scoped to a team, and all resources (channels, scripts, ideas) belong to a team. Teams have subscription plans, credit balances, and can manage API tokens.

GET /api/v1/team

Channels

A Channel is the top-level container for your content creation work. Each channel represents either a YouTube channel or a content planning space. Channels hold voice profiles, audience information, and serve as the parent for scripts and ideas.

GET /api/v1/channels

Ideas

Ideas are content concepts within a channel. They can be created manually or generated by AI. Ideas serve as the basis for scripts and can be developed into full scripts with titles, outlines, and content.

POST /api/v1/channels/{channel}/ideas

Scripts

A Script is a video project within a channel. Scripts progress through multiple stages from outline to full draft. You can generate scripts from ideas, export them, and poll generation status.

POST /api/v1/channels/{channel}/scripts

Typical Workflow

1

List your channels to find the one you want to work with (GET /channels)

2

Create ideas manually or generate them from competitor videos

3

Write/develop ideas to add structure and details

4

Generate outlines and scripts for your ideas

5

Export the finished script in your preferred format

6

Set up webhooks to be notified when generation is complete

Authentication

The Subscribr API uses Bearer token authentication. All requests must include a valid API token in the Authorization header.

API authentication uses Bearer tokens issued by your Subscribr account. These tokens are tied to your team and include specific abilities (permissions) that control what the token can access.

bash

curl -X GET https://subscribr.ai/api/v1/team \
  -H "Authorization: Bearer sk_live_your_token_here"

Team-scoped tokens

Each API token is bound to the team that created it. Tokens can only access resources (channels, scripts, ideas) that belong to their team. You cannot use a token from one team to access another team's data.

Available Token Abilities

When creating an API token, you specify which abilities it should have. These abilities determine what resources the token can access.

Ability	Description
intel:read	Read-only access to YouTube Intel lookup, search, and bookmark retrieval endpoints
intel:write	Create and delete Intel bookmarks (requires intel:read)
scripts:read	Read scripts, ideas, and script content
scripts:write	Create scripts and ideas, generate outlines and scripts (requires scripts:read)
channels:read	List and get channel details, templates, and voices
webhooks:read	List and get webhook details
webhooks:write	Create, update, and delete webhooks (requires webhooks:read)

Rate Limits

The Subscribr API implements rate limiting to ensure fair usage and maintain service quality.

Rate limits are enforced per API token and are based on your subscription plan. Different endpoints have different rate limits depending on their computational cost.

Rate Limits by Endpoint Category

Category	Limit	Notes
General API	50 requests/minute	Default limit for most endpoints
Channel/Video Search	5 requests/minute	Resource-intensive semantic search
Script Generation	5 requests/minute	AI generation endpoints
Channel/Video Lookup	50 requests/minute	Fast direct lookups by ID or handle

Rate Limit Response Headers

Every API response includes these headers with current rate limit status:

Header	Description
X-RateLimit-Limit	The maximum number of requests allowed in the current window
X-RateLimit-Remaining	The number of requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the rate limit window resets
Retry-After	Seconds to wait before retrying (only present on 429 responses)

Errors

The API returns standard HTTP status codes to indicate the success or failure of requests.

All API error responses include a JSON body with details about what went wrong. Use these responses to debug integration issues.

HTTP Status Codes

Code	Meaning	Common Causes
200	OK	Request succeeded
201	Created	Resource was successfully created
400	Bad Request	Invalid request parameters or malformed JSON
401	Unauthorized	Missing or invalid API token
403	Forbidden	Token lacks required abilities for this endpoint
404	Not Found	Resource doesn't exist or belongs to different team
409	Conflict	Resource state conflict (e.g., duplicate creation)
422	Validation Failed	Request data failed validation
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error (please contact support)