API reference

Motionworks API v2 is a Cloudflare Workers-based REST API at api2.mworks.com/v2. It is the successor to the legacy Intermx API and is the recommended platform for new integrations.

Base URL

https://api2.mworks.com/v2

api2.mworks.com is the canonical Motionworks API host. Use it for all production traffic.

Authentication

Two authentication patterns are supported:

Calling an authenticated endpoint with the API-key pattern:

curl https://api2.mworks.com/v2/markets \
  -H "X-API-Key: $MW_API_KEY"

Sandbox onboarding

Get a sandbox API key by signing up at app2.mworks.com. New accounts receive a 10 req/min sandbox-tier key automatically — no waitlist, no sales call. Verify the key with the public health endpoint:

curl https://api2.mworks.com/v2/health \
  -H "X-API-Key: $MW_API_KEY"

Rate limits

Tier	Limit	Audience
Sandbox	10 req/min	Trial keys, evaluation
Growth	100 req/min	Production single-tenant integrations
Enterprise	1,000 req/min	High-volume enterprise integrations

Every response includes the rate-limit headers:

• X-RateLimit-Limit — requests permitted in the current window.
• X-RateLimit-Remaining — requests remaining in the current window.
• Retry-After — seconds to wait before retrying, attached to 429 responses.

Error envelope

Every error response uses the same JSON shape. The X-Request-Id response header always matches the request_id field in the body — use it when filing support tickets.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Sandbox tier allows 10 requests per minute. Retry after 38s.",
    "status": 429,
    "request_id": "01HQ7K3W9V1F8X2YZ4M5N6P7QR",
    "product": "platform",
    "docs_url": "https://mworks.com/docs/api/#rate-limits"
  }
}

Stable error codes

Code	Description
INVALID_API_KEY	The X-API-Key header is missing or does not match a known key.
EXPIRED_API_KEY	The X-API-Key header matches a known key, but the key has been revoked or expired.
INSUFFICIENT_CREDITS	The org's credit balance is below the cost of the requested call.
RATE_LIMIT_EXCEEDED	The org has exceeded its tier's per-minute request quota.
NOT_FOUND	The requested resource (segment, market, place, path, etc.) does not exist.
VALIDATION_ERROR	Request parameters or body failed schema validation.
INTERNAL_ERROR	An unexpected error occurred. The request was logged with X-Request-Id.
DATA_UNAVAILABLE	The endpoint and field are valid, but no data is available for the requested period or geography.
UPSTREAM_UNAVAILABLE	A credentialed external upstream returned a non-OK response. Typically transient and retryable; distinct from DATA_UNAVAILABLE, which usually indicates a deploy-config issue.
NOT_YET_AVAILABLE	The endpoint or field is on the published roadmap; data is not yet produced.
SCOPE_NOT_SUPPORTED	The API key's scope is not supported for this endpoint. Only 'read' scope is honored in MVP; mint a read-scoped key via POST /v2/account/keys.
ORIGIN_NOT_ALLOWED	The request's Origin header does not match the API key's allowed_origins list, the list is empty (key effectively disabled), or the key requires an Origin and none was provided. See ADR-25.
AMBIGUOUS_AUTH	The request includes more than one of {X-API-Key, Authorization Bearer, X-MW-Anon-Session}. Choose exactly one auth header per request.
INVALID_API_KEY	The X-API-Key header is missing or does not match a known key.
EXPIRED_API_KEY	The X-API-Key header matches a known key, but the key has been revoked or expired.
UNAUTHORIZED	Session-layer authentication failure (invalid, missing, or expired JWT, anonymous-session token, or admin credentials). Use INVALID_API_KEY for X-API-Key failures.
UNAUTHORIZED	Session-layer authentication failure (invalid, missing, or expired JWT, anonymous-session token, or admin credentials). Use INVALID_API_KEY for X-API-Key failures.
UNAUTHORIZED	Session-layer authentication failure (invalid, missing, or expired JWT, anonymous-session token, or admin credentials). Use INVALID_API_KEY for X-API-Key failures.
CONFLICT	The requested operation conflicts with the current resource state (e.g. concurrent session-extend on the same anonymous session). Retry with a fresh request id.

Code samples

Calling GET /v2/markets (defined on the platform spec) to list available DMAs / metro markets.

curl

curl https://api2.mworks.com/v2/markets \
  -H "X-API-Key: $MW_API_KEY"

Python (requests)

import os
import requests

resp = requests.get(
    "https://api2.mworks.com/v2/markets",
    headers={"X-API-Key": os.environ["MW_API_KEY"]},
    timeout=10,
)
resp.raise_for_status()
markets = resp.json()["data"]
print(f"{len(markets)} markets")

JavaScript (fetch)

const resp = await fetch("https://api2.mworks.com/v2/markets", {
  headers: { "X-API-Key": process.env.MW_API_KEY },
});
if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
const { data: markets } = await resp.json();
console.log(`${markets.length} markets`);

API reference

One Redoc-rendered reference per product, sourced from the OpenAPI 3.1 specs in api-mworks-com.

Download specs

OpenAPI YAMLs are available for download:

• platform.yaml — Platform (Markets, Segments, Auth, Billing)
• pathcast.yaml — Pathcast (Paths, Viewsheds, Traffic)
• placecast.yaml — Placecast (Foot Traffic)
• places.yaml — Places Library
• popcast.yaml — Popcast (Population Intelligence)
• popcast-ambient.yaml — Popcast Ambient API
• popcast-attention.yaml — Popcast Attention API
• popcast-change.yaml — Popcast Change API
• popcast-conscience.yaml — Popcast Conscience API
• popcast-reporting.yaml — Popcast Reporting API
• popcast-signal.yaml — Popcast Signal API
• redemption.yaml — Redemption
• set-dynamics.yaml — Set Dynamics (Campaign Reach & Frequency)
• viewcast.yaml — Viewcast (Inventory Profiles)

Contact

Questions or want enterprise access? Email api@mworks.com.