{"openapi":"3.1.0","info":{"title":"Promotedly API","version":"2026-11-04","description":"Public discovery endpoints describe Promotedly. Account endpoints act for one business after its owner approves an OAuth connection. Agents can create and edit drafts; only a person can publish. No endpoint returns customer names or contact details.","contact":{"url":"https://promotedly.com/developers"}},"servers":[{"url":"https://promotedly.com/api/v1"}],"externalDocs":{"url":"https://promotedly.com/developers"},"paths":{"/company":{"get":{"operationId":"getCompany","summary":"Company profile","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/features":{"get":{"operationId":"listFeatures","summary":"Features and capabilities with status","tags":["Discovery"],"security":[],"parameters":[{"name":"q","in":"query","description":"Keyword search.","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["available","paid","in_development","planned","not_supported"]}},{"name":"kind","in":"query","schema":{"type":"string","enum":["campaign_type","platform"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/features/{id}":{"get":{"operationId":"getFeature","summary":"One feature","tags":["Discovery"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/capabilities":{"get":{"operationId":"listCapabilities","summary":"Platform capabilities with status","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaign-types":{"get":{"operationId":"listCampaignTypes","summary":"Campaign types","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaign-types/{id}":{"get":{"operationId":"getCampaignType","summary":"One campaign type by id or slug","tags":["Discovery"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/pricing":{"get":{"operationId":"getPricing","summary":"Plans and prices from the billing catalogue","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/recommendations":{"get":{"operationId":"getRecommendations","summary":"Campaign types suited to an industry","tags":["Discovery"],"security":[],"parameters":[{"name":"industry","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaign-examples":{"get":{"operationId":"listCampaignExamples","summary":"Worked campaign examples","tags":["Discovery"],"security":[],"parameters":[{"name":"type","in":"query","schema":{"type":"string"}},{"name":"industry","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/documentation":{"get":{"operationId":"getDocumentation","summary":"Documentation links, scopes and agent rules","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/agent/registrations":{"post":{"operationId":"startRegistration","summary":"Start a sign-up for a business","description":"Emails the owner a link. Nothing is created until they confirm and choose a password. The response is the same whether or not the address already has an account.","tags":["Discovery"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["businessName","email"],"properties":{"businessName":{"type":"string","maxLength":120},"email":{"type":"string","format":"email"},"contactName":{"type":"string"},"websiteUrl":{"type":"string","format":"uri"},"industry":{"type":"string"},"agentPlatform":{"type":"string"},"referral":{"type":"string"},"clientId":{"type":"string","description":"Your OAuth client id, for attribution."}}}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/agent/registrations/{id}":{"get":{"operationId":"getRegistration","summary":"Sign-up status","tags":["Discovery"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Registration-Token","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/me":{"get":{"operationId":"getAccount","summary":"Connected account","tags":["Account"],"security":[{"oauth":["account:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/brand":{"get":{"operationId":"getBrand","summary":"Brand profile","tags":["Account"],"security":[{"oauth":["brand:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns":{"get":{"operationId":"listCampaigns","summary":"List campaigns","tags":["Account"],"security":[{"oauth":["campaigns:read"]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["draft","scheduled","active","paused","ended"]}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"pageSize","in":"query","schema":{"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"post":{"operationId":"createDraft","summary":"Create a draft campaign","tags":["Account"],"security":[{"oauth":["campaigns:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["instant_dollar_off","percent_off","refer_a_friend","give_get","scratch_win","spin_to_win","flash_sale","appointment","loyalty_visit","share_to_unlock","giveaway","review_video","countdown_coupon"]},"name":{"type":"string","maxLength":120},"deployment":{"type":"string","enum":["qr","popup","link","qr_and_popup"]},"config":{"type":"object","description":"Partial settings merged over the type's defaults and validated."}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/ai":{"post":{"operationId":"createAiDraft","summary":"Create a draft filled from the brand profile","tags":["Account"],"security":[{"oauth":["campaigns:write"]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["type"],"properties":{"type":{"type":"string","enum":["instant_dollar_off","percent_off","refer_a_friend","give_get","scratch_win","spin_to_win","flash_sale","appointment","loyalty_visit","share_to_unlock","giveaway","review_video","countdown_coupon"]}}}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/ideas":{"get":{"operationId":"campaignIdeas","summary":"Campaign ideas for this brand","tags":["Account"],"security":[{"oauth":["campaigns:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}":{"get":{"operationId":"getCampaign","summary":"One campaign","tags":["Account"],"security":[{"oauth":["campaigns:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"patch":{"operationId":"updateDraft","summary":"Edit a draft","description":"Only drafts can be edited through the API.","tags":["Account"],"security":[{"oauth":["campaigns:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"name":{"type":"string"},"deployment":{"type":"string","enum":["qr","popup","link","qr_and_popup"]},"startsAt":{"type":["string","null"],"format":"date-time"},"endsAt":{"type":["string","null"],"format":"date-time"},"maxParticipants":{"type":["integer","null"]},"perCustomerLimit":{"type":"integer"},"newCustomersOnly":{"type":"boolean"},"config":{"type":"object"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/publish-request":{"post":{"operationId":"requestPublish","summary":"Ask a person to publish","description":"Never publishes. Returns the portal link where a person reviews and publishes.","tags":["Account"],"security":[{"oauth":["campaigns:write"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/campaigns/{id}/analytics":{"get":{"operationId":"campaignAnalytics","summary":"Campaign totals","tags":["Account"],"security":[{"oauth":["analytics:read"]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"days","in":"query","description":"Look-back window in days (1-365, default 30).","schema":{"type":"integer","minimum":1,"maximum":365}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/analytics":{"get":{"operationId":"brandAnalytics","summary":"Brand totals","tags":["Account"],"security":[{"oauth":["analytics:read"]}],"parameters":[{"name":"days","in":"query","description":"Look-back window in days (1-365, default 30).","schema":{"type":"integer","minimum":1,"maximum":365}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"oauth":{"type":"oauth2","description":"OAuth 2.1 authorization code with PKCE (S256). Clients register dynamically at /oauth/register.","flows":{"authorizationCode":{"authorizationUrl":"https://promotedly.com/oauth/authorize","tokenUrl":"https://promotedly.com/oauth/token","refreshUrl":"https://promotedly.com/oauth/token","scopes":{"account:read":"See the business name, plan and customer allowance.","brand:read":"See the brand profile: name, description, industry, colours and locations.","campaigns:read":"See campaigns and their settings.","campaigns:write":"Create and edit draft campaigns. Drafts are never published by an agent.","analytics:read":"See campaign totals: views, claims, rewards and redemptions. No customer names or contact details."}}}}},"schemas":{"Envelope":{"type":"object","required":["data"],"properties":{"data":{},"meta":{}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"fields":{"type":"object"}}}}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}