EcomBrain API v1

Developer Documentation

The EcomBrain API gives you programmatic access to the full intelligence layer — profit leak detection, autonomous fix execution, swarm agent status, and integration management.

Everything EcomBrain does through the dashboard, you can do through the API. Build custom dashboards, trigger recoveries from your own pipelines, or extend the Swarm with your own data.

Base URL

api.ecombrain.io/v1

Protocol

HTTPS only

Format

JSON

Authentication

All API requests require a Bearer token passed in the Authorization header. Generate your API key from the EcomBrain dashboard under Settings → API Keys.

bash

curl https://api.ecombrain.io/v1/store \
  -H "Authorization: Bearer eb_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

Key types

eb_live_

Live key

Executes real changes in your store. Never expose client-side.

eb_test_

Test key

Reads live data but all write operations are dry-run. Safe for development.

Quick Start

Connect your store and pull your first profit report in under 3 minutes.

1. Connect Shopify

bash

curl -X POST https://api.ecombrain.io/v1/integrations/connect \
  -H "Authorization: Bearer eb_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "shopify",
    "shop_domain": "your-store.myshopify.com",
    "access_token": "shpat_xxxxxxxxxxxx"
  }'

2. Trigger a full diagnostic

bash

curl -X POST https://api.ecombrain.io/v1/report/generate \
  -H "Authorization: Bearer eb_live_xxxx"

3. Retrieve detected leaks

bash

curl https://api.ecombrain.io/v1/leaks \
  -H "Authorization: Bearer eb_live_xxxx"

json

{
  "leaks": [
    {
      "id": "lk_01jqz7r8m4k3x",
      "type": "ad_attribution_gap",
      "platform": "meta",
      "estimated_loss_monthly": 2840.00,
      "currency": "USD",
      "confidence": 0.94,
      "status": "pending",
      "detected_at": "2026-03-27T08:14:22Z",
      "description": "Meta reports 247 conversions. Shopify records 189. Gap of 58 orders unaccounted."
    }
  ],
  "total_monthly_exposure": 4210.00,
  "currency": "USD"
}

Leaks

Leaks are specific, quantified profit gaps detected by the Swarm. Each leak contains an estimated monthly exposure and can be executed (fixed) autonomously.

GET

/v1/leaks

List all detected profit leaks for the connected store.

GET

/v1/leaks/{id}

Retrieve a single leak with full evidence trail.

POST

/v1/leaks/{id}/execute

Instruct EcomBrain to autonomously execute the fix.

POST

/v1/leaks/{id}/dismiss

Mark a leak as reviewed and dismissed.

Query parameters — GET /leaks

statusstring

Filter by status. One of pending, executing, resolved, dismissed.

platformstring

Filter by integration. e.g. meta, shopify, klaviyo.

min_exposurenumber

Minimum estimated monthly loss in store currency.

limitinteger

Number of results (default 20, max 100).

cursorstring

Pagination cursor from previous response.

Execute a fix — POST /leaks/{id}/execute

json

{
  "mode": "autonomous",       // "autonomous" | "simulation"
  "notify_webhook": true,     // ping your webhook on completion
  "notes": "Approved by ops team 2026-03-27"
}

json

{
  "leak_id": "lk_01jqz7r8m4k3x",
  "execution_id": "ex_01jr4m9k7z2p",
  "status": "queued",
  "estimated_completion": "2026-03-27T08:22:00Z"
}

Report

The profit diagnostic report is a full-stack analysis of your store's revenue, margin, and leak exposure. Reports are generated asynchronously — request generation, then poll or use a webhook.

POST

/v1/report/generate

Trigger a new full diagnostic. Returns a report ID immediately.

GET

/v1/report/{id}

Retrieve report status and results once complete.

GET

/v1/report/latest

Shortcut to retrieve the most recent completed report.

Report object

json

{
  "id": "rpt_01jqzb2n7x8k",
  "status": "complete",
  "generated_at": "2026-03-27T08:30:00Z",
  "period": {
    "from": "2026-02-25",
    "to": "2026-03-27"
  },
  "summary": {
    "gross_revenue": 184200.00,
    "true_net_margin": 28640.00,
    "total_leak_exposure": 4210.00,
    "leak_exposure_pct": 2.28,
    "leaks_detected": 7,
    "leaks_resolved": 2
  },
  "currency": "USD",
  "integrations_analyzed": ["shopify", "meta", "klaviyo", "google_ads"]
}

Integrations

Manage the platforms connected to EcomBrain. Adding an integration gives the Swarm read access to detect leaks, and optionally write access to execute fixes.

GET

/v1/integrations

List all connected integrations and their sync status.

POST

/v1/integrations/connect

Connect a new platform.

PATCH

/v1/integrations/{id}

Update credentials or permissions for an integration.

DELETE

/v1/integrations/{id}

Disconnect and revoke access for an integration.

Supported platform identifiers

shopifyshopify_plusmeta_adsgoogle_adsklaviyotiktok_adsstripegoogle_analytics_4triple_whalegorgiasrechargeshipstation

Connect a platform

json

// POST /v1/integrations/connect
{
  "platform": "klaviyo",
  "api_key": "pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "permissions": ["read", "write"]   // "read" | "write"
}

json

{
  "id": "int_01jr9z4m2k7p",
  "platform": "klaviyo",
  "status": "syncing",
  "permissions": ["read", "write"],
  "connected_at": "2026-03-27T09:00:00Z",
  "last_synced_at": null
}

Agents

The Swarm consists of specialized autonomous agents that run continuously. You can query their status, see what each agent is currently doing, and receive alerts via webhook when an agent flags a critical issue.

GET

/v1/agents

List all active swarm agents and their current task.

GET

/v1/agents/{id}/log

Retrieve the activity log for a specific agent.

Agent object

json

{
  "id": "agt_adspend_monitor",
  "name": "Ad Spend Monitor",
  "type": "surveillance",
  "status": "active",
  "current_task": "Reconciling Meta spend vs Shopify revenue for past 48h",
  "last_alert_at": "2026-03-26T22:18:04Z",
  "cycles_completed_today": 144,
  "integrations": ["meta_ads", "shopify"]
}

Webhooks

Register an endpoint to receive real-time push notifications when EcomBrain detects leaks, completes fixes, or generates a new report. We sign every request with a X-EcomBrain-Signature header.

POST

/v1/webhooks

GET

/v1/webhooks

List all registered webhooks.

DELETE

/v1/webhooks/{id}

Remove a webhook.

Supported events

leak.detected

A new profit leak has been identified by the Swarm.

fix.queued

A fix has been approved and queued for autonomous execution.

fix.executed

A fix has been successfully applied to your store.

fix.failed

An execution attempt failed. Contains the reason and retry plan.

agent.alert

A Swarm agent flagged a critical condition requiring attention.

report.ready

A new diagnostic report has been generated and is available.

integration.disconnected

An integration lost connection or credentials expired.

Verifying signatures

typescript

import crypto from 'crypto';

function verifyWebhook(payload: string, signature: string, secret: string) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

JavaScript / TypeScript SDK

bash

npm install @ecombrain/sdk

typescript

import { EcomBrain } from '@ecombrain/sdk';

const client = new EcomBrain({
  apiKey: process.env.ECOMBRAIN_API_KEY,
});

// Get all active leaks
const { leaks } = await client.leaks.list({ status: 'pending' });

// Execute a fix autonomously
const execution = await client.leaks.execute(leaks[0].id, {
  mode: 'autonomous',
});

// Generate and await a report
const report = await client.report.generate().then((r) =>
  client.report.awaitCompletion(r.id)
);

console.log(`True net margin: ${report.summary.true_net_margin}`);
console.log(`Leak exposure: ${report.summary.total_leak_exposure}`);

Next.js webhook handler

typescript

// app/api/ecombrain/route.ts
import { EcomBrain } from '@ecombrain/sdk';

const client = new EcomBrain({ apiKey: process.env.ECOMBRAIN_API_KEY });

export async function POST(req: Request) {
  const body = await req.text();
  const sig = req.headers.get('x-ecombrain-signature') ?? '';

  if (!client.webhooks.verify(body, sig)) {
    return Response.json({ error: 'Invalid signature' }, { status: 401 });
  }

  const event = JSON.parse(body);

  if (event.type === 'leak.detected') {
    console.log('New leak:', event.data.description);
    console.log('Exposure:', event.data.estimated_loss_monthly);
  }

  return Response.json({ received: true });
}

Python SDK

bash

pip install ecombrain

python

from ecombrain import EcomBrain

client = EcomBrain(api_key="eb_live_xxxx")

# List pending leaks
leaks = client.leaks.list(status="pending")

for leak in leaks:
    print(f"{'{'}leak.type{'}'}: ${'{'}leak.estimated_loss_monthly:.2f{'}'}/mo")
    print(f"  {'{'}leak.description{'}'}")

# Execute top leak
if leaks:
    execution = client.leaks.execute(leaks[0].id, mode="autonomous")
    print(f"Execution queued: {'{'}execution.execution_id{'}'}")

# Pull latest report
report = client.report.latest()
print(f"Gross revenue: ${'{'}report.summary.gross_revenue:,.2f{'}'}")
print(f"True margin:   ${'{'}report.summary.true_net_margin:,.2f{'}'}")
print(f"Leak exposure: ${'{'}report.summary.total_leak_exposure:,.2f{'}'}")

Rate Limits

Rate limits are applied per API key. Responses include X-RateLimit-Remaining and X-RateLimit-Reset headers on every request.

PlanRequests / minExecutions / day

Growth6050

Pro300500

Elite1,000Unlimited

When a rate limit is exceeded the API returns 429 Too Many Requests. Respect the Retry-After header.

Error Codes

All errors follow a consistent shape. The code field is machine-readable; message is human-readable.

json

{
  "error": {
    "code": "integration_not_connected",
    "message": "No Shopify integration found. Connect one via POST /v1/integrations/connect.",
    "request_id": "req_01jr4n7z8mk2"
  }
}

HTTPCode

400

invalid_request

Missing or malformed parameters.

401

unauthorized

API key missing, invalid, or revoked.

403

forbidden

Key lacks permission for this action (e.g. write on read-only key).

404

not_found

Resource does not exist.

409

already_connected

Integration is already active.

422

execution_unsafe

Simulation layer rejected the fix. No change made.

429

rate_limit_exceeded

Too many requests. Check Retry-After header.

500

internal_error

EcomBrain fault. Automatically reported. request_id helps support.

Need help integrating? Our engineering team is reachable directly.

dev@ecombrain.io