REST API authentication and request conventions

The public REST API reads project configuration and analytics, saves configuration drafts, starts exports, and publishes a project. It is distinct from the dashboard's session API and the hosted MCP connection.

Base URL and authentication

The base URL is https://api.rightmessage.com/v1. Authenticate with an API token in Authorization: Bearer YOUR_API_TOKEN. Send Accept: application/json; JSON bodies also use Content-Type: application/json.

The API token setup guide explains how to create your first token in the dashboard.

Project endpoints use /{teamPid}/.... This is the public project identifier, not its name or an internal database ID. Resource IDs come from responses and are scoped to the chosen project's configuration. Use the returned strings unchanged.

A token belongs to a user, not one project. Project members and administrators can access project routes. Ordinary API mutations do not require the owner role. Nonmembers receive 403. An unknown project receives 404.

Token creation requires API access on the account. Project endpoints do not repeat that token-creation entitlement check. Subscription and publication requirements remain separate from token abilities. See token creation and its plan requirement.

Illustrative authenticated request

This illustrative request reads flows from the fictional WorkForge project.

GET /v1/123456/flows HTTP/1.1
Host: api.rightmessage.com
Authorization: Bearer YOUR_API_TOKEN
Accept: application/json

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

Abilities and their limits

Read routes accept either read or write. Omitted abilities on token creation default to ["*"]. An explicitly empty abilities array remains empty.

These abilities are not a comprehensive security sandbox. The user-scoped /tokens and /oauth-connections routes require authentication but have no ability middleware. A read-only token can therefore reach token management, including creation when the account gate permits it. Tokens are not project-restricted. The hosted MCP route does not apply the public REST ability checks either. Do not distribute a token on the assumption that read prevents every write outside project v1 routes.

Tokens and OAuth connections documents the exact management operations.

Rate limits

User-scoped token and OAuth management routes allow 60 requests per minute. Project routes allow 120 requests per minute. These are route limits, not independent quotas for every resource or token. Excess requests return 429. The response exposes remaining-limit information and a retry interval when throttled.

These limits do not apply by inheritance to the separate /api hosted-page and template routes. See hosted page and template API.

JSON and validation

Request names are case-sensitive. Most v1 resource fields use snake_case, while flow definitions and nested design/input settings retain documented camelCase names.

Optional means a field can be omitted. Nullable means request validation accepts an explicit JSON null, though stored-configuration validation may still reject it. Boolean request fields accept booleans, 0, 1, "0", and "1" without converting their types. Use JSON booleans and numbers for stored boolean and numeric fields. A field described as array can represent an object or a list. Follow the documented shape.

Undocumented top-level fields are not part of the write contract. Some nested objects accept additional keys, but mapping and full-configuration validation determine whether those keys survive. An accepted request shape does not guarantee a valid flow, campaign, or widget configuration.

Success envelopes

Do not assume every response has data. Errors, publication responses, and dashboard media endpoints use other shapes.

Error contract

Authenticated users can send GET requests to the demo project. Demo mutations return 403. A request from a suspended account invalidates its presented API token and session.

Illustrative validation response:

{
	"message": "The name field is required.",
	"errors": {"name": ["The name field is required."]}
}

Draft and live configuration

Configuration CRUD reads the draft first, then stable configuration. Mutations save a draft and a snapshot of the previous configuration, and notify open dashboards. They do not change the published snippet by themselves.

Saving includes configuration repair before schema validation. The saved response can therefore contain defaults absent from the request, including question Other labels, form fields, and widget design settings. Validation covers the whole configuration, not just the edited resource. A failed mutation can leave a snapshot or a newly created draft behind; an error is not a transaction-level promise that nothing changed.

Active question A/B tests protect wording, answers, display, behavior, and linked Auto-Segment rules at the configuration save boundary. Such a change can return 422 under errors.config, including through a segment-group update or deletion. Sync mappings, internal names, and flow membership remain editable. This is separate from the token's write ability.

A request to a project you belong to can switch your current project to the one in the URL. Account-level entitlement checks then use that project.

PUT and PATCH are both partial updates at the top level. Nested merge and replacement rules differ by resource. In particular, a campaign's supplied changes list and a flow's supplied definition can remove content omitted from the payload.

Publishing applies the entire project draft, not just changes made by the current token. Analytics describe recorded activity, not draft previews. Project data endpoints have different draft and live sources. Hosted-page changes take effect separately and do not wait for v1 publication.