Plainrouter API

Use the Plainrouter REST API to send consented conversion events, inspect delivery, read stored reports, and submit or track governed action proposals. Start with an authenticated read from your workspace. The unauthenticated sandbox is retired. To compare this API with Meta’s own Marketing API, see the Meta Ads API guide.

Make your first request

Read retained events with your workspace Server secret.

Authenticate production requests

Choose a Server secret, Workspace key, or Management key for the interface.

Connection details

Setting	Value
Base URL	`https://plainrouter.com/api/v1`
Request and response format	JSON; each endpoint documents its schema
Signals authentication	Bearer Server secret for the workspace
Actions authentication	Bearer Workspace key with the operation grant: Read for supported reads, Write for previews and proposals; see Actions API
Management authentication	Bearer Management key; see management operations
API schema	Published OpenAPI contract
Official clients	TypeScript, Python, Ruby, PHP, Go, and CLI

This is Plainrouter’s API, not Meta’s Graph API. Workspace keys used for MCP do not authenticate the Signals REST API.

Make your first request

You need an active Signals workspace, its Server secret and an HTTP client such as cURL. Store PLAINROUTER_TOKEN in a protected server environment; do not paste the secret into chat or commit it.

curl https://plainrouter.com/api/v1/dashboard/events \
  --header "Authorization: Bearer $PLAINROUTER_TOKEN" \
  --header "Accept: application/json"

HTTP 200 confirms that the authenticated list request succeeded. Inspect the returned data and pagination before treating it as complete. An empty list is valid; it does not verify browser collection or destination delivery. This read creates no conversion. For an account-bound Actions read, use the separate Actions API.

Choose an endpoint group

Group	Operations	Use it to
Events	Submit, verify ingestion, retrieve, or list events	Send conversions and inspect event and delivery state.
Actions	Dry-run or submit a proposal; read actions, batches, policy, and decision receipts	Preview policy, then follow a governed change through human review and its stored outcome.
Destination testing	Set test mode and send a controlled test purchase	Check the connected Meta destination. These operations can change state or contact Meta.
Delivery replay	Replay selected eligible failed deliveries	Retry retained payloads after fixing the destination problem.
Reports	Reconciliation and Event Match Quality	Read stored conversion comparisons and matching reports.
Privacy	Delete user data	Request workspace-scoped deletion using the endpoint’s documented identifiers.

Expand a group in the sidebar for its request fields, responses, and examples. Production operations use real workspace data; check each endpoint’s side effects before sending a request.

Set up collection and delivery

Set up Signals, then configure your server with its Server secret. Keep credentials out of browser code, prompts, and source control.
Use the identity-free ingestion diagnostic if you only need to check the authenticated write path. It does not verify a real website arrival.
For advertising delivery, connect the intended Meta dataset. Send an actual conversion only with the recorded consent and original event data required by the conversion guide.
Preserve the event ID on retries and inspect the delivery trace. HTTP 202 is ingestion acceptance; destination acceptance is a separate result.

Handle errors and retries

Send Accept: application/json on REST requests and Content-Type: application/json when sending a JSON body. Agent API routes under /api/v1/agent/ return JSON errors for authentication, validation and busy-workspace failures even when Accept is absent. This does not change MCP’s streaming headers. If a client receives HTML or a sign-in redirect, inspect the original status, Content-Type and request URL before parsing the body. Use the API base URL and the endpoint’s credential type; a dashboard URL is not an API endpoint. Do not forward a bearer key to a redirect target.

Result	Next step
`401`	Check the credential type, scope and validity for the selected interface.
`410` with `sandbox_retired`	Remove old sandbox calls and follow the migration guidance.
`422`	Read the field errors and correct the payload before retrying.
New production event: `202`	Read `warnings` and inspect delivery separately.
Duplicate production event: `200`	Keep the original ID. The response does not replay failed delivery.
Uncertain production write after a timeout	Retry the original event ID and payload, subject to continued consent eligibility.

See conversion errors, consent warnings for the applicable details. Prefer an official SDK when you want typed operations in application code.

Overview

Endpoints

Resources

Sandbox retirement

Make your first request

Authenticate production requests

Connection details

Make your first request

Choose an endpoint group

Set up collection and delivery

Handle errors and retries

Make your first request

Authenticate production requests

​Connection details

​Make your first request

​Choose an endpoint group

​Set up collection and delivery

​Handle errors and retries

Connection details

Make your first request

Choose an endpoint group

Set up collection and delivery

Handle errors and retries