API Reference

Build on top of Meridian with our RESTful API. Access signal data, attribution models, and reporting programmatically.

Overview

The Meridian API is organized around REST. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. All API requests must be made over HTTPS.

Base URL

https://api.meridian.io/v2

API Version

v2 (stable)

Authentication

Authenticate your API requests by including your API key in the Authorization header as a Bearer token. You can find your API key in the Meridian dashboard under Settings > API.

# Authenticate with your API key
curl https://api.meridian.io/v2/signals \
  -H "Authorization: Bearer mk_live_your_api_key_here" \
  -H "Content-Type: application/json"

API keys carry significant privileges. Do not share your secret API keys in publicly accessible areas such as client-side code, GitHub repositories, or public documentation.

Rate Limits

Rate limits are applied per API key. When you exceed the limit, the API returns a 429 Too Many Requests response.

Plan	Rate Limit	Burst
Growth	1,000 requests/min	50 concurrent
Enterprise	10,000 requests/min	200 concurrent

Rate limit headers are included in every response: X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Core Endpoints

GET /v2/signals

List all signals for the authenticated account. Supports pagination, date range filtering, and channel filtering.

# List signals from the last 7 days
curl "https://api.meridian.io/v2/signals?start_date=2024-01-11&end_date=2024-01-18&limit=50" \
  -H "Authorization: Bearer mk_live_your_api_key_here"

// Response (200 OK)
{
  "data": [
    {
      "id": "sig_abc123",
      "type": "page_view",
      "channel": "google_ads",
      "user_id": "usr_def456",
      "timestamp": "2024-01-15T14:32:00Z",
      "properties": {
        "campaign": "q1_brand_awareness",
        "device": "mobile"
      }
    }
  ],
  "pagination": {
    "total": 1284,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

GET /v2/journeys/:id

Retrieve a specific customer journey by ID, including all associated touchpoints, attribution weights, and conversion events.

curl https://api.meridian.io/v2/journeys/jrn_xyz789 \
  -H "Authorization: Bearer mk_live_your_api_key_here"

POST /v2/signals

Create a new signal event. Use this to send custom events from your backend systems into Meridian for attribution tracking.

curl https://api.meridian.io/v2/signals \
  -X POST \
  -H "Authorization: Bearer mk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "form_submission",
    "user_id": "usr_def456",
    "channel": "organic_search",
    "properties": {
      "form_name": "demo_request",
      "page_url": "/pricing"
    }
  }'

GET /v2/attribution/report

Generate an attribution report for a specified date range and model type. Returns channel-level attribution data with spend, revenue, and ROI metrics.

curl "https://api.meridian.io/v2/attribution/report?model=data_driven&start=2024-01-01&end=2024-01-31" \
  -H "Authorization: Bearer mk_live_your_api_key_here"

POST /v2/webhooks

Create a webhook subscription to receive real-time notifications when specific events occur, such as anomaly detection or conversion milestones.

curl https://api.meridian.io/v2/webhooks \
  -X POST \
  -H "Authorization: Bearer mk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/meridian",
    "events": ["anomaly.detected", "conversion.completed"],
    "secret": "whsec_your_signing_secret"
  }'

Client Libraries

Official SDKs are available for popular languages. Community-maintained libraries are also welcome.

Node.js

npm install @meridian/sdk

Python

pip install meridian-sdk

Ruby

gem install meridian

Ready to build with the Meridian API?

Start Free Trial