Full access & MCP
Most keys only read. A key you create with Full access can also start work - one article, a batch, a research report or a domain audit - and publish a finished one, from your own code or from an AI assistant.
The permission is fixed at creation
When you mint a key in Settings → Account → API access you choose Read only, which is the default, or Full access. There is no switch afterwards. A read-only key stays read-only for its whole life, and to get a spending key you create a new one - the database grants the permission when the row is inserted and never on an update, so this is not a rule the interface is politely asking you to follow.
Every key that existed before full access was introduced is a read-only key, and nothing about it changed.
It acts as the person who created it
A full-access key is not a separate account with its own budget. Work it starts is done as its owner, through the same guards the dashboard goes through: the newsroom's hourly ceiling, the plan's allowance, that person's permission to spend in the newsroom, accepted terms and an open account. If they could not start it in the dashboard, the key cannot start it either.
A key is stamped with the newsroom its owner was in when it was made. If that person later moves to another newsroom, the key stops rather than billing the new one: 403 wrong_newsroom. Create a new key there.
20 paid actions an hour, per key
On top of everything above, each full-access key may start at most 20 paid actions an hour. An article, one row of a batch, a report and an audit each count one. The count is per key, so a second key has its own, and a read-only key never spends from it.
Going over is a 429 rate_limited with Retry-After: 60, and nothing is started. A batch is cut at the room left rather than refused whole - the rows that fit start, and every row past the limit comes back in refused with its position and the reason. Keys live in scripts and leak more often than logins, so this ceiling exists to make the blast radius of a leaked key a number rather than an allowance.
The whole-account archive is separate
One file containing everything the account owns is a dashboard job, not an API one: Settings → Account → Download everything. See Rate limits & errors for what /v1/exports answers.
The five doors
The first four answer 202 with an id and start the work in the background. Publish is the odd one out and the heaviest: it answers when the post is live, so there is nothing to poll.
| Endpoint | Starts |
|---|---|
| /v1/editions/{slug}/articles | Commission one article on a domain. Answers 202 with a job id. |
| /v1/editions/{slug}/articles/batch | Up to 100 articles on one domain in a single call, with a refusal reason per row. |
| /v1/editions/{slug}/research | Commission a research report on a domain. Answers 202 with a report id. |
| /v1/editions/{slug}/audit | Crawl a domain you have verified and audit what is there. Answers 202 with a crawl id. |
| /v1/editions/{slug}/articles/{article_id}/publish | Put a finished article live on the domain's connected site. |
An article job is polled on GET /v1/jobs/{job_id}. A report and an audit each have their own path, named on their pages, because neither is an article job. Those two paths carry the finished result as well as the progress, and any key of yours can read them - a result you have already paid for is a read, so it needs no Full access and spends nothing.
MCP
The same four actions are available over MCP, so Claude Code, Cursor or any MCP client can start work in your newsroom. The server is streamable HTTP and the credential is the same API key you already hold.
https://api.mastheads.app/v1/mcpThe address and a config block to paste are in the dashboard under Settings → Developer.
| Tool | What it starts |
|---|---|
| write_article | One article on a domain. Takes domain_id and input, and the same optional id. |
| write_articles | Up to 100 at once. Takes domain_id and inputs, each row a string or an object with input and id. |
| run_research | A research report on a domain. Takes domain_id. |
| run_audit | A whole-domain audit. Takes domain_id. |
| publish_article | Puts a finished article live on the domain's connected site. |
All five appear only to a full-access key. Connect with a read-only key and the tool list is the read tools alone, so an assistant cannot offer to spend something it was never handed. They go through the same door as the endpoints above - the same 20 an hour, the same allowance, the same refusals - and they take the same optional id, so an assistant that retries after a timeout does not commission the work twice. Reading a finished research report or audit is on the read side, listed to every key.
Connecting an app
Claude Code, Cursor and VS Code take the key directly, as above. Claude.ai, ChatGPT and Claude Desktop connect a different way: point them at the same address and you sign in with your Mastheads login rather than pasting anything.
Signing in shows you a consent screen with a single choice - Let this app spend - which is off unless you turn it on, and is never pre-ticked. Leave it off and the app reads; turn it on and it can start work and publish, under the same 20 an hour and the same allowance as any other key. Like a key, that choice is fixed at the moment you allow it.
Connected apps are listed in the dashboard under Settings → Developer, each with Disconnect, which does exactly what revoking a key does and takes effect on the next request. They are counted separately from the three keys you make by hand.
Plan access
Full access is on the same plans as the rest of the API: Growth and Pro. There is no separate charge for it - work a key starts is metered exactly like work started in the dashboard, out of the same allowance.