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
curl "https://api.adbliss.io/v1/dashboard/kpis?org_id=YOUR_ORG_ID" \
-H "Authorization: Bearer YOUR_API_KEY"Step 3 — Read the response
{
"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.
Authorization: Bearer YOUR_API_KEYKey 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_dayswhen 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.
# 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
https://api.adbliss.io/v1/Staging
https://api-dev.adbliss.io/v1//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
/v1/dashboard/kpisAggregated KPIs across all connected platforms — spend, CAC, conversions, revenue, ROAS, and per-platform breakdowns.
Organization ID
Lookback window in days (1–365, default 30)
Response
{
"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": [...]
}
}/v1/dashboard/spendDaily spend time series and platform breakdown for the requested window.
Organization ID
Lookback window in days (1–365, default 30)
Response
{
"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 }
]
}
}/v1/connectors/connectedLists all active platform connectors for the org, including sync status and last sync time.
Organization ID
Response
{
"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"
}
]
}/v1/campaignsUnified campaign list across all connected platforms with aggregated metrics. Filterable by platform, status, and date window.
Organization ID
Comma-separated: facebook, google.
Campaign status filter
Lookback window (1–365, default 30)
Response
{
"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"] }
}
}
}
}/v1/campaigns/{id}Full detail for a single campaign, including performance metrics over the specified window.
Internal campaign UUID
Lookback window (1–365, default 30)
Response
{
"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
start_date and end_date in YYYY-MM-DD format./v1/analytics/{platform}/metrics/dailyDaily ad metrics at campaign, ad group, or ad level. Replace {platform} with facebook or google.
Organization ID
YYYY-MM-DD
YYYY-MM-DD
campaign | ad_group | ad (default campaign)
Filter to a specific campaign
Max rows (1–10000, default 1000)
Pagination offset (default 0)
Response
{
"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"
}
}/v1/analytics/cac/summaryCurrent customer acquisition cost with trend direction and cost breakdown.
Organization ID
Lookback period (1–90, default 30)
Response
{
"success": true,
"data": {
"cac_cents": 3200,
"total_spend_cents": 4820000,
"total_conversions": 312,
"net_revenue_cents": 18316000,
"avg_daily_spend_cents": 283529,
"trend": "improving"
}
}/v1/analytics/cac/timelineCAC trend over time with optional platform breakdown.
Organization ID
Historical window (1–90, default 7)
overview | platform | campaign (default overview)
Response
{
"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
}
}
}/v1/analytics/revenueUnified revenue aggregation across all connected payment and revenue sources (Stripe, Shopify, etc.).
Organization ID
Historical lookback (1–365, default 30)
Comma-separated: stripe, shopify, etc.
Response
{
"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.
/v1/ai/analysis/runInitiates a background AI analysis job. Returns a job_id to poll with.
Request body
{
"org_id": "YOUR_ORG_ID",
"days": 7
}Response
{
"success": true,
"data": {
"job_id": "job_xyz789",
"status": "queued"
}
}/v1/ai/analysis/status/{job_id}Poll the progress of a running analysis job. Status will be queued → running → completed | failed.
Job ID from /run response
Organization ID
Response
{
"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
}
}/v1/ai/analysis/latestFetches the most recent completed analysis for the org — no job_id needed.
Organization ID
Response
{
"success": true,
"data": { ... }
}/v1/ai/decisionsLists AI recommendations. Filter by status, confidence, or campaign.
Organization ID
pending | approved | executed
low | medium | high
Filter to a specific campaign
Max results (1–500, default 100)
Pagination offset (default 0)
Response
{
"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.
| Plan | API calls/mo | AI runs/mo | Overage |
|---|---|---|---|
| Free | 50 | 3 | $0.02/call |
| API | 500 | 3 | $0.02/call |
| Starter | 2,000 | 50 | $0.015/call |
| Growth | 10,000 | 150 | $0.01/call |
Quota state is returned in every response header:
Errors
All errors return a consistent JSON envelope with a code and message.
{
"error": {
"code": "unauthorized",
"message": "Invalid API key."
}
}| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing or invalid API key |
| 403 | forbidden | Key lacks permission for this resource or scope |
| 404 | not_found | Resource does not exist |
| 422 | validation_error | Request body or params failed validation |
| 429 | rate_limited | Monthly quota exhausted — overage billing applies |
| 500 | internal_error | Something 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
https://api-dev.adbliss.io/v1/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:
{
"mcpServers": {
"adbliss": {
"url": "https://mcp.adbliss.io/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}Cursor
Add to your Cursor MCP settings (~/.cursor/mcp.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
- +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
- +Platform-specific analytics: /v1/analytics/{platform}/metrics/daily
- +Campaign write operations: budget and status mutations
- +org_id now accepted via X-Org-Id header
- +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