{"openapi":"3.0.3","info":{"title":"Benjiads API","version":"1.0.0","description":"Sites, local advertising and leads. All access is scoped to one workspace. Limits: 120 operations and 20 writes per rolling minute per workspace, shared by REST and MCP. Existing subscription, contact masking and advertising funding rules apply. Integration requests are not separately billed."},"servers":[{"url":"https://api.benjiads.com/v1"}],"paths":{"/verticals":{"get":{"operationId":"list_verticals","summary":"List supported verticals and rules","description":"Published trade catalog with configured state-specific fields, ad-copy restrictions and platform guidance. A published vertical can still be on hold. Configuration flags do not enable a new advertising channel.","tags":["verticals"],"security":[{"ApiKey":[]},{"OAuth":["site:read"]}],"x-required-scope":"site:read","parameters":[],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"verticals":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"singular":{"type":"string"},"locationKind":{"type":"string"},"compliance":{"type":"object","properties":{"launch":{"type":"string","enum":["go","hold"]},"platform":{"type":"object","properties":{"googleSearch":{"type":"boolean"},"metaSpecialAdCategory":{"type":"string","enum":["housing","employment","credit"]},"ageMin":{"type":"number"},"healthPixelRisk":{"type":"boolean"}},"required":["googleSearch"],"additionalProperties":false},"adRules":{"type":"array","items":{"type":"string"}},"avoid":{"type":"array","items":{"type":"string"}},"tenantFields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"askAt":{"type":"string","enum":["onboarding","before-ads"]},"requiredIn":{"type":"array","items":{"type":"string"}},"why":{"type":"string"}},"required":["key","label","askAt","why"],"additionalProperties":false}},"disclosures":{"type":"array","items":{"type":"object","properties":{"states":{"type":"array","items":{"type":"string"}},"text":{"type":"string"}},"required":["states","text"],"additionalProperties":false}},"notes":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}}},"required":["launch","platform","adRules","avoid","tenantFields","disclosures","notes","sources"],"additionalProperties":false,"nullable":true}},"required":["slug","label","singular","locationKind","compliance"],"additionalProperties":false}},"globalAvoid":{"type":"array","items":{"type":"string"}}},"required":["verticals","globalAvoid"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/verticals/{slug}":{"get":{"operationId":"get_vertical","summary":"Read a vertical's requirements","description":"Read the full configured rule sheet for a trade such as plumber, including requiredIn states and disclosures. Check get_workspace_requirements for the current workspace's license blockers.","tags":["verticals"],"security":[{"ApiKey":[]},{"OAuth":["site:read"]}],"x-required-scope":"site:read","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z0-9-]{2,60}$"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"vertical":{"type":"object","properties":{"slug":{"type":"string"},"label":{"type":"string"},"singular":{"type":"string"},"locationKind":{"type":"string"},"compliance":{"type":"object","properties":{"launch":{"type":"string","enum":["go","hold"]},"platform":{"type":"object","properties":{"googleSearch":{"type":"boolean"},"metaSpecialAdCategory":{"type":"string","enum":["housing","employment","credit"]},"ageMin":{"type":"number"},"healthPixelRisk":{"type":"boolean"}},"required":["googleSearch"],"additionalProperties":false},"adRules":{"type":"array","items":{"type":"string"}},"avoid":{"type":"array","items":{"type":"string"}},"tenantFields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"askAt":{"type":"string","enum":["onboarding","before-ads"]},"requiredIn":{"type":"array","items":{"type":"string"}},"why":{"type":"string"}},"required":["key","label","askAt","why"],"additionalProperties":false}},"disclosures":{"type":"array","items":{"type":"object","properties":{"states":{"type":"array","items":{"type":"string"}},"text":{"type":"string"}},"required":["states","text"],"additionalProperties":false}},"notes":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}}},"required":["launch","platform","adRules","avoid","tenantFields","disclosures","notes","sources"],"additionalProperties":false,"nullable":true}},"required":["slug","label","singular","locationKind","compliance"],"additionalProperties":false}},"required":["vertical"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/workspace/requirements":{"get":{"operationId":"get_workspace_requirements","summary":"Check workspace license requirements","description":"Resolve the workspace's selected states against its trade rules and the existing license acceptance checks. missing lists actual license blockers. Other configured fields guide onboarding and ad copy; their presence does not imply an automated registry check. Billing, funding and job completion are checked separately on launch.","tags":["workspace"],"security":[{"ApiKey":[]},{"OAuth":["site:read"]}],"x-required-scope":"site:read","parameters":[],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"workspaceId":{"type":"string"},"vertical":{"type":"string"},"states":{"type":"array","items":{"type":"string"}},"fields":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"askAt":{"type":"string","enum":["onboarding","before-ads"]},"requiredIn":{"type":"array","items":{"type":"string"}},"why":{"type":"string"}},"required":["key","label","askAt","why"],"additionalProperties":false}},"missing":{"type":"array","items":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"states":{"type":"array","items":{"type":"string"}}},"required":["key","label","states"],"additionalProperties":false}},"licenseLine":{"type":"string","nullable":true},"disclosures":{"type":"array","items":{"type":"string"}},"manageUrl":{"type":"string","format":"uri"}},"required":["workspaceId","vertical","states","fields","missing","licenseLine","disclosures","manageUrl"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/workspace":{"get":{"operationId":"get_workspace","summary":"Read your workspace","description":"Returns only the workspace authorized by this connection.","tags":["workspace"],"security":[{"ApiKey":[]},{"OAuth":["site:read"]}],"x-required-scope":"site:read","parameters":[],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"workspace":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"displayName":{"type":"string"},"siteUrl":{"type":"string","format":"uri"}},"required":["id","slug","displayName","siteUrl"],"additionalProperties":false},"scopes":{"type":"array","items":{"type":"string"}}},"required":["workspace","scopes"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/site":{"get":{"operationId":"get_site","summary":"Read the site and its draft","description":"Read published content and the current draft. Available without a paid subscription.","tags":["site"],"security":[{"ApiKey":[]},{"OAuth":["site:read"]}],"x-required-scope":"site:read","parameters":[],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"},"tagline":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"photoUrl":{"type":"string","nullable":true},"phonePublic":{"type":"string","nullable":true},"theme":{"type":"string"},"accentColor":{"type":"string","nullable":true},"brandWordmarkUrl":{"type":"string","nullable":true},"brandWordmarkWhiteUrl":{"type":"string","nullable":true},"locations":{},"links":{},"socials":{},"siteDoc":{},"siteDraft":{}},"required":["id","slug","displayName","status","tagline","bio","photoUrl","phonePublic","theme","accentColor"],"additionalProperties":false}},"required":["site"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}},"patch":{"operationId":"update_site","summary":"Update site settings","description":"Update business details, appearance, service areas or publication status. Lead capture remains available without a subscription.","tags":["site"],"security":[{"ApiKey":[]},{"OAuth":["site:write"]}],"x-required-scope":"site:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–80 letters, digits, underscores or hyphens. Reuse the same key and arguments for retries. Completed mutations replay for at least 90 days; a pending operation returns 409 and must be reconciled before using a new key.","schema":{"type":"string","minLength":8,"maxLength":80,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"displayName":{"type":"string","minLength":1,"maxLength":80},"tagline":{"type":"string","maxLength":160,"nullable":true},"bio":{"type":"string","maxLength":2000,"nullable":true},"photoUrl":{"type":"string","format":"uri","maxLength":1000,"nullable":true},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":48},"label":{"type":"string","maxLength":120},"city":{"type":"string","maxLength":80},"state":{"type":"string","maxLength":2},"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180},"radiusMi":{"type":"number","minimum":1,"maximum":100}},"required":["lat","lon"],"additionalProperties":false},"maxItems":7},"phonePublic":{"type":"string","maxLength":40,"nullable":true},"theme":{"type":"string","enum":["electric","midnight","sky"]},"accentColor":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$","nullable":true},"brandWordmarkUrl":{"type":"string","format":"uri","maxLength":1000,"nullable":true},"brandWordmarkWhiteUrl":{"type":"string","format":"uri","maxLength":1000,"nullable":true},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":60},"url":{"type":"string","format":"uri","maxLength":500}},"required":["label","url"],"additionalProperties":false},"maxItems":20},"socials":{"type":"object","properties":{"instagram":{"type":"string","maxLength":300},"facebook":{"type":"string","maxLength":300},"tiktok":{"type":"string","maxLength":300},"youtube":{"type":"string","maxLength":300},"website":{"type":"string","maxLength":300},"email":{"type":"string","maxLength":120}},"additionalProperties":false},"status":{"type":"string","enum":["DRAFT","LIVE"]},"trust":{"type":"object","properties":{"startedYear":{"type":"integer"},"credentials":{"type":"array","items":{"type":"string"}},"statLines":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"],"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"},"tagline":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"photoUrl":{"type":"string","nullable":true},"phonePublic":{"type":"string","nullable":true},"theme":{"type":"string"},"accentColor":{"type":"string","nullable":true},"brandWordmarkUrl":{"type":"string","nullable":true},"brandWordmarkWhiteUrl":{"type":"string","nullable":true},"locations":{},"links":{},"socials":{},"siteDoc":{},"siteDraft":{}},"required":["id","slug","displayName","status","tagline","bio","photoUrl","phonePublic","theme","accentColor"],"additionalProperties":false}},"required":["site"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/site/draft":{"put":{"operationId":"save_site_draft","summary":"Save a site draft","description":"Save a Benjiads site document using the same structural validation as the site builder. Get the existing document with get_site before editing.","tags":["site"],"security":[{"ApiKey":[]},{"OAuth":["site:write"]}],"x-required-scope":"site:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–80 letters, digits, underscores or hyphens. Reuse the same key and arguments for retries. Completed mutations replay for at least 90 days; a pending operation returns 409 and must be reconciled before using a new key.","schema":{"type":"string","minLength":8,"maxLength":80,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"doc":{"type":"object","additionalProperties":{}}},"required":["doc"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"},"tagline":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"photoUrl":{"type":"string","nullable":true},"phonePublic":{"type":"string","nullable":true},"theme":{"type":"string"},"accentColor":{"type":"string","nullable":true},"brandWordmarkUrl":{"type":"string","nullable":true},"brandWordmarkWhiteUrl":{"type":"string","nullable":true},"locations":{},"links":{},"socials":{},"siteDoc":{},"siteDraft":{}},"required":["id","slug","displayName","status","tagline","bio","photoUrl","phonePublic","theme","accentColor"],"additionalProperties":false}},"required":["site"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/site/publish":{"post":{"operationId":"publish_site","summary":"Publish the saved site draft","description":"Publishes the saved draft to the live site. Review the draft first. Available without a paid subscription.","tags":["site"],"security":[{"ApiKey":[]},{"OAuth":["site:write"]}],"x-required-scope":"site:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–80 letters, digits, underscores or hyphens. Reuse the same key and arguments for retries. Completed mutations replay for at least 90 days; a pending operation returns 409 and must be reconciled before using a new key.","schema":{"type":"string","minLength":8,"maxLength":80,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"site":{"type":"object","properties":{"id":{"type":"string"},"slug":{"type":"string"},"displayName":{"type":"string"},"status":{"type":"string"},"tagline":{"type":"string","nullable":true},"bio":{"type":"string","nullable":true},"photoUrl":{"type":"string","nullable":true},"phonePublic":{"type":"string","nullable":true},"theme":{"type":"string"},"accentColor":{"type":"string","nullable":true},"brandWordmarkUrl":{"type":"string","nullable":true},"brandWordmarkWhiteUrl":{"type":"string","nullable":true},"locations":{},"links":{},"socials":{},"siteDoc":{},"siteDraft":{}},"required":["id","slug","displayName","status","tagline","bio","photoUrl","phonePublic","theme","accentColor"],"additionalProperties":false}},"required":["site"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/campaigns":{"get":{"operationId":"list_campaigns","summary":"Read campaigns and ad balance","description":"Money is in USD wallet cents. balanceCents is cumulative funding; remainingCents is available funding. If the provider is unavailable, spending may use the stored lifetime mirror.","tags":["campaigns"],"security":[{"ApiKey":[]},{"OAuth":["ads:read"]}],"x-required-scope":"ads:read","parameters":[{"name":"preset","in":"query","required":false,"schema":{"anyOf":[{"not":{}},{"type":"string","enum":["today","yesterday","last_7d","maximum"]}]}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"balanceCents":{"type":"number"},"remainingCents":{"type":"number"},"spentCents":{"type":"number"},"spentLifetimeCents":{"type":"number"},"exhausted":{"type":"boolean"},"masterStatus":{"type":"string","nullable":true},"campaigns":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"dailyBudgetCents":{"type":"number"},"budgetCents":{"type":"number"},"spendCents":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","name","status"],"additionalProperties":false}}},"required":["balanceCents","remainingCents","spentCents","spentLifetimeCents","exhausted","masterStatus","campaigns"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}},"post":{"operationId":"create_campaign","summary":"Prepare a campaign","description":"Queues preparation with launch disabled. Requires the existing subscription, wallet, creative ownership and licence checks. Returns a job to poll. dailyBudgetCents is the TOTAL across locations.","tags":["campaigns"],"security":[{"ApiKey":[]},{"OAuth":["ads:write"]}],"x-required-scope":"ads:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–80 letters, digits, underscores or hyphens. Reuse the same key and arguments for retries. Completed mutations replay for at least 90 days; a pending operation returns 409 and must be reconciled before using a new key.","schema":{"type":"string","minLength":8,"maxLength":80,"pattern":"^[A-Za-z0-9_-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":80},"messages":{"type":"array","items":{"type":"string","minLength":1,"maxLength":400},"minItems":1,"maxItems":5},"headlines":{"type":"array","items":{"type":"string","minLength":1,"maxLength":60},"minItems":1,"maxItems":5},"descriptions":{"type":"array","items":{"type":"string","minLength":1,"maxLength":100},"minItems":1,"maxItems":2},"dailyBudgetCents":{"type":"integer"},"creativeIds":{"type":"array","items":{"type":"string","format":"uuid"},"maxItems":18},"creativeId":{"type":"string","format":"uuid"},"radiusMi":{"type":"integer","minimum":10,"maximum":50},"extraLocations":{"type":"array","items":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90},"lon":{"type":"number","minimum":-180,"maximum":180}},"required":["lat","lon"],"additionalProperties":false},"maxItems":10}},"required":["dailyBudgetCents"],"additionalProperties":false}}}},"responses":{"202":{"description":"Queued; poll the returned job ID.","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"hold":{"type":"string","nullable":true},"attempts":{"type":"number"},"adsWanted":{"type":"number"},"adsCreated":{"type":"number"},"campaignId":{"type":"string","nullable":true},"liveAt":{"type":"string","nullable":true},"nextRunAt":{"type":"string","nullable":true},"lastError":{"type":"string","nullable":true}},"required":["id","status","hold","attempts","adsWanted","adsCreated","campaignId","liveAt","nextRunAt","lastError"],"additionalProperties":false}},"required":["job"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/jobs/{id}":{"get":{"operationId":"get_job","summary":"Read campaign preparation status","description":"Poll an existing deployment job. ready means prepared; live means delivery was activated. A failed or cancelled job may have created provider objects.","tags":["jobs"],"security":[{"ApiKey":[]},{"OAuth":["ads:read"]}],"x-required-scope":"ads:read","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"job":{"type":"object","properties":{"id":{"type":"string"},"status":{"type":"string"},"hold":{"type":"string","nullable":true},"attempts":{"type":"number"},"adsWanted":{"type":"number"},"adsCreated":{"type":"number"},"campaignId":{"type":"string","nullable":true},"liveAt":{"type":"string","nullable":true},"nextRunAt":{"type":"string","nullable":true},"lastError":{"type":"string","nullable":true}},"required":["id","status","hold","attempts","adsWanted","adsCreated","campaignId","liveAt","nextRunAt","lastError"],"additionalProperties":false}},"required":["job"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/campaigns/{id}/launch":{"post":{"operationId":"launch_campaign","summary":"Launch a prepared campaign","description":"Starts ad delivery using the campaign's saved budget. Requires an active entitlement, available funding and completed preparation with required licences. Authorize the budget before calling.","tags":["campaigns"],"security":[{"ApiKey":[]},{"OAuth":["ads:write"]}],"x-required-scope":"ads:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"8–80 letters, digits, underscores or hyphens. Reuse the same key and arguments for retries. Completed mutations replay for at least 90 days; a pending operation returns 409 and must be reconciled before using a new key.","schema":{"type":"string","minLength":8,"maxLength":80,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"dailyBudgetCents":{"type":"number"},"budgetCents":{"type":"number"},"spendCents":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","name","status"],"additionalProperties":false}},"required":["campaign"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/campaigns/{id}/pause":{"post":{"operationId":"pause_campaign","summary":"Pause a campaign","description":"Pauses the selected campaign using the existing product access rules.","tags":["campaigns"],"security":[{"ApiKey":[]},{"OAuth":["ads:write"]}],"x-required-scope":"ads:write","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"8–80 letters, digits, underscores or hyphens. Reuse the same key and arguments for retries. Completed mutations replay for at least 90 days; a pending operation returns 409 and must be reconciled before using a new key.","schema":{"type":"string","minLength":8,"maxLength":80,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"campaign":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"status":{"type":"string"},"dailyBudgetCents":{"type":"number"},"budgetCents":{"type":"number"},"spendCents":{"type":"number"},"createdAt":{"type":"string"}},"required":["id","name","status"],"additionalProperties":false}},"required":["campaign"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/metrics":{"get":{"operationId":"get_metrics","summary":"Read business performance","description":"Returns the dashboard's lead and site performance. days=1 uses a 48-hour hourly series and rolling totals; days=7 or 30 uses daily points.","tags":["metrics"],"security":[{"ApiKey":[]},{"OAuth":["metrics:read"]}],"x-required-scope":"metrics:read","parameters":[{"name":"days","in":"query","required":false,"schema":{"anyOf":[{"not":{}},{"type":"string","enum":["1","7","30"]}]}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","additionalProperties":{}}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/leads":{"get":{"operationId":"list_leads","summary":"Read leads","description":"Contact details stay masked when the workspace has no paid entitlement. Follow nextCursor for pagination.","tags":["leads"],"security":[{"ApiKey":[]},{"OAuth":["leads:read"]}],"x-required-scope":"leads:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"not":{}},{"type":"integer","minimum":1,"maximum":200}]}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"not":{}},{"type":"string","format":"uuid"}]}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"leads":{"type":"array","items":{"type":"object","additionalProperties":{}}},"gated":{"type":"boolean"},"nextCursor":{"type":"string","nullable":true}},"required":["leads","gated","nextCursor"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/billing/subscription":{"get":{"operationId":"get_subscription","summary":"Read subscription status","description":"Read the workspace's current entitlement. active includes an eligible trial, as in the dashboard.","tags":["billing"],"security":[{"ApiKey":[]},{"OAuth":["billing:read"]}],"x-required-scope":"billing:read","parameters":[],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","nullable":true},"currentPeriodEnd":{"type":"string","nullable":true},"checkoutUrl":{"type":"string","format":"uri"}},"required":["status","currentPeriodEnd","checkoutUrl"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/billing/checkout":{"post":{"operationId":"start_subscription","summary":"Open subscription checkout","description":"Returns a browser handoff to the existing Benjiads checkout. The owner signs in and authorizes the recurring subscription; this call does not charge a card or grant access. Existing subscribers can manage billing there.","tags":["billing"],"security":[{"ApiKey":[]},{"OAuth":["billing:write"]}],"x-required-scope":"billing:write","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"8–80 letters, digits, underscores or hyphens. Reuse the same key and arguments for retries. Completed mutations replay for at least 90 days; a pending operation returns 409 and must be reconciled before using a new key.","schema":{"type":"string","minLength":8,"maxLength":80,"pattern":"^[A-Za-z0-9_-]+$"}}],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"action":{"type":"string","enum":["complete_in_browser"]}},"required":["url","action"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/billing/invoices":{"get":{"operationId":"list_invoices","summary":"Read subscription invoices","description":"Lists invoices for this workspace's Benjiads subscription only.","tags":["billing"],"security":[{"ApiKey":[]},{"OAuth":["billing:read"]}],"x-required-scope":"billing:read","parameters":[],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"invoices":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["invoices"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}},"/usage":{"get":{"operationId":"get_usage","summary":"Read integration usage","description":"Returns admitted REST and MCP operations for the last 30 days, grouped by operation. These are operational counters, not additional billable units.","tags":["usage"],"security":[{"ApiKey":[]},{"OAuth":["metrics:read"]}],"x-required-scope":"metrics:read","parameters":[],"responses":{"200":{"description":"Success","headers":{"X-Request-Id":{"schema":{"type":"string"},"description":"Operation receipt ID"},"Idempotency-Replayed":{"schema":{"type":"string","enum":["true"]},"description":"Present for a replay"}},"content":{"application/json":{"schema":{"type":"object","properties":{"since":{"type":"string"},"requests":{"type":"number"},"operations":{"type":"array","items":{"type":"object","properties":{"operation":{"type":"string"},"count":{"type":"number"}},"required":["operation","count"],"additionalProperties":false}},"limits":{"type":"object","properties":{"requestsPerMinute":{"type":"number"},"writesPerMinute":{"type":"number"}},"required":["requestsPerMinute","writesPerMinute"],"additionalProperties":false}},"required":["since","requests","operations","limits"],"additionalProperties":false}}}},"400":{"description":"Invalid input or missing idempotency key","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"401":{"description":"Missing, expired or revoked credential","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"402":{"description":"Subscription required","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"403":{"description":"Missing scope or workspace access","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"409":{"description":"State conflict, operation pending or idempotency conflict","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"413":{"description":"Request body exceeds 512 KiB","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"429":{"description":"Rate limited; retry after 60 seconds","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"500":{"description":"Internal failure; inspect state before retrying a mutation","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"502":{"description":"Provider unavailable","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}},"503":{"description":"Service not configured","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}},"additionalProperties":true}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","bearerFormat":"bja_key_…","description":"Create a scoped key in Benjiads → Integrations. Sent only in Authorization."},"OAuth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://api.benjiads.com/oauth/authorize","tokenUrl":"https://api.benjiads.com/oauth/token","scopes":{"site:read":"Read your site and workspace","site:write":"Edit and publish your site","ads:read":"Read campaigns and advertising balance","ads:write":"Create, launch and pause campaigns within your funded budget","leads:read":"Read leads, subject to your subscription","metrics:read":"Read performance and integration usage","billing:read":"Read subscription and invoices","billing:write":"Open checkout to subscribe or manage billing"}}}}}},"x-mcp-url":"https://api.benjiads.com/mcp","x-mcp-auth":"OAuth resource is the exact /mcp URL. REST OAuth tokens target the exact /v1 URL. Personal keys work on both."}