{"openapi":"3.1.0","info":{"title":"GetScaled API","version":"1.0.0","summary":"AI-powered multi-channel marketing & sales engagement platform.","description":"The GetScaled REST API lets AI agents and developers drive email, SMS, and voice campaigns, manage contacts and segments, run automated journeys and sequences, and query analytics. Authenticate with a scoped API key (`gsk_` Bearer token) or an OAuth 2.1 access token. The same credentials work with the MCP server at https://mcp.getscaled.com. See https://getscaled.com/auth.md for the agent auth guide.","termsOfService":"https://getscaled.com/terms","contact":{"name":"GetScaled Developer Support","email":"developers@getscaled.com","url":"https://getscaled.com/developers"},"license":{"name":"Proprietary","url":"https://getscaled.com/terms"}},"servers":[{"url":"https://api.getscaled.com","description":"Production"}],"externalDocs":{"description":"Developer portal","url":"https://getscaled.com/developers"},"security":[{"ApiKeyAuth":[]},{"OAuth2":["campaigns:read"]}],"tags":[{"name":"System","description":"Health and metadata."},{"name":"Clients","description":"Tenant/workspace management."},{"name":"Campaigns","description":"Email/SMS/voice campaign CRUD and lifecycle."},{"name":"Contacts","description":"Contact records, search, and bulk operations."},{"name":"Lists & Segments","description":"Static lists and dynamic segments."},{"name":"Journeys","description":"Multi-step automation flows."},{"name":"Sequences","description":"Linear cold-outreach sequences."},{"name":"Templates","description":"Reusable message templates."},{"name":"Senders & Domains","description":"Sending identities and authenticated domains."},{"name":"Analytics","description":"Engagement, funnel, and trend analytics."},{"name":"Deliverability","description":"Reputation, inbox placement, suppression."},{"name":"Webhooks","description":"Event subscriptions."}],"paths":{"/api/v1/health":{"get":{"operationId":"getHealth","tags":["System"],"summary":"Health check","description":"Public liveness probe. No authentication required.","security":[],"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}},"/api/v1/clients":{"get":{"operationId":"listClients","tags":["Clients"],"summary":"List clients/workspaces","description":"List tenants visible to the authenticated key (platform-wide keys see all).","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of clients","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Client"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createClient","tags":["Clients"],"summary":"Create a client","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientInput"}}}},"responses":{"200":{"description":"The created client","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Client"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/campaigns":{"get":{"operationId":"listCampaigns","tags":["Campaigns"],"summary":"List campaigns","description":"List campaigns scoped to the key. Filter by status; paginate with cursor.","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","scheduled","sending","sent","paused","failed","cancelled"]}},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Substring match on campaign name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of campaigns","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createCampaign","tags":["Campaigns"],"summary":"Create a campaign","description":"Create a draft campaign. Requires the `campaigns:write` scope.","security":[{"ApiKeyAuth":[]},{"OAuth2":["campaigns:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInput"}}}},"responses":{"200":{"description":"The created campaign","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Campaign"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/campaigns/{id}":{"get":{"operationId":"getCampaign","tags":["Campaigns"],"summary":"Get a campaign","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The campaign","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Campaign"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateCampaign","tags":["Campaigns"],"summary":"Update a campaign","security":[{"ApiKeyAuth":[]},{"OAuth2":["campaigns:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInput"}}}},"responses":{"200":{"description":"The updated campaign","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Campaign"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"deleteCampaign","tags":["Campaigns"],"summary":"Delete a draft/paused campaign","security":[{"ApiKeyAuth":[]},{"OAuth2":["campaigns:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/launch":{"post":{"operationId":"launchCampaign","tags":["Campaigns"],"summary":"Launch a campaign","description":"Start sending a draft/scheduled campaign. Requires the `campaigns:launch` scope (separate from `:write` so a drafting agent cannot fire sends).","security":[{"ApiKeyAuth":[]},{"OAuth2":["campaigns:launch"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"boolean","const":true,"description":"Must be true to fire."}},"required":["confirm"]}}}},"responses":{"200":{"description":"Launch accepted","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/pause":{"post":{"operationId":"pauseCampaign","tags":["Campaigns"],"summary":"Pause a sending campaign","security":[{"ApiKeyAuth":[]},{"OAuth2":["campaigns:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Paused","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/campaigns/{id}/stats":{"get":{"operationId":"getCampaignStats","tags":["Campaigns","Analytics"],"summary":"Get campaign engagement stats","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Engagement counters","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CampaignStats"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/contacts":{"get":{"operationId":"listContacts","tags":["Contacts"],"summary":"List contacts","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createContact","tags":["Contacts"],"summary":"Create a contact","security":[{"ApiKeyAuth":[]},{"OAuth2":["contacts:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}},"responses":{"200":{"description":"The created contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/contacts/search":{"post":{"operationId":"searchContacts","tags":["Contacts"],"summary":"Search contacts","description":"Full-text + attribute search across the contact book.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"limit":{"type":"integer","maximum":200}},"required":["query"]}}}},"responses":{"200":{"description":"Matching contacts","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/contacts/{id}":{"get":{"operationId":"getContact","tags":["Contacts"],"summary":"Get a contact","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"updateContact","tags":["Contacts"],"summary":"Update a contact","security":[{"ApiKeyAuth":[]},{"OAuth2":["contacts:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}},"responses":{"200":{"description":"The updated contact","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Contact"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/lists":{"get":{"operationId":"listLists","tags":["Lists & Segments"],"summary":"List contact lists","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of lists","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactList"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createList","tags":["Lists & Segments"],"summary":"Create a contact list","security":[{"ApiKeyAuth":[]},{"OAuth2":["lists:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string"}},"required":["name"]}}}},"responses":{"200":{"description":"The created list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ContactList"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/segments":{"get":{"operationId":"listSegments","tags":["Lists & Segments"],"summary":"List dynamic segments","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of segments","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createSegment","tags":["Lists & Segments"],"summary":"Create a dynamic segment","security":[{"ApiKeyAuth":[]},{"OAuth2":["lists:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentInput"}}}},"responses":{"200":{"description":"The created segment","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Segment"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/journeys":{"get":{"operationId":"listJourneys","tags":["Journeys"],"summary":"List journeys","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of journeys","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Journey"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createJourney","tags":["Journeys"],"summary":"Create a journey","security":[{"ApiKeyAuth":[]},{"OAuth2":["journeys:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JourneyInput"}}}},"responses":{"200":{"description":"The created journey","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Journey"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/journeys/{id}/enroll":{"post":{"operationId":"enrollContacts","tags":["Journeys"],"summary":"Enroll contacts into a journey","security":[{"ApiKeyAuth":[]},{"OAuth2":["journeys:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"segment_id":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Enrollment accepted","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/sequences":{"get":{"operationId":"listSequences","tags":["Sequences"],"summary":"List sequences","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of sequences","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Sequence"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/templates":{"get":{"operationId":"listTemplates","tags":["Templates"],"summary":"List templates","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of templates","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Template"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createTemplate","tags":["Templates"],"summary":"Create a template","security":[{"ApiKeyAuth":[]},{"OAuth2":["templates:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TemplateInput"}}}},"responses":{"200":{"description":"The created template","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Template"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/senders":{"get":{"operationId":"listSenders","tags":["Senders & Domains"],"summary":"List sending identities","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of senders","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Sender"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains":{"get":{"operationId":"listDomains","tags":["Senders & Domains"],"summary":"List authenticated domains","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of domains","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/domains/{id}/verify":{"post":{"operationId":"verifyDomain","tags":["Senders & Domains"],"summary":"Verify a domain (DKIM/SPF/DMARC)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"responses":{"200":{"description":"Verification status","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Domain"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/funnel":{"get":{"operationId":"getAnalyticsFunnel","tags":["Analytics"],"summary":"Engagement funnel","description":"Sent → delivered → opened → clicked → replied funnel for a window.","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"from","in":"query","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Funnel metrics","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/analytics/trends":{"get":{"operationId":"getAnalyticsTrends","tags":["Analytics"],"summary":"Engagement trends over time","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"metric","in":"query","schema":{"type":"string","enum":["sent","delivered","opened","clicked","replied","bounced"]}}],"responses":{"200":{"description":"Time-series metrics","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/deliverability/score":{"get":{"operationId":"getDeliverabilityScore","tags":["Deliverability"],"summary":"Deliverability score","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."}],"responses":{"200":{"description":"Deliverability score and factors","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/suppressions":{"get":{"operationId":"listSuppressions","tags":["Deliverability"],"summary":"List suppressed recipients","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"description":"Maximum items to return (1–200, default 50)."},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"},"description":"Opaque pagination cursor from the previous response."}],"responses":{"200":{"description":"A page of suppressions","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"addSuppression","tags":["Deliverability"],"summary":"Suppress a recipient","security":[{"ApiKeyAuth":[]},{"OAuth2":["compliance:read"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email"},"reason":{"type":"string"}},"required":["email"]}}}},"responses":{"200":{"description":"Suppressed","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}},"/api/v1/webhooks":{"get":{"operationId":"listWebhooks","tags":["Webhooks"],"summary":"List webhook subscriptions","parameters":[{"name":"client_id","in":"query","required":false,"schema":{"type":"string","format":"uuid"},"description":"Tenant UUID. Required for platform-wide keys; ignored for tenant-scoped keys."}],"responses":{"200":{"description":"Webhook subscriptions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"createWebhook","tags":["Webhooks"],"summary":"Create a webhook subscription","description":"Subscribe a URL to platform events. Payloads are signed; see /developers for verification.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookInput"}}}},"responses":{"200":{"description":"The created webhook","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Webhook"}}}}}},"401":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"API key lacks required scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}]}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"gsk_*","description":"Scoped API key issued in the portal (Admin → API Keys). Send as `Authorization: Bearer gsk_...`. Also accepted as `X-Api-Key`."},"OAuth2":{"type":"oauth2","description":"OAuth 2.1 with PKCE (S256) via the platform authorization server (Amazon Cognito).","flows":{"authorizationCode":{"authorizationUrl":"https://gs-auth.auth.us-east-1.amazoncognito.com/oauth2/authorize","tokenUrl":"https://gs-auth.auth.us-east-1.amazoncognito.com/oauth2/token","refreshUrl":"https://gs-auth.auth.us-east-1.amazoncognito.com/oauth2/token","scopes":{"campaigns:read":"Read campaigns","campaigns:write":"Create/update campaigns","campaigns:launch":"Launch campaigns","contacts:read":"Read contacts","contacts:write":"Create/update contacts","journeys:read":"Read journeys","journeys:write":"Create/update journeys","analytics:read":"Read analytics","lists:write":"Manage lists & segments","templates:write":"Manage templates","compliance:read":"Manage suppressions/consent"}},"clientCredentials":{"tokenUrl":"https://gs-auth.auth.us-east-1.amazoncognito.com/oauth2/token","scopes":{"campaigns:read":"Read campaigns","contacts:read":"Read contacts","analytics:read":"Read analytics"}}}}},"parameters":{"IdempotencyKey":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255},"description":"Optional unique key that makes a mutating request idempotent — a retried request with the same key returns the original result instead of duplicating the operation. Echoed back in the response Idempotency-Key header."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"VALIDATION_FAILED"},"message":{"type":"string"},"request_id":{"type":"string","format":"uuid"}},"required":["code","message"]}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}},"Client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ClientInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"industry":{"type":"string"}}},"Campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","scheduled","sending","sent","paused","failed","cancelled"]},"subject":{"type":"string","nullable":true},"channel":{"type":"string","enum":["email","sms","voice"]},"scheduled_at":{"type":"string","format":"date-time","nullable":true},"total_recipients":{"type":"integer","nullable":true},"total_sent":{"type":"integer","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"CampaignInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"subject":{"type":"string"},"channel":{"type":"string","enum":["email","sms","voice"],"default":"email"},"template_id":{"type":"string","format":"uuid"},"list_id":{"type":"string","format":"uuid"},"scheduled_at":{"type":"string","format":"date-time"}}},"CampaignStats":{"type":"object","properties":{"sent":{"type":"integer"},"delivered":{"type":"integer"},"opened":{"type":"integer"},"clicked":{"type":"integer"},"replied":{"type":"integer"},"bounced":{"type":"integer"},"unsubscribed":{"type":"integer"},"open_rate":{"type":"number"},"click_rate":{"type":"number"}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"first_name":{"type":"string","nullable":true},"last_name":{"type":"string","nullable":true},"company":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"status":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"ContactInput":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"first_name":{"type":"string"},"last_name":{"type":"string"},"company":{"type":"string"},"phone":{"type":"string"},"custom_fields":{"type":"object","additionalProperties":true}}},"ContactList":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"member_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"Segment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"rule_groups":{"type":"array","items":{"type":"object"}},"estimated_size":{"type":"integer","nullable":true}}},"SegmentInput":{"type":"object","required":["name","rule_groups"],"properties":{"name":{"type":"string"},"rule_groups":{"type":"array","items":{"type":"object","properties":{"match":{"type":"string","enum":["all","any"]},"rules":{"type":"array","items":{"type":"object"}}}}}}},"Journey":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string","enum":["draft","active","paused","archived"]},"nodes":{"type":"array","items":{"type":"object"}},"created_at":{"type":"string","format":"date-time"}}},"JourneyInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"nodes":{"type":"array","items":{"type":"object"}}}},"Sequence":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"step_count":{"type":"integer"}}},"Template":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"channel":{"type":"string","enum":["email","sms","voice"]},"subject":{"type":"string","nullable":true},"created_at":{"type":"string","format":"date-time"}}},"TemplateInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"channel":{"type":"string","enum":["email","sms","voice"],"default":"email"},"subject":{"type":"string"},"body_html":{"type":"string"},"body_text":{"type":"string"}}},"Sender":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"from_email":{"type":"string","format":"email"},"from_name":{"type":"string"},"verified":{"type":"boolean"}}},"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"domain":{"type":"string"},"dkim_verified":{"type":"boolean"},"spf_verified":{"type":"boolean"},"dmarc_verified":{"type":"boolean"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"}}},"WebhookInput":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["email.delivered","email.opened","email.clicked","email.bounced","contact.unsubscribed","campaign.complete","reply.received"]},"minItems":1}}}}}}