Skip to content
Promotedly

Developers and AI agents

Connect an assistant to Promotedly

Anyone can ask what Promotedly does and what it costs, with no key. With the owner's approval, an assistant can also draft campaigns and read campaign totals for that business. A person always publishes, and no interface returns customer names or contact details.

MCP server

Endpoint https://promotedly.com/mcp, Streamable HTTP, stateless. Add it as a custom connector or remote MCP server in your assistant. Discovery tools work straight away. The first time you use an account tool, the assistant opens a Promotedly page where the business owner signs in and approves the connection.

{
  "mcpServers": {
    "promotedly": {
      "type": "http",
      "url": "https://promotedly.com/mcp"
    }
  }
}

Tools that need no sign-in

get_promotedly_info, search_promotedly_features, get_campaign_types, get_pricing, get_industry_recommendations, get_campaign_examples, get_documentation, start_signup

Tools that act for a connected business

get_account, generate_campaign_ideas, create_promotion, create_coupon_campaign, create_qr_campaign, create_giveaway, create_rewards_campaign, create_loyalty_campaign, list_campaigns, get_campaign, update_campaign_draft, request_campaign_publish, get_campaign_analytics

The create tools save drafts. request_campaign_publish returns the link where a person reviews and publishes; it never makes anything live.

REST API

Base URL https://promotedly.com/api/v1. Responses are JSON in a { data, meta } envelope; errors are { error: { code, message } }. The full description is at /.well-known/openapi.json.

Public

  • GET /api/v1/company

    Company profile, audience and how it works

  • GET /api/v1/features?q=

    Features and capabilities, each with a status

  • GET /api/v1/capabilities

    Platform capabilities and their status

  • GET /api/v1/campaign-types

    The campaign types, with setup and journey

  • GET /api/v1/pricing

    Plans and prices from the billing catalogue

  • GET /api/v1/recommendations?industry=

    Campaign types suited to an industry

  • GET /api/v1/campaign-examples

    Worked examples by type or industry

  • GET /api/v1/documentation

    Links, scopes and agent rules

  • POST /api/v1/agent/registrations

    Start a sign-up; the owner confirms by email

With an access token

Send Authorization: Bearer <token>. Without one, the response is 401 with a WWW-Authenticate header pointing at the protected resource metadata.

  • GET /api/v1/me

    Scope: account:read

    Business name, plan and customer allowance

  • GET /api/v1/brand

    Scope: brand:read

    Brand profile

  • GET /api/v1/campaigns

    Scope: campaigns:read

    Campaigns, newest first

  • POST /api/v1/campaigns

    Scope: campaigns:write

    Create a draft

  • POST /api/v1/campaigns/ai

    Scope: campaigns:write

    Create a draft filled from the brand profile

  • GET /api/v1/campaigns/ideas

    Scope: campaigns:read

    Campaign ideas for this brand

  • PATCH /api/v1/campaigns/{id}

    Scope: campaigns:write

    Edit a draft

  • POST /api/v1/campaigns/{id}/publish-request

    Scope: campaigns:write

    Get the link where a person publishes

  • GET /api/v1/campaigns/{id}/analytics

    Scope: analytics:read

    Campaign totals

  • GET /api/v1/analytics

    Scope: analytics:read

    Brand totals

Authorization

OAuth 2.1 authorization code flow with PKCE (S256 only), dynamic client registration and resource indicators. Access tokens last one hour; refresh tokens rotate on every use and a reused one ends the connection. Owners and admins can disconnect any app from Settings, Connected apps.

  • Authorization server metadata: /.well-known/oauth-authorization-server
  • Protected resource metadata: /.well-known/oauth-protected-resource/mcp and /.well-known/oauth-protected-resource/api/v1
  • Register: POST /oauth/register, token: POST /oauth/token, revoke: POST /oauth/revoke

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.

Signing up a business

An assistant can start a sign-up with POST /api/v1/agent/registrations or the start_signup tool. Promotedly emails the owner, and the account exists only after they follow the link and choose a password. The response is the same whether or not the address already has an account, and requests are rate limited per network, per app and per address.

Rules for agents

  • Agents can read public product information without signing in.
  • Agents can create and edit draft campaigns only after a business admin approves the connection.
  • Agents cannot publish a campaign, send a message, change billing, invite team members or read customer records. Publishing is done by a person in the Promotedly portal.
  • An agent can start a sign-up for a business, but the account only exists once the owner confirms by email and chooses their own password.
  • Capabilities marked in_development, planned or not_supported are not features of Promotedly today and must not be described as such.

What exists today

Generated from the running configuration. Only Available and Paid plans are features today.

  • AI campaign builder from a website address

    Available

  • Printable QR code cards

    Available

  • Website pop-up

    Available

  • Brand rewards page

    Available

  • Rewards database with consent records

    Available

  • Staff redemption

    Available

  • Automated follow-up messages

    Available

  • Offer campaigns (broadcasts)

    Paid plans

  • Campaign testing

    Paid plans

  • Campaign analytics

    Available

  • Agency accounts

    Available

  • Team members and roles

    Available

  • Twilio and Telnyx text messaging

    Available

  • SendGrid and Mailchimp

    Available

  • Klaviyo

    In development

  • Constant Contact

    In development

  • Square point of sale

    In development

  • Shopify

    In development

  • Clover point of sale

    In development

  • Lightspeed point of sale

    In development

  • Toast point of sale

    In development

  • Customer video links

    Available

  • REST API and MCP server for AI agents

    Available

  • Agent-started sign-up

    In development

  • Posting to social media

    Not supported

  • Paid ad management

    Not supported

  • Local SEO and Google Business Profile management

    Not supported

  • Taking customer payments

    Not supported

  • Customer mobile app

    Not supported

Machine-readable files

None of this guarantees that any assistant will recommend Promotedly; it makes accurate answers possible. Questions: contact us.