Docs / Developers

Developer overview

Every way to connect to ChannelForge — REST API, MCP server, webhooks, automation apps and machine-readable files — and which to choose.

Everything you do in ChannelForge's app can be watched, and most of it driven, from outside it: your own code, an assistant such as Claude or ChatGPT, or an automation tool. Each way in acts for one workspace, with a key or a connection that you create, limit and revoke, and each spends credits only after it has been shown the price.

This page lists the ways in, helps you choose, and explains what they share: keys and scopes, limits, plans, the spending safeguards, and what never leaves through them.

Every way in#

Way in	What it is for	How it signs in	Where
REST API v1	JSON over HTTPS: projects, channels, episodes, jobs, prices, approvals, films, storyboards, webhooks	a workspace API key	`https://forge.storeswiki.com/api/v1` — REST API reference
MCP server	an assistant runs the workspace in conversation: check credits, quote, generate, approve, follow jobs, change schedules	OAuth sign-in (Claude, ChatGPT) or an API key (Claude Code, Cursor, n8n)	`https://forge.storeswiki.com/api/mcp` — MCP server
Webhooks	your endpoint, a Slack channel or a Discord channel is told the moment something happens	every delivery to your endpoint is signed	Settings → API & webhooks — Webhooks and REST hooks
REST hooks	instant triggers that subscribe and unsubscribe themselves (what Zapier, Make and n8n use)	an API key	`POST /api/v1/webhooks`
Event feed	polling, catching up after downtime, sample data while you build	an API key	`GET /api/v1/events`
n8n, Make and Zapier apps	automations without code: triggers and actions	an API key	n8n, Make and Zapier
OpenAPI 3.1	generating a client, Postman or Insomnia, contract tests	public, no key	`/api/v1/openapi.json`
llms.txt and pricing.md	assistants and crawlers that need to know what ChannelForge is and costs	public, no key	llms.txt, pricing.md and OpenAPI

Which one to choose#

You want to…	Use
start episodes every night from your own scheduler, within a budget	the REST API: `GET /quote`, then `POST /episodes/generate` with `max_credits`
hear when an episode is ready, held or published, without polling	a webhook on your endpoint, or a REST hook from your integration
ask "make two episodes for Load Path, no more than 500 credits" in a chat	the MCP server, connected to Claude or ChatGPT
post a message in your team's Slack or Discord channel when work finishes	a webhook with the Slack or Discord format — no code
move finished episodes into a spreadsheet, a CMS or a ticket queue	the n8n, Make or Zapier app, or a REST hook into your own tool
find out what happened while your receiver was down	the event feed, which keeps 30 days
build a client library or a typed SDK	the OpenAPI document

Most integrations combine two: the REST API to act, and webhooks to be told. Using the API: a walk-through takes one from a key to a published episode.

Plans#

The API, the MCP server, webhooks and the n8n, Make and Zapier apps are part of Pro and above (Pro, Agency and Enterprise). On a plan without them:

no key can be created, and a key made before a downgrade answers 403 with the code plan;
the MCP server refuses the workspace, and its consent screen lists it as one that cannot be connected;
events are still recorded in the workspace's feed, but webhooks are not delivered;
existing keys and endpoints stay listed in Settings → API & webhooks, so you can revoke or delete them.

Everything else the plan decides applies through the API exactly as in the app: how many channels and projects you may have, how many jobs may wait in the queue, how many GPU jobs run at once, premium quality, which platforms you may post to. Each plan's limits are on Pricing; Credits and plans explains how credits work.

Keys and scopes#

A key belongs to one workspace and acts for the whole of it, within its scopes. Owners and admins create them.

Open Settings → API & webhooks.
Under API keys, in New key, give the key a Name that says where it is used (for example "Zapier" or "nightly import").
Choose when it Expires: Never, in 30, 90 or 180 days, or in 1 year. New keys expire in 90 days unless you change it.
Tick its Scopes, then Create key.
Copy the key at once. It starts with fk_live_ and is shown only this time: ChannelForge keeps only a hash of it. If you lose it, revoke it and create another.

Send it on every request as a bearer token:

bash

curl https://forge.storeswiki.com/api/v1/me -H "Authorization: Bearer fk_live_…"

Scope	Label in the app	Through the REST API	Through MCP
`read`	Read	every `GET` — and every key can read, whatever its other scopes	`whoami`, the `list_` and `get_` tools, `quote`, `get_schedule`
`write`	Write	create a project; hold an episode back	`reject_episode`, `set_schedule`
`jobs`	Jobs	start and cancel jobs, generate and revise episodes, start, improve, release, discard and cancel films — this spends credits	`generate_episodes`, `cancel_job`, `revise_episode`
`publish`	Publish	post an episode to a connected account; approve episodes, films and storyboards; schedule a film's post	`approve_episode`, `approve_storyboard`

REST hooks (subscribing and unsubscribing a webhook through the API) work with a key of any scope, because they carry only what the key could read anyway.

A workspace holds up to 25 active keys. The list shows each key's first characters, scopes, when it was last used, when it expires and who created it. Revoke (pressed twice) stops it at once. Everything a key changes is written in the workspace's audit log with the key as the actor.

Limits#

What	Limit
Requests	120 a minute per key, the REST API and MCP together; an app connected over OAuth has its own 120 a minute
Over the limit	`429` with the code `rate_limited` and a `Retry-After` header in seconds
Active keys	25 a workspace
Webhook endpoints	the app adds one while the workspace has fewer than 10 in all; up to 50 REST hooks through the API
Event feed	the last 30 days
Links to a video or thumbnail	signed, valid for 15 minutes
An MCP message	64 KB
Work in the queue and on GPUs	your plan's limits on jobs waiting and GPU jobs at once

Spending safeguards#

Nothing that spends credits starts without a price, and you can always put a ceiling on it.

The price first. GET /api/v1/quote prices any job before it starts: what is reserved, what jobs like it typically cost on this channel, in this workspace or across ChannelForge, and why. Every request that starts work answers with the same price object.
A ceiling on every generation. POST /api/v1/episodes/generate and the MCP tool generate_episodes need max_credits. When the credits they would hold are more than that, they are refused with 409 quote and nothing is held or spent.
Holds, then the real charge. A job holds its typical cost when it starts and is charged what it really used when it ends; the rest comes back at once.
Free when it is not your fault. An episode the critic holds back, a job that fails on our side, and a queued job you cancel cost nothing.
Spending caps. Owners set a monthly cap for the workspace (Settings → Billing) and owners and admins one per channel (the channel page). A job that would pass a cap is refused with 409 cap, and error.cap says which cap, what it is, what has been spent this month, what the job needs and the month. See Billing, invoices and caps.
Retries that never double. An idempotency key makes a repeated request return the work the first one started.
A warning before you run dry. The credits.low event is sent, at most once a day, when the available credits fall below the low mark.

What never leaves through these surfaces#

YouTube's data and YouTube actions. YouTube's API terms do not allow its data, or anything worked out from it, to be passed on through an API. The REST API, MCP and webhooks carry none of YouTube's numbers or replies, and they cannot upload to YouTube: YouTube posts are made by ChannelForge on the schedules people set up in the app, or from an episode's page. See Platform policies we follow.
TikTok and Pinterest posts. Each is made by a person on the episode's own TikTok or Pinterest screen, as those platforms require.
Other platforms' numbers. A post's view count on Facebook and Instagram is given only by the REST API, to the workspace's own key. MCP and webhooks carry no platform numbers at all.
Secrets and costs. No token, signing secret, storage key or ChannelForge's own cost is ever in an answer.

Errors#

Every error has one shape, and its message is written to be shown to a person:

json

{ "error": { "code": "quote", "message": "This would hold 462 credits (2 × 231), more than max_credits 300. Nothing was queued or spent. Ask again with max_credits of at least 462." } }

Status	Codes	When
400	`invalid`, `youtube`, `url`	a wrong body or parameter; a YouTube action asked of the API; a webhook address that is refused
401	`unauthenticated`	no key, or a revoked or expired one
402	`credits`	not enough credits for the job
403	`plan`, `scope`, `made_in_app`	the plan does not include it; the key lacks the scope; an endpoint added in the app
404	`not_found`	nothing with that id in this workspace — another workspace's id answers the same — or a feature that is not on
409	`limit`, `state`, `quote`, `cap`	a plan limit; a state that does not allow it; a price above `max_credits`; a spending cap
429	`rate_limited`	more than 120 requests a minute

The REST API reference lists every route, its scope and its answers.

Using the API: a walk-through — from a key to a published episode, in curl, TypeScript and Python.
MCP server — connect Claude, ChatGPT, Cursor, Claude Code or n8n.
Webhooks and REST hooks — events, signatures, retries.
n8n, Make and Zapier — the apps, and what to use until they are listed.
System overview — how the parts behind the API fit together.

Something missing or unclear? Tell us and we will improve this page.