Core API Overview

Overview

The Core API is Analify's platform-mirror layer. Each connected integration — Meta, TikTok, Google Ads, Google Analytics, Shopify and Bosta — gets a /api/core/<platform>/* surface that is a 1:1, zero-customization mirror of that platform's own API: same paths, same parameters, same response shapes, returned raw. No filtering, no renaming, no derived fields, no client-side reshaping.

This is deliberately different from Analify's /api/analytics/* dashboard API, which is curated and pre-aggregated for the UI. Core API exists so any consumer — Analify's own services, the AI agent, or a third-party integration — can reach the full native capability of a connected platform, not just the slice the dashboard needed.

160 routes across 9 domains, all live.

📘

Rule of thumb: if a Core API response doesn't match the platform's

own docs, that's a bug. Business logic belongs in a layer above Core API.

How It Works

1. Auth is per-organization. Every Core API route resolves the calling organization's own stored credentials for that platform (via its existing integrations connection) — you never pass platform credentials directly.
2. Requests are scoped by organizationId. Every route requires ?organizationId=<uuid> (or the equivalent body field on write routes).
3. Params and bodies are the platform's own. A Bosta endpoint takes exactly the query params or body fields Bosta's API documents — Analify does not rename page to pageNumber or reshape a delivery payload into an Analify-flavored one.
4. Responses are raw. The platform's response is wrapped once in Analify's standard { success, data, timestamp } envelope — data is the platform's own JSON, untouched.

Response Envelope

Every Core API route returns Analify's standard envelope:

{
  "success": true,
  "data": { /* the platform's raw response, exactly as it returned it */ },
  "timestamp": "2026-08-16T21:06:11.292Z"
}

On error:

{
  "success": false,
  "error": {
    "message": "Bosta API error (400): Delivery not found.",
    "code": "BOSTA_API_ERROR",
    "details": { "errorCode": 1066 }
  },
  "timestamp": "2026-08-16T21:06:11.292Z"
}

The platform's own error message and error code are preserved in error.message / error.details — Core API does not translate or paraphrase them. Each platform page lists its own error codes and how its failures map onto HTTP statuses.

Reads, writes and token scopes

Much of the Core API mutates — creating a Shopify product, pausing a TikTok campaign, changing a Google Ads budget. Two rules follow:

• A read-scoped API token can only call GET/HEAD. Mutations need a token created with the write scope (Settings → API → Create token); a write token always carries read too.
• Permission scope is matched per PATH, not per method. One path often serves both a read and a write (/api/core/shopify/products is GET + POST), so each domain prefix carries the scope its most privileged verb needs — never the read tier, which would hand a read-only seat the ability to mutate.

⚠️

Writes hit live accounts immediately — no dry-run by default. Meta's create endpoints accept execution_options: ["validate_only"] to validate without creating — see the Meta page. Each platform page flags its destructive routes.

Money units — the one place piasters do NOT apply

Everywhere else in the Analify API, money is an integer in piasters (EGP × 100). Core API is the documented exception: because responses are the platform's own, money arrives in the platform's unit.

Convert on your side, and never assume ×100.

Freshness

Core API routes are never cached — every call hits the platform live. The short-TTL response cache that fronts Analify's high-volume aggregator routes does not apply here, so a Core API call consumes your organization's platform rate budget directly. Avoid tight polling loops, and note TikTok's app-wide 8 QPS ceiling in particular.

Daily quota

API access is on Max (5,000 calls per UTC day per organization, across all of its tokens) and Enterprise (unlimited). Call 5,001 returns 429 with code: "API_DAILY_LIMIT_EXCEEDED", error.meta = { limit, resetAt } and the Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. The count resets at 00:00 UTC. A call the API refuses for another reason (wrong organization, missing scope) does not use the quota. Separately, each token has a burst cap of 2,000 requests per 15 minutes (RATE_LIMIT_EXCEEDED).

Plan-gated breakdowns

Hour-of-day, placement and region breakdowns are part of advanced analytics (Pro and up) — the same rule the Analify dashboards apply. On a plan without it, these return 403 with code: "FEATURE_GATED", feature: "advanced_analytics", requiredPlan: "Pro", before the platform is called: Meta insights with breakdowns = publisher_platform, platform_position, region, dma or hourly_stats_*; TikTok reports with dimensions = stat_time_hour, province_id or placement; and Google Ads insights/hourly. Age and gender breakdowns are open on every plan. This applies to MCP clients (ChatGPT, Claude) too.

Platforms

Where to start

GET /api/core/integrations is the cheapest call in the API — a plain database read, no date range, no platform fan-out. It tells you which platforms an organization has connected and hands you the integration UUIDs the rest of the API takes, so it is the natural first request from any script or agent.

curl "https://analify.scalyax.ai/api/core/integrations?organizationId={organizationId}" \
  -H "Authorization: Bearer {anlfy_token}"

When NOT to use Core API

• You want a number a dashboard shows. Use the Analytics API. Platform-reported ROAS from /api/core/meta/…/insights is not Analify's nROAS after RTO — and for a COD store with returns, that difference is the whole point of the product.
• You want profit. Blended profit joins ads + Shopify + shipping + COGS; no single platform's raw payload can express it.
• You want cheap polling. Core routes are uncached and hit the platform every time.