Connect a script or an AI assistant

Everything you can see in the app, you can reach programmatically: your pieces, your plan, your campaigns, your wins, and the team’s activity. There are two ways in, and which one you want depends on who is doing the asking.

An API key, for your own code

Go to My settings → API & MCP and create a key. Name it after the thing that will use it, so that revoking one later doesn’t take the others down with it.

The key is shown once, at the moment you create it. It isn’t stored anywhere we can read, so if you lose it you create a new one, and nothing can recover the old.

Use it as a bearer token. Put it in an environment variable rather than typing it into a command, so it doesn’t end up in your shell history:

export THESTORY_API_KEY="the key you just copied"

curl https://api.thestory.run/v1/pieces \
  -H "Authorization: Bearer $THESTORY_API_KEY"

The full list of endpoints, parameters and response shapes lives at /v1/openapi.json, that file is generated from the running code, so it can’t drift from what the API actually does.

MCP, for Claude and other assistants

MCP is how an AI assistant connects to a tool without you pasting a key into a chat window. In My settings → API & MCP you’ll find the MCP server URL. Add it as a connector in Claude; Claude opens a page here asking what you want to allow, and you approve it. No key changes hands.

An assistant connected this way can list your pieces, read your plan, look at campaigns and activity, capture an idea, and mark a post as published.

What a token can and cannot do

Both kinds of access carry one of two scopes:

• Read lists your pieces, plan, campaigns, wins and the team’s activity.
• Write additionally captures ideas and marks posts as published.

Two things no token can do, whichever scope it has. It cannot publish to a social network on your behalf, marking something as posted records that you did it, it doesn’t do it. And it cannot run or read a coach conversation: the interview transcripts are not on the API, and there is no endpoint that makes the coach ask you anything.

Be clear-eyed about what a read token CAN see, though, because it is more than the published work. It reads your pieces at every stage, drafts included, with the text you wrote in them, and it reads your plan: your topics and how often you set out to post. A read token is therefore worth protecting like a password, and revoking one is a single press in settings.

A token acts as you, and reaches organisation data through your membership. If you leave an organisation, anything using your token loses access to that organisation with you.

If you’re in more than one organisation

A key carries your own permissions in every organisation you belong to, so it doesn’t have to be recreated per organisation. Which one a request reads is up to the request: send the organisation id in an X-Org-Id header.

curl https://api.thestory.run/v1/orgs \
  -H "Authorization: Bearer $THESTORY_API_KEY"

curl https://api.thestory.run/v1/campaigns \
  -H "Authorization: Bearer $THESTORY_API_KEY" \
  -H "X-Org-Id: 0b1f…"

GET /v1/orgs lists the ids you may use, and marks which one is active. Leave the header off and you get that active one, the organisation you last switched to in the app. For a script that runs unattended, name the organisation explicitly: otherwise what it reads changes the next time you use the switcher in a browser.

An MCP connection works differently on purpose. It is pinned to the single organisation you picked when you approved it, and asking it for another one is refused rather than quietly answered.

Taking access back

My settings → API & MCP lists every key and every connected app. Revoking a key or disconnecting an app takes effect on its very next request, with no grace period.

An app’s name is what it told us when it registered, and we don’t verify it. If you see something you don’t recognise, disconnect it.