Developers
Connect scripts, services and AI agents to Pluto Ads with the API, the MCP server and webhooks.
Choose a way in
Everything a person does in Pluto Ads, a script or agent can do too, through the same actions, permissions and audit log.
| You want to | Use | Credential |
|---|---|---|
| Work from Claude, ChatGPT, Cursor or another AI client | MCP server | Sign in from the client. No key to copy. |
| Call Pluto Ads from your own code or server | Public API | An API key |
| Run your own agent or service without anyone signing in | Public API or MCP server | Agent credentials |
| Hear about changes as they happen | Webhooks | A signing secret |
API and MCP access is included on every plan, the free trial too. Every endpoint is in the API reference, and every error in API errors.
Settings > API
Open SettingsAPI (Settings, then API) in a workspace. What you see depends on your role, and everything on it works in that workspace only. Add at the top creates a key, agent credentials or a webhook, and each section shows once it has something in it. Your organization may let only its owners and admins create some of these: they aren't in Add for anyone else then, and what members made before keeps working. See Security.
| Section | Who sees it | What it's for |
|---|---|---|
| API keys | Admins, and roles that create API keys | Your keys for scripts, servers and integrations. Admins, and roles that manage everyone's API keys and agents, see everyone's. |
| Connect an MCP client | Everyone who may connect agents | The server URL and the setup for your AI client |
| Connected agents | Admins, and roles that manage everyone's API keys and agents | Every agent people connected in this workspace. Everyone else sees Your connected agents instead, a link to their own. |
| Agent credentials | Admins, and roles that register agent clients | A client ID and secret for an agent or service that runs on its own: yours, or everyone's for those who manage everyone's API keys and agents |
| Webhooks | Admins, and roles that manage webhooks | Signed requests to your server when something changes |
Guests don't see this page and can't use the API or connect agents.
Access
Every key, agent credential and connected agent can do what's ticked in its Access, and never more than the person it acts for can do right now: if their role changes, it follows on its next request, and if they leave, it stops. Whoever removes them can take their API keys and Service agent credentials over instead: each is re-issued to that person with a new secret, shown once, so an integration keeps working once it has the new one. See Remove someone.
Choose one of these. Full access is the default:
| Access | What it can do |
|---|---|
| View results | Look at ads, launches, analytics and spend. It can't change anything. |
| Build and publish | Also create and edit launches and drafts, upload media, comment and approve, publish to Meta or LinkedIn or X, which spends money, change live budgets and pause and resume live ads. Deleting at the platform, replying to comments, lead answers, loops, credits and the Agent aren't in it. No administration. |
| Full access | Everything you can do in the workspace, administration included. |
| Custom | Exactly what you tick in the list it opens. |
- Under the first three, one line says what the choice leaves out of what your role allows, like "Can't publish or change live ads."
- Custom opens the list in place. It has the same groups and lines as roles. Ticking a line ticks what it needs, and unticking one unticks what depends on it.
- What your role doesn't include is off, with the reason under its group. Nobody gives more than they have.
- A starting point that would tick the same lines as one above it isn't offered.
- Your organization may let members' keys or agent credentials do no more than View results or Build and publish. Then only what fits is offered, and one line says so under the widest choice; under Custom, the lines it leaves out are off with that reason. Keys and credentials made before are narrowed to it on their next request, and get back what they had when it's lifted. See Security.
- Under Custom, organization owners and admins also see Manage the organization too, for the organization's people, workspaces, plan and billing. No starting point ticks it. It needs everything under Administration and Developer access.
- Adding a paid member, changing an organization admin's access and, in an organization with one workspace, making someone an admin need Manage the organization too, whoever the key or agent acts for.
- Paying and changing ownership always stay with a person: even with Manage the organization too, a key or agent can't buy credits, turn on auto top-up or extra storage, add to an Enterprise contract, confirm a plan change that charges or open the billing portal.
In the API, scopes takes the same: a whole group by its scope name (read, review, write, publish, admin,
organization) and single capabilities by their ID, like ads:publish. Send what each needs beside it too, like
ads:read: the API refuses a capability without it, naming what's missing. See Scopes.
Create an API key
Ad accounts
A key or agent credentials with Chosen ad accounts works only in those:
- It sees only what's in them: their launches and ads, their insights, leads from their ads, and the jobs it started
itself. What's in another ad account answers as if it didn't exist (
404), and lists leave it out. - It's refused anything in another ad account, and anything that names one for something new, like a launch:
403with "This credential works only in the ad accounts it was given." The audit log records it. - Your inbox, Agent chats, loops, plans and bulk edits show only when everything they're about is in its ad accounts; one about nothing in an ad account (a notice, a loop that watches every ad account) stays hidden from it.
- Leads and comments on ads show by the ad they came through. Organic leads, lead forms and comments on a Page's other posts show only when every ad account that publishes from that Page is one of its own.
- Pluto Profit's store figures, reading every Page's leads or comments now, and syncing every ad account or importing all their insights at once span every ad account: it gets them only when it works in all of them, and names its own ad accounts instead.
- What's in no ad account is the workspace's, and it works with it as before: the media library, drafts without an ad account, statuses, labels and templates.
- It can't use what spans every ad account: the Agent and loops (they act as you everywhere), people, integrations, everyone's API keys and agents, the audit log and the organization. Full access says so in its line, and the key shows it.
- A webhook it creates sends only events of its ad accounts. A key or agent credentials it creates works in no more ad accounts than it does.
In the API, send resources: { "adAccounts": ["act_123", ...] }, or "all". See
Ad accounts.
The key is shown once: we store only a hash of it. A key that only views results starts with pk_live_ and every
other key with sk_live_. Send it as Authorization: Bearer <key>. See the quickstart.
Your organization may limit how long new keys last. Never isn't offered then, and the line under Expires says the limit, like "Your organization limits credentials to 90 days." Its owners and admins aren't limited. See Security.
Keys and agent credentials made through the API or an agent last 90 days too, or your organization's limit when that's shorter, unless they say when they end or that they never do. See Expiry and allowed addresses.
The list shows each key's Name, what it can do in words, like "Can view results and publish", its ad accounts ("All ad accounts", or their names), and the addresses it works from when it has some, then when it was Created, when it was Last used and from which address, and when it Expires. It lists your own keys. Admins, and roles that manage everyone's API keys and agents, see everyone's, with who Made by each, and rotate or revoke any of them.
- Rotate key..., then Rotate key, replaces a key with a new one with the same name, access, expiry and addresses. The old key stops at once, and the new one is shown once under API key rotated. As when you revoke it, the API keys and agent credentials the old key made are revoked with it, and the webhooks it made are turned off: a key you rotate may have leaked, and so may what was made with it. Rotating someone else's key makes the new one yours, so it can do only what your role allows: a key with access you don't have can't be rotated by you.
- Narrow access... gives a key less access while it keeps its secret, so nothing changes where it's used but what it may do. It opens the same choices as creating one, offering only what the key can do now and the ad accounts it works in now, without an expiry or addresses. Select Save: from its next request it does only what you kept. Narrowing never adds access or ad accounts, and what the key made keeps its own access.
- Revoke key..., then Revoke key, turns a key off. Apps using it lose access right away. The API keys and agent credentials it made, through the API or an agent using it, are revoked with it, and the webhooks it made are turned off.
In an organization with several workspaces, organization owners and admins see every key and agent on the organization's API page in Settings, and whoever manages everyone's API keys and agents in a workspace sees that workspace's, with the person each acts for and who made it, and can revoke any of them. See API.
A key, agent credentials or a connected agent that expires reminds the person it acts for in their Inbox 7 days before, and again the day before, with a link to SettingsAPI (Settings, then API). They get an email too when they turn on Expiring keys and agents by email in SettingsNotifications (Settings, then Notifications). See Notification settings. The audit log shows when it expired.
Agent credentials
For your own agent or service that shouldn't hold a long-lived key.
Both types are held to what your organization lets members' agent credentials do: when it lets them only view, they get View results and nothing more. See Security.
Your service trades them for a short-lived access token. See Agent credentials. The list shows what each can do, its ad accounts, when it Expires and the addresses it works from.
- Rotate secret..., then Rotate secret, gives them a new secret, shown once under Secret rotated. The old secret and the tokens it got stop working at once. The Client ID stays the same, so only the secret changes where they're used, and what they made keeps working.
- Narrow access... gives them less access, as for a key, while the client ID and secret stay.
- Revoke credentials..., then Revoke credentials, stops them on their next request. The API keys and agent credentials they made are revoked with them, and the webhooks they made are turned off.
While Members can connect agents is off, only agent credentials an organization owner or admin made keep working, and only they can create new ones. See Who can connect agents.
Webhooks
A workspace can have up to 20 webhooks. The list shows each one's Last delivery. Show deliveries opens Recent deliveries with each attempt's Event, Status, Attempts, Response and when it was Sent. Delete webhook..., then Delete webhook, stops deliveries at once, retries included. A webhook also stops when the person who created it, or whose key or agent did, is suspended, removed or leaves the workspace: create a new one to keep receiving events.
A webhook sends only while that person may manage webhooks in the workspace. If their role changes and no longer includes it, or the key or agent that created it stops working, it sends nothing, and the list says why under its endpoint, like "Not delivering: Maya's role no longer includes managing webhooks". It starts again by itself when their role includes it again. What happened in between isn't sent later.
How deliveries look, how to verify them and every event are in Webhooks.
Good to know
- Keys, agents and webhooks belong to one workspace. To work in another, create a key there or connect an agent to it.
- Rate limits are per key and per workspace. See Rate limits.
- Changing a webhook's URL or events, rotating its secret and sending a test event are done through the API.
- The audit log in SettingsAudit log (Settings, then Audit log) shows every change a key or agent made, and who it acted for. Each use of admin or organization access is there too, reads and refused requests included, with the request ID and the status the API answered (for an MCP tool, how the call went). When an agent connects for the first time, the log names the app it connected from.
- A call refused for access the key or agent doesn't have is in the audit log too, with the capability it needed
(
missingCapability, the same as the error names) and what it was at, once a minute per key or agent, capability and entry point. Refused reads aren't.