Developers
The API page in the sidebar is where admins give scripts, services and agents access to the workspace, and where webhooks are set up. This page covers what is on it. The details of each request are in the API reference.
API page
Every member can open the API page (guests can't). What you see depends on your role:
| Section | Who sees it | What it is for |
|---|---|---|
| API keys | Admins | Keys for scripts, servers and integrations. |
| Connect an MCP client | Everyone | The server URL, and the command or config for Claude, ChatGPT, Cursor, Claude Code, VS Code or Codex. These clients sign in, so no key is needed. See Agents. |
| Connected agents | Everyone | Agents people connected by signing in from their client, or that registered with auth.md and were confirmed. You see your own; admins see everyone's. |
| Agent credentials | Admins | A client ID and secret for an agent or service that runs on its own, without anyone signing in. |
| Webhooks | Admins | Signed requests to your server when something changes. |
Docs at the top of the page opens this documentation. Once there are keys, Create key sits next to it. Everything on the page belongs to the workspace you're in: a key, credential or webhook works in that workspace only.
API keys
Select Create key, give it a Name, and choose the Access:
| Access | Starts with | What it can do |
|---|---|---|
| Read only | pk_live_ | Look at launches, ads, media and results. It can never change anything. |
| Read and write | sk_live_ | Also draft launches, edit ads, add media and comment. It can't publish or change budgets. |
| Read, write and publish | sk_live_ | Also publish approved launches and change live budgets, which spends money. |
| Workspace admin | sk_live_ | Also manage this workspace: members and guests, API keys, webhooks, the Meta connection and settings. It can't change the organization or its billing. |
| Organization admin | sk_live_ | Also manage the organization: its people, workspaces, plan, usage limits, extra storage and billing details. Payments and ownership changes always stay with a person. |
Publishing spends money, so it is its own level: a Read and write key never publishes. Workspace admins can give up to Workspace admin; only organization owners and admins can give Organization admin. A key never does more than the person it belongs to can do right now: if their role changes, the key follows on its next request, and if they leave, it stops. Before someone leaves, an organization owner or admin can take their keys over through the API: each key is issued again to that admin with a new secret.
A key can also expire by itself: under Expires, choose 30 days, 90 days or 1 year, or keep No expiry.
The key appears once, under API key created, with Copy it now. You won't see it again. We store only a hash of it, so nobody can show it to you later. Lost it? Rotate it, or revoke it and create a new one.
The list shows each key's name, the first characters of the key, its Access, when it was Created, when it was Last used (or Never used) and from which address, and when it Expires (or Never). Select Revoke, then Revoke key, to turn a key off. Apps using it lose access at once, and it can't be undone. Rotate, then Rotate key, gives you a new key with the same name, access and expiry and turns the old one off in the same step; the new key is shown once, under New API key.
A key never gets a permission the admin who created it doesn't have. Organization owners and admins see every API key and agent in the organization, with the person it acts for, its workspace and access, and can revoke any of them: in Settings, under your organization, API access, then Revoke and Revoke access. See Who can do what.
Connected agents
Each connected agent acts as the person who connected it and never does more than that person's role allows. The list shows the Agent, who it Acts for (admins only), its Access, when it was Connected and when it was Last used. An agent still signing in shows Finishing sign-in. Disconnect, then Disconnect agent, ends its access on its next request. To use it again, sign in from the agent again.
Everyone also sees their own agents across all workspaces in Settings, under Connected agents. See Agents and Register with auth.md.
Agent credentials
Agent credentials are for your own agents and services that shouldn't hold a long-lived key. Select Create credentials, name them and choose:
- Type: Agent acting for you acts as you and never does more than your role allows. Service acts as its own service, limited to the access you choose.
- Access: the same levels as API keys, up to your own role. A Service never does more than the admin who created it can do right now.
You get a Client ID and a Client secret under Credentials created. The secret is shown once. Your service trades them for a short-lived access token, and asks for a new one when it runs out. The list shows each one's Type (Acts for you or Service), Access and when it was Connected. Revoke, then Revoke credentials, stops them on their next request. See Authentication for the token exchange.
Webhooks
A webhook sends a signed HTTPS request to your server when something changes in the workspace.
- Select Add webhook and enter the Endpoint URL. It must be HTTPS on a public address.
- Pick Events. All events covers every event, including ones added later. Or pick single events, grouped by what they're about: launches, ads, ad sets, workflow, integrations, leads, comments and jobs, plus Meta status changes, comments on ad posts, finished uploads, metric thresholds and budget spent. Job events tell you when long-running work such as publishing, imports or media processing finishes, fails or is cancelled.
- Select Add webhook. The Signing secret is shown once. Use it to check that requests come from us.
A workspace can have up to 20 webhooks.
The list shows each webhook's Endpoint with its events, its Last delivery (Delivered 200, Failed 500, Retrying or No deliveries yet) and when it was Added. Deliveries opens Recent deliveries: the 50 latest, with their Event, Status, Attempts, Response and when they were Sent.
A delivery counts as delivered when your server answers with a 2xx status within 10 seconds. Anything else is retried after 30 seconds, 2 minutes, 10 minutes, 30 minutes, 1 hour, 2 hours and 4 hours: up to 8 attempts over almost 8 hours. After the last one it shows as failed.
Delete, then Delete webhook, stops deliveries at once, including ones waiting to retry. Changing a webhook's URL or events, rotating its signing secret and sending a test delivery are done through the API.
How deliveries look, how to verify the signature, and every event are in Webhooks.
Rate limits
Limits count requests per 10 seconds:
| Who | Requests per 10 seconds |
|---|---|
| Each API key or agent | 1,000 |
| Each person in the app | 300 |
| All API keys and agents of one workspace together | 3,000 |
| Each person's sync | 120 |
People don't count against the workspace total, so busy agents never slow down the people in the app.
Sync has its own budget, so a busy person's other requests can't hold up their sync. Over a
limit, the API answers 429 with how many seconds to wait. See
Rate limits.
Next steps
- Public API: credentials, idempotency keys, conflicts, batches, launch specs, jobs, webhooks and every route.
- MCP server: connect an agent and the tools it can call.
- API errors: every error code and what to do about it.