{"openapi":"3.1.0","info":{"title":"MCP Ads Developer API","description":"Connect your customers' ad, analytics and social accounts and run 3,000+ marketing tools on them: Meta, Google Ads, GA4, Search Console, Tag Manager, Merchant Center, TikTok, LinkedIn, X, Microsoft, Snapchat and WordPress. Create a profile per customer, send them a connect link, then call tools with X-Profile-Id. The same key and header work over MCP at /mcp-slim.","version":"1.0.0"},"servers":[{"url":"https://mcp-ads.com"}],"paths":{"/v1/profiles":{"post":{"tags":["developer"],"summary":"Create a profile","description":"One profile per end customer of your app. `external_id` is your own id for them (unique per account), so you never need to store ours.","operationId":"create_profile_route_v1_profiles_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileCreate"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Profile Route V1 Profiles Post"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict: external_id already used, or the profile has not connected what the tool needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"tags":["developer"],"summary":"List profiles","description":"Newest first. Filter by your own `external_id`.","operationId":"list_profiles_route_v1_profiles_get","parameters":[{"name":"external_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"External Id"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Profiles Route V1 Profiles Get"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/profiles/{profile_id}":{"get":{"tags":["developer"],"summary":"Get a profile","operationId":"get_profile_route_v1_profiles__profile_id__get","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Profile Route V1 Profiles  Profile Id  Get"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["developer"],"summary":"Update a profile","operationId":"update_profile_route_v1_profiles__profile_id__patch","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProfileUpdate"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Update Profile Route V1 Profiles  Profile Id  Patch"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict: external_id already used, or the profile has not connected what the tool needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["developer"],"summary":"Delete a profile","description":"Disconnects every account the profile connected and deletes its tokens. Cannot be undone.","operationId":"delete_profile_route_v1_profiles__profile_id__delete","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Delete Profile Route V1 Profiles  Profile Id  Delete"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/profiles/{profile_id}/accounts":{"get":{"tags":["developer"],"summary":"List a profile's connected accounts","description":"Each connection with its platform, health and the ad accounts / properties discovered behind it. Tokens are never returned.","operationId":"profile_accounts_route_v1_profiles__profile_id__accounts_get","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Profile Accounts Route V1 Profiles  Profile Id  Accounts Get"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/profiles/{profile_id}/accounts/{connection_id}":{"delete":{"tags":["developer"],"summary":"Disconnect one account","operationId":"disconnect_account_route_v1_profiles__profile_id__accounts__connection_id__delete","parameters":[{"name":"profile_id","in":"path","required":true,"schema":{"type":"string","title":"Profile Id"}},{"name":"connection_id","in":"path","required":true,"schema":{"type":"string","title":"Connection Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Disconnect Account Route V1 Profiles  Profile Id  Accounts  Connection Id  Delete"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connect/platforms":{"get":{"tags":["developer"],"summary":"Platforms a connect link can connect","operationId":"connect_platforms_route_v1_connect_platforms_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Connect Platforms Route V1 Connect Platforms Get"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connect/{platform}":{"post":{"tags":["developer"],"summary":"Create a connect link","description":"Send your customer to `connect_url`. They sign in with the platform itself, and are sent back to `redirect_url` (which must be on a redirect origin registered in the console) with `profile_id`, `platform`, `status` (`connected` or `error`) and, on failure, `error`. Links are single use and expire after 30 minutes.","operationId":"create_connect_link_route_v1_connect__platform__post","parameters":[{"name":"platform","in":"path","required":true,"schema":{"type":"string","title":"Platform"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectBody"}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Connect Link Route V1 Connect  Platform  Post"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tools":{"get":{"tags":["developer"],"summary":"Browse the tool catalogue","description":"Without `category`: the categories (meta_ads_action, google_ads_action, ...) with how many actions each has. With it: every action in that category with its parameters (JSON Schema), paged; narrow with `search` (matches name and description).","operationId":"list_tools_route_v1_tools_get","parameters":[{"name":"category","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"e.g. meta_ads_action; omit for the category list","title":"Category"},"description":"e.g. meta_ads_action; omit for the category list"},{"name":"search","in":"query","required":false,"schema":{"type":"string","default":"","title":"Search"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":500,"minimum":1,"default":100,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Tools Route V1 Tools Get"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tools/{category}/{action}":{"post":{"tags":["developer"],"summary":"Run a tool","description":"Runs one action for the profile in `X-Profile-Id` (or on your own connections when it is left off). The body is the action's arguments as a JSON object -- see GET /v1/tools?category=... for each action's parameters. Write actions need a read-write key. `ok` is false when the platform refused the call; the platform's message is in `result`.","operationId":"run_tool_route_v1_tools__category___action__post","parameters":[{"name":"category","in":"path","required":true,"schema":{"type":"string","title":"Category"}},{"name":"action","in":"path","required":true,"schema":{"type":"string","title":"Action"}},{"name":"X-Profile-Id","in":"header","required":false,"schema":{"type":"string"},"description":"The profile to act for."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Run Tool Route V1 Tools  Category   Action  Post"}}}},"422":{"description":"Missing or invalid arguments; the message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"400":{"description":"The body is not a JSON object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or revoked API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"The developer account has no active or trialing subscription.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"A read-only key tried to write, or the account is not a developer account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown profile, connection, platform, category or action.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict: external_id already used, or the profile has not connected what the tool needs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"The platform failed in a way we could not explain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"504":{"description":"The action ran out of time.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true},"example":{"account_id":"act_1234567890","date_preset":"last_7d"}}}}}}},"components":{"schemas":{"ConnectBody":{"properties":{"profile_id":{"type":"string","minLength":1,"title":"Profile Id"},"redirect_url":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Redirect Url"}},"type":"object","required":["profile_id"],"title":"ConnectBody"},"ProfileCreate":{"properties":{"name":{"type":"string","maxLength":160,"minLength":1,"title":"Name"},"external_id":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","required":["name"],"title":"ProfileCreate"},"ProfileUpdate":{"properties":{"name":{"anyOf":[{"type":"string","maxLength":160,"minLength":1},{"type":"null"}],"title":"Name"},"external_id":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}],"title":"External Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"}},"type":"object","title":"ProfileUpdate"},"Error":{"type":"object","properties":{"detail":{"type":"string","description":"One sentence, written for the developer."}},"required":["detail"]}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"An mcp_live_ key from the developer console."}}},"security":[{"bearerAuth":[]}]}