API Reference

AdBliss API Docs

Everything you need to start pulling data. Most integrations are live in under 10 minutes.

Quick Start

Get your first response in three steps.

Step 1 — Get your API key

Log into your AdBliss dashboard → Settings → API. Your key is available immediately on all plans.

Step 2 — Make your first call

bash
curl "https://api.adbliss.io/v1/dashboard/kpis?org_id=YOUR_ORG_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Step 3 — Read the response

json
{
  "success": true,
  "data": {
    "spend_cents": 4000000,
    "cac_cents": 3200,
    "conversions": 312,
    "net_revenue_cents": 18316000,
    "roas": 4.6,
    "roas_basis": "first_party_net",
    "ctr_pct": 2.42,
    "spend_currencies": ["USD"],
    "spend_by_platform": {
      "facebook": 2400000,
      "google": 1600000
    }
  }
}

Your full portfolio snapshot — aggregated spend, CAC, ROAS, and conversions across all connected platforms.


Authentication

All requests require a Bearer token in the Authorization header.

http
Authorization: Bearer YOUR_API_KEY

Key Management

  • •Keys are scoped per organization
  • •Create and revoke keys anytime from Settings → API
  • •Keys can be scoped to specific permissions (e.g. tools:read, tools:execute)
  • •Optional expiration — set expires_in_days when creating a key
  • •Never expose keys in client-side code

Organization context

Most endpoints require an org_id. Pass it as a query parameter, request body field, or X-Org-Id header.

bash
# As a query parameter
curl "https://api.adbliss.io/v1/dashboard/kpis?org_id=YOUR_ORG_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

# As a header
curl "https://api.adbliss.io/v1/dashboard/kpis" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Org-Id: YOUR_ORG_ID"

Base URL & Versioning

Production

text
https://api.adbliss.io/v1/

Staging

text
https://api-dev.adbliss.io/v1/
All endpoints are versioned under /v1/. We do not make breaking changes within a version. When a new major version ships, the previous version stays live for at least 6 months with advance notice.

Core Endpoints

GET/v1/dashboard/kpis

Aggregated KPIs across all connected platforms — spend, CAC, conversions, revenue, ROAS, and per-platform breakdowns.

Parameters
org_idreq
string

Organization ID

days
number

Lookback window in days (1–365, default 30)

Response

json
{
  "success": true,
  "data": {
    "spend_cents": 4820000,
    "cac_cents": 3200,
    "conversions": 312,
    "net_revenue_cents": 18316000,
    "roas": 3.8,
    "roas_basis": "first_party_net",
    "ctr_pct": 2.42,
    "spend_change_pct": -4.0,
    "cac_change_pct": 12.0,
    "spend_currencies": ["USD"],
    "spend_currencies_by_platform": { "facebook": ["USD"], "google": ["USD"] },
    "spend_by_platform": { "facebook": 2400000, "google": 1600000 },
    "conversions_by_source": { "facebook": 180, "google": 132 },
    "cac_timeline": [...]
  }
}
GET/v1/dashboard/spend

Daily spend time series and platform breakdown for the requested window.

Parameters
org_idreq
string

Organization ID

days
number

Lookback window in days (1–365, default 30)

Response

json
{
  "success": true,
  "data": {
    "total_spend_cents": 4000000,
    "by_platform": { "facebook": 2400000, "google": 1600000 },
    "daily": [
      { "date": "2026-04-16", "spend_cents": 162000 },
      { "date": "2026-04-17", "spend_cents": 158000 }
    ]
  }
}
GET/v1/connectors/connected

Lists all active platform connectors for the org, including sync status and last sync time.

Parameters
org_idreq
string

Organization ID

Response

json
{
  "success": true,
  "data": [
    {
      "id": "conn_abc123",
      "platform": "facebook",
      "status": "active",
      "last_synced_at": "2026-04-17T08:14:00Z",
      "account_name": "Acme Ads"
    },
    {
      "id": "conn_def456",
      "platform": "google",
      "status": "active",
      "last_synced_at": "2026-04-17T08:15:00Z",
      "account_name": "Acme — Google Ads"
    }
  ]
}
GET/v1/campaigns

Unified campaign list across all connected platforms with aggregated metrics. Filterable by platform, status, and date window.

Parameters
org_idreq
string

Organization ID

platforms
string

Comma-separated: facebook, google.

status
string

Campaign status filter

days
number

Lookback window (1–365, default 30)

Response

json
{
  "success": true,
  "data": {
    "campaigns": [
      {
        "id": "camp_abc123",
        "platform": "facebook",
        "name": "Spring Sale — Retargeting",
        "status": "ACTIVE",
        "spend_cents": 1240000,
        "currency": "USD",
        "currencies": ["USD"],
        "ctr_pct": 2.42,
        "conversions": 98,
        "roas": 4.2
      }
    ],
    "summary": {
      "total_campaigns": 14,
      "total_spend_cents": 4820000,
      "currencies": ["USD"],
      "total_conversions": 312,
      "by_platform": {
        "facebook": { "spend_cents": 2400000, "currencies": ["USD"] },
        "google": { "spend_cents": 2420000, "currencies": ["USD"] }
      }
    }
  }
}
GET/v1/campaigns/{id}

Full detail for a single campaign, including performance metrics over the specified window.

Parameters
idreq
string

Internal campaign UUID

days
number

Lookback window (1–365, default 30)

Response

json
{
  "success": true,
  "data": {
    "id": "camp_abc123",
    "metrics": { "spend_cents": 1240000, "ctr_pct": 2.42 },
    "ad_groups": [{ "ad_group_id": "ag_123", "ctr_pct": 2.17 }]
  }
}

Analytics

Platform metrics endpoints follow the same shape for Facebook and Google — swap the platform slug in the path. All require start_date and end_date in YYYY-MM-DD format.
GET/v1/analytics/{platform}/metrics/daily

Daily ad metrics at campaign, ad group, or ad level. Replace {platform} with facebook or google.

Parameters
org_idreq
string

Organization ID

start_datereq
string

YYYY-MM-DD

end_datereq
string

YYYY-MM-DD

level
string

campaign | ad_group | ad (default campaign)

campaign_id
string

Filter to a specific campaign

limit
number

Max rows (1–10000, default 1000)

offset
number

Pagination offset (default 0)

Response

json
{
  "success": true,
  "data": {
    "metrics": [
      {
        "date": "2026-04-17",
        "campaign_id": "camp_abc123",
        "impressions": 42100,
        "clicks": 980,
        "spend_cents": 162000,
        "currency": "USD",
        "currencies": ["USD"],
        "ctr_pct": 2.33,
        "conversions": 14
      }
    ],
    "summary": {
      "total_impressions": 980000,
      "total_clicks": 22400,
      "total_spend_cents": 4820000,
      "currencies": ["USD"],
      "total_conversions": 312
    },
    "total": 45,
    "date_range": { "start": "2026-04-01", "end": "2026-04-17" },
    "level": "campaign"
  }
}
GET/v1/analytics/cac/summary

Current customer acquisition cost with trend direction and cost breakdown.

Parameters
org_idreq
string

Organization ID

days
number

Lookback period (1–90, default 30)

Response

json
{
  "success": true,
  "data": {
    "cac_cents": 3200,
    "total_spend_cents": 4820000,
    "total_conversions": 312,
    "net_revenue_cents": 18316000,
    "avg_daily_spend_cents": 283529,
    "trend": "improving"
  }
}
GET/v1/analytics/cac/timeline

CAC trend over time with optional platform breakdown.

Parameters
org_idreq
string

Organization ID

days
number

Historical window (1–90, default 7)

breakdown
string

overview | platform | campaign (default overview)

Response

json
{
  "success": true,
  "data": {
    "timeline": [
      { "date": "2026-04-10", "spend_cents": 2380000, "cac_cents": 3400, "net_revenue_cents": 8910000 },
      { "date": "2026-04-17", "spend_cents": 2440000, "cac_cents": 3200, "net_revenue_cents": 9406000 }
    ],
    "metadata": {
      "start_date": "2026-04-10",
      "end_date": "2026-04-17",
      "days": 7
    }
  }
}
GET/v1/analytics/revenue

Unified revenue aggregation across all connected payment and revenue sources (Stripe, Shopify, etc.).

Parameters
org_idreq
string

Organization ID

days
number

Historical lookback (1–365, default 30)

sources
string

Comma-separated: stripe, shopify, etc.

Response

json
{
  "window": { "start": "2026-04-01", "end": "2026-04-30" },
  "currency": "USD",
  "summary": {
    "gross_revenue_cents": 19000000,
    "refunds_cents": -684000,
    "net_revenue_cents": 18316000,
    "refund_rate_pct": 3.6,
    "transactions": 312,
    "unique_customers": 289,
    "aov_cents": 58700
  },
  "time_series": [{ "date": "2026-04-17", "net_revenue_cents": 1080000, "transactions": 18 }],
  "by_source": { "stripe": { "net_revenue_cents": 18316000, "gross_revenue_cents": 19000000, "refunds_cents": -684000, "transactions": 312 } }
}

AI Analysis

AI analysis jobs run asynchronously — kick one off, poll for status, then read decisions. Jobs count against your plan's monthly AI run allocation.

POST/v1/ai/analysis/run

Initiates a background AI analysis job. Returns a job_id to poll with.

Request body

json
{
  "org_id": "YOUR_ORG_ID",
  "days": 7
}

Response

json
{
  "success": true,
  "data": {
    "job_id": "job_xyz789",
    "status": "queued"
  }
}
GET/v1/ai/analysis/status/{job_id}

Poll the progress of a running analysis job. Status will be queued → running → completed | failed.

Parameters
job_idreq
string

Job ID from /run response

org_idreq
string

Organization ID

Response

json
{
  "success": true,
  "data": {
    "job_id": "job_xyz789",
    "status": "completed",
    "progress": {
      "total_entities": 14,
      "processed_entities": 14,
      "current_level": null
    },
    "created_at": "2026-04-17T10:00:00Z",
    "started_at": "2026-04-17T10:00:02Z",
    "completed_at": "2026-04-17T10:00:38Z",
    "error_message": null
  }
}
GET/v1/ai/analysis/latest

Fetches the most recent completed analysis for the org — no job_id needed.

Parameters
org_idreq
string

Organization ID

Response

json
{
  "success": true,
  "data": { ... }
}
GET/v1/ai/decisions

Lists AI recommendations. Filter by status, confidence, or campaign.

Parameters
org_idreq
string

Organization ID

status
string

pending | approved | executed

min_confidence
string

low | medium | high

campaign_id
string

Filter to a specific campaign

limit
number

Max results (1–500, default 100)

offset
number

Pagination offset (default 0)

Response

json
{
  "success": true,
  "data": {
    "decisions": [
      {
        "id": "dec_abc123",
        "type": "budget_shift",
        "confidence": "high",
        "status": "pending",
        "summary": "Shift 20% of Facebook spend to Google — Google ROAS is 2.1x higher.",
        "affected_campaigns": ["camp_abc123"]
      }
    ]
  }
}

Quota: Each /run call counts against your plan's monthly AI run allocation. Staging runs do not consume quota.


Rate Limits & Quotas

Limits are based on your plan's monthly allocation. Overages are metered and billed at month-end — no hard cutoffs that break your integration mid-run.

PlanAPI calls/moAI runs/moOverage
Free503$0.02/call
API5003$0.02/call
Starter2,00050$0.015/call
Growth10,000150$0.01/call

Quota state is returned in every response header:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 2026-05-01T00:00:00Z

Errors

All errors return a consistent JSON envelope with a code and message.

json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key."
  }
}
StatusCodeMeaning
401unauthorizedMissing or invalid API key
403forbiddenKey lacks permission for this resource or scope
404not_foundResource does not exist
422validation_errorRequest body or params failed validation
429rate_limitedMonthly quota exhausted — overage billing applies
500internal_errorSomething went wrong on our end

Sandbox

The staging environment lets you test your integration against realistic data before going live. Staging usage does not count against your plan quota.

Staging Access

  • •Get your staging key from Settings → API on the staging dashboard
  • •Staging and production use separate credentials — never mix them
  • •Staging data is realistic but isolated from production
  • •Self-serve — available to all plans immediately

Staging base URL

text
https://api-dev.adbliss.io/v1/
bash
curl "https://api-dev.adbliss.io/v1/dashboard/kpis?org_id=YOUR_ORG_ID" \
  -H "Authorization: Bearer YOUR_STAGING_KEY"

MCP Setup

AdBliss ships an MCP server so you can query your ad data directly from Claude, Cursor, or any MCP-compatible AI tool — no API calls to write.

Claude Desktop

Add the following to your claude_desktop_config.json:

json
{
  "mcpServers": {
    "adbliss": {
      "url": "https://mcp.adbliss.io/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Add to your Cursor MCP settings (~/.cursor/mcp.json):

json
{
  "adbliss": {
    "url": "https://mcp.adbliss.io/mcp",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY"
    }
  }
}

Once connected, you can ask Claude or Cursor things like “What's my ROAS across all platforms this week?” or “Which campaigns should I pause based on yesterday's data?” — directly from chat, no copy-pasting.


Changelog

2026-04-22
v1.4
  • +Added /v1/ai/analysis/run, /status, and /latest for async AI jobs
  • +Added /v1/ai/decisions for reading AI recommendations
  • +Added CAC timeline and summary analytics endpoints
  • +Added /v1/revenue for unified payment source aggregation
2026-03-01
v1.3
  • +Platform-specific analytics: /v1/analytics/{platform}/metrics/daily
  • +Campaign write operations: budget and status mutations
  • +org_id now accepted via X-Org-Id header
2026-01-15
v1.2
  • +Initial public release
  • +Dashboard KPIs, spend, connectors, and campaigns endpoints
  • +Bearer token authentication with scope-based permissions

Ready to start building?

Get your API key in seconds. No credit card required on the Free plan.

Get Your API Key