RightMessage
Developers

Build on RightMessage from your own code or your AI assistant.

Read your projects and analytics, save changes as drafts, and publish when you’re ready, through the REST API or the hosted MCP server. Then render campaigns at the edge with our open-source packages.

Make your first requestOpenAPI description
Base URL
https://api.rightmessage.com/v1
OpenAPI
https://rightmessage.com/openapi.json
Authentication
Personal API token as a bearer token
API tokens
Scale or Pro plan
Rate limits
60/min or 120/min
Responses
JSON
Quickstart

Your first API call in three steps.

  1. 1

    Create an API token

    Open Your account › API & AI access › API tokens in the app and copy the token into your secret storage. Creating one needs the Scale or Pro plan.

    Token guide
  2. 2

    Copy your project ID

    Project settings › General has a copy button. It's the public ID from your install snippet, not a secret.

    Find your project ID
  3. 3

    Make a request

    List the flows in your project. Changes you make through the API save to the draft until you publish.

    Request conventions
GET /v1/{projectId}/flowsTerminal
curl https://api.rightmessage.com/v1/YOUR_PROJECT_ID/flows \
  --header "Authorization: Bearer $RIGHTMESSAGE_TOKEN" \
  --header "Accept: application/json"

Illustrative response

{
  "data": [
    {
      "id": "ofn_example1",
      "name": "WorkForge welcome",
      "definition": {
        "type": "root",
        "child": []
      }
    }
  ]
}

Create, update, and delete calls save to the project draft. Publishing is a separate POST /v1/YOUR_PROJECT_ID/publish that needs the publish ability.

Authentication

One token for the API. OAuth or a token for MCP.

REST API

Send a personal API token as Authorization: Bearer. The REST API doesn’t accept OAuth tokens. A token belongs to your user, so it reaches every project you can access. Pick its abilities when you create it through the API.

read
Configuration, analytics, data, and export status GET routes.
write
Everything read can do, plus creating, updating, and deleting configuration and starting exports.
publish
Publishing the project draft. It doesn't grant the read or write routes by itself.
*
Every ability. Tokens created in the app, or without abilities, get this by default.

MCP server

Most assistants sign in with hosted OAuth: OAuth 2.1 with PKCE, scope mcp:use, with dynamic client registration. If your client can’t do OAuth, send an API token as a bearer token instead. OAuth works only on the MCP endpoint.

https://api.rightmessage.com/mcp/rightmessage

Agent authentication guideMCP authorization reference
Limits and errors

Predictable limits. JSON errors you can handle.

Rate limits

  • Token and OAuth connection management (/tokens, /oauth-connections)60/min
  • Project routes (/{projectId}/...)120/min

Error responses

401
Missing or invalid token. A JSON message plus the header WWW-Authenticate: Bearer realm="rightmessage-api".
403
Not a project member, or the ability, plan, or account status doesn’t allow it. Usually a JSON message.
404
Unknown project or resource.
422
Validation failed: a message plus an errors map of field paths.
429
Rate limit exceeded. Wait for the retry interval in the response.
Full error contract
Beyond the API

Connect an assistant, render at the edge, reuse our playbooks.

MCP server

Connect Claude, ChatGPT, Cursor, or another MCP client to https://api.rightmessage.com/mcp/rightmessage. Sign in with hosted OAuth (scope mcp:use) or send an API token. MCP server access is included with every RightMessage plan.

MCP guideMCP reference (Markdown)

Edge packages

Open-source, MIT-licensed packages that apply supported campaigns before the page reaches the browser: @rightmessage/edge (core engine), @rightmessage/cloudflare (Cloudflare Worker), @rightmessage/next (Next.js).

npmedgeedge-cloudflareedge-nextjs

Agent skills

Public playbooks your AI assistant can follow to audit a project, build a quiz, personalize a page, or decide what to test, with AGENTS.md and plugin.json for agent tools.

mcp-skills on GitHubSkills index
For AI agents

Machine-readable from the start.

Point an agent at these files instead of scraping pages. Every help article is also available as Markdown.

Stuck on an integration?

The REST API reference documents every endpoint. If something doesn’t behave the way it says, email support@rightmessage.com with the request, the response, and your project ID.

REST API referenceContact us