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, and Claude sends you to a page here. Sign in if you are not already, and the page tells you who is asking and what they will be able to reach, as you, including your private drafts and ideas. It also says plainly that the app’s name is whatever the app told us, and that we have not checked it.

There is one choice on that page, which organisation’s team data the connection may read, and then one Connect button. The permissions themselves are the ones the assistant asked for, so the page states them rather than offering you a pick list. No key changes hands.

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

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, marks posts as published, and schedules a finished piece to publish at a day and time you give it.

Be precise about that last one, because it is the one power on this list that reaches outside the app. A write token cannot publish to LinkedIn on the spot, and marking something as posted only records that you did it. But it CAN set a schedule, and a schedule publishes to your own LinkedIn profile at its time with nobody present. The piece is visible in Ready with its time on it the whole while, and one press in the app calls it off, so a schedule you did not ask for is something you can see and stop, not something that happens silently. If that is more than you want an assistant to hold, use a read token.

What no token can do, whichever scope it has, is 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.