{ "openapi": "3.1.0", "info": { "title": "Meerkats Public API (White-Label)", "version": "1.0.0", "description": "The Meerkats Public API lets an **agency** build its own white-labeled app on\ntop of Meerkats' ads-intelligence platform. Your end users sign up and log in\nthrough your app; your app reads cross-platform ad/revenue metrics and manages\nautomations for the workspaces you connected.\n\n## Authentication — two layers\n\nEvery call carries an **API key** that identifies your app. Data calls ALSO\ncarry an **end-user token** that identifies which of your users is asking.\n\n| Credential | Header | Identifies | Where you get it |\n|---|---|---|---|\n| **API key** | `X-API-Key: mk_live_…` | your agency app (allowed workspaces, scopes, branding) | Meerkats dashboard → API Keys |\n| **End-user token** | `Authorization: Bearer ` | the logged-in end user | returned by `/auth/signup` and `/auth/login` |\n| **Workspace** | `X-Workspace-Id: ` | which workspace to read/write | one of the key's allowed workspaces (see `/workspaces`) |\n\n### Typical flow\n1. `GET /branding` → render your white-label login screen (API key only).\n2. `POST /auth/signup` or `POST /auth/login` → get an end-user `token`.\n3. `GET /workspaces` → list the workspaces this key may access; let the user pick one.\n4. Call data endpoints with `X-API-Key` + `Authorization: Bearer ` +\n `X-Workspace-Id`. If you omit `X-Workspace-Id`, the key's first workspace is used.\n\n## Scopes\nAn API key has `read` and/or `write` scope. Read endpoints need `read`;\nmutating endpoints (create/update/delete automations) need `write`. `write`\nimplies `read`.\n\n## Rate limits\nRequests are limited per API key (default 120/min; configurable per key).\nExceeding the limit returns `429`.\n\n## Errors\nAll errors share one shape: `{ \"success\": false, \"error\": \"message\",\n\"statusCode\": 400, \"timestamp\": \"…\" }`.\n" }, "servers": [ { "url": "https://partners.meerkats.ai/api/public/v1", "description": "Production" }, { "url": "http://localhost:3000/api/public/v1", "description": "Local development" } ], "tags": [ { "name": "Auth", "description": "White-label end-user signup / login / password reset. API key only (no end-user token yet)." }, { "name": "Branding", "description": "Fetch your white-label config to render the login UI." }, { "name": "Workspaces", "description": "The workspaces this API key may access." }, { "name": "Metrics", "description": "Cross-platform reports and explore-graph queries over the semantic layer." }, { "name": "Automations", "description": "Ad-automation rules — \"if metric crosses a threshold, take an action\". CRUD." }, { "name": "Approvals", "description": "The interrupt inbox — staged automation actions awaiting a human approve/reject." }, { "name": "Agents", "description": "Automation agents (scheduled small agents) — list, run, enable/disable, and run history." }, { "name": "Sync", "description": "When the workspace's platform data was last synced, and the per-run sync history." } ], "security": [ { "ApiKeyAuth": [], "EndUserAuth": [] } ], "paths": { "/branding": { "get": { "tags": [ "Branding" ], "summary": "Get white-label branding for the login screen", "description": "Returns the app name, logo, colors and tagline configured for this API\nkey, so you can render a branded login page before any user exists.\nRequires ONLY the API key.\n", "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Branding config", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "$ref": "#/components/schemas/Branding" } } }, "example": { "success": true, "data": { "app_name": "Colors Queen Insights", "tagline": "Your Flipkart command center", "logo_url": "https://cdn.example.com/logo.png", "primary_color": "#7c3aed", "support_email": "help@colorsqueen.com" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/signup": { "post": { "tags": [ "Auth" ], "summary": "Register a new end user", "description": "Creates an end user scoped to your agency and returns a session token. API key only.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string", "minLength": 8 }, "full_name": { "type": "string" } } }, "example": { "email": "jane@brand.com", "password": "s3cure-pass", "full_name": "Jane Doe" } } } }, "responses": { "201": { "description": "Account created; session token returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/auth/login": { "post": { "tags": [ "Auth" ], "summary": "Log an end user in", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" } } }, "example": { "email": "jane@brand.com", "password": "s3cure-pass" } } } }, "responses": { "200": { "description": "Authenticated; session token returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthSuccess" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/auth/forgot-password": { "post": { "tags": [ "Auth" ], "summary": "Request a password-reset email", "description": "Always returns success (it never reveals whether the email exists). If the\nuser exists, a branded reset email is sent with a link to your configured\n`auth_redirect_base_url` carrying a one-hour, single-use `?token=`.\n", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" } } }, "example": { "email": "jane@brand.com" } } } }, "responses": { "200": { "description": "Accepted (whether or not the email exists)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } } } }, "/auth/reset-password": { "post": { "tags": [ "Auth" ], "summary": "Complete a password reset", "description": "Consumes the single-use token from the reset email and sets a new password.", "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token", "password" ], "properties": { "token": { "type": "string", "description": "The raw token from the reset email link" }, "password": { "type": "string", "minLength": 8 } } } } } }, "responses": { "200": { "description": "Password updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } } } }, "/auth/me": { "get": { "tags": [ "Auth" ], "summary": "Get the current end user", "description": "Requires API key + end-user token.", "responses": { "200": { "description": "The authenticated end user", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/EndUser" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/workspaces": { "get": { "tags": [ "Workspaces" ], "summary": "List the workspaces this key may access (lite)", "description": "Returns the minimal `{id, name, is_default}` for each workspace assigned\nto this API key. Use an `id` as the `X-Workspace-Id` header on data calls.\n", "responses": { "200": { "description": "Permitted workspaces", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkspaceLite" } } } }, "example": { "success": true, "data": [ { "id": "3f2a…", "name": "Colors Queen — Flipkart", "is_default": true }, { "id": "9b1c…", "name": "Colors Queen — Amazon", "is_default": false } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/metrics/catalog": { "get": { "tags": [ "Metrics" ], "summary": "Discover available metrics and dimensions", "description": "Returns the metric inventory for this workspace's vertical, each metric\nmapped to the dimensions it can be grouped by. Use this to know which\n`metrics` and `groupBy` values `/metrics/query` will accept.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Metric catalog", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "vertical": { "type": [ "string", "null" ], "example": "ecommerce" }, "metrics": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "metric name → list of groupable dimension names" } } }, "example": { "success": true, "vertical": "ecommerce", "metrics": { "total_revenue": [ "order__channel", "metric_time__day" ], "roas": [ "ad_row__platform", "metric_time__week" ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "502": { "$ref": "#/components/responses/UpstreamUnavailable" } } } }, "/metrics/query": { "post": { "tags": [ "Metrics" ], "summary": "Run a cross-platform report / explore-graph query", "description": "The single flexible reporting endpoint. Pick one or more `metrics`,\noptionally `groupBy` dimensions, a `dateRange` (or custom `startDate`/\n`endDate`), and ordering/limit. Returns tabular rows you can chart or\ntable directly. `workspace_id` is taken from the auth context — never\nthe body.\n\nMetric and dimension names are validated against the catalog; unknown\nnames return `400`. Call `/metrics/catalog` first to discover valid names.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricQuery" }, "examples": { "revenueByChannel": { "summary": "Revenue + ROAS by channel, last 30 days", "value": { "metrics": [ "total_revenue", "roas" ], "groupBy": [ "order__channel" ], "dateRange": "last_30_days", "orderBy": [ "-total_revenue" ], "limit": 20 } }, "dailyTrend": { "summary": "Daily ad spend trend this month", "value": { "metrics": [ "total_ad_spend" ], "groupBy": [ "metric_time__day" ], "dateRange": "this_month" } } } } } }, "responses": { "200": { "description": "Query result rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricQueryResult" }, "example": { "success": true, "metrics": [ "total_revenue", "roas" ], "group_by": [ "order__channel" ], "row_count": 2, "rows": [ { "order__channel": "Flipkart", "total_revenue": 128400.5, "roas": 3.8 }, { "order__channel": "Amazon", "total_revenue": 94200, "roas": 2.9 } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/automations": { "get": { "tags": [ "Automations" ], "summary": "List automation rules", "description": "Requires `read` scope. Rules are ordered enabled-first, newest-first.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "The workspace's automation rules", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "rules": { "type": "array", "items": { "$ref": "#/components/schemas/AutomationRule" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Automations" ], "summary": "Create an automation rule", "description": "Requires `write` scope.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRuleInput" }, "example": { "name": "Pause wasteful campaigns", "platform": "google", "metric": "real_roas", "comparator": "lt", "threshold": 1.5, "window_days": 4, "action": "pause_campaign", "mode": "suggest" } } } }, "responses": { "201": { "description": "Rule created", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "rule": { "$ref": "#/components/schemas/AutomationRule" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/automations/{id}": { "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "patch": { "tags": [ "Automations" ], "summary": "Update an automation rule", "description": "Requires `write` scope. Send the full rule body (same shape as create).", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutomationRuleInput" } } } }, "responses": { "200": { "description": "Rule updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "rule": { "$ref": "#/components/schemas/AutomationRule" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Automations" ], "summary": "Delete an automation rule", "description": "Requires `write` scope.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/automations/{id}/toggle": { "post": { "tags": [ "Automations" ], "summary": "Enable or disable an automation rule", "description": "Requires `write` scope.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/WorkspaceHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "example": { "enabled": false } } } }, "responses": { "200": { "description": "Toggled", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "rule": { "$ref": "#/components/schemas/AutomationRule" } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/{id}/runs": { "get": { "tags": [ "Automations" ], "summary": "Get a rule's evaluation + fire history", "description": "Requires `read` scope. Returns the last evaluation snapshot plus recent staged/fired actions and the audit trail.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Rule history", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "last_evaluated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_fired_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_eval": { "type": [ "object", "null" ] }, "runs": { "type": "array", "items": { "type": "object" } }, "activity": { "type": "array", "items": { "type": "object" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/metrics/product-revenue": { "get": { "tags": [ "Metrics" ], "summary": "Product-grain revenue for a platform", "description": "Convenience wrapper over /metrics/query that picks the right product\nrevenue metric + product-name dimension per platform, sorted by revenue.\n(Product revenue is per-platform — there's no single metric.) Requires `read`.\n", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "name": "platform", "in": "query", "schema": { "type": "string", "enum": [ "shopify", "flipkart", "amazon" ], "default": "shopify" } }, { "name": "dateRange", "in": "query", "schema": { "type": "string", "default": "last_30_days" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50 } } ], "responses": { "200": { "description": "Product revenue rows (metric + product name per row)", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "platform": { "type": "string" }, "metric": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/workspaces/sync-status": { "get": { "tags": [ "Sync" ], "summary": "When the workspace's data was last synced", "description": "Returns the last sync timestamp for the current workspace. Requires `read`.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Last-sync summary", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid" }, "last_synced_at": { "type": [ "string", "null" ], "format": "date-time" } } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/workspaces/sync-history": { "get": { "tags": [ "Sync" ], "summary": "Per-run sync history", "description": "The durable sync run log for the current workspace, newest first. Requires `read`.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100 } } ], "responses": { "200": { "description": "Sync run history", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/automations/staged": { "get": { "tags": [ "Approvals" ], "summary": "List staged actions awaiting approval", "description": "The interrupt inbox — automation actions staged for a human decision. Requires `read`.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "name": "status", "in": "query", "schema": { "type": "string", "default": "pending" } } ], "responses": { "200": { "description": "Staged action cards", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "items": { "type": "array", "items": { "type": "object", "additionalProperties": true } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/automations/staged/{id}/approve": { "post": { "tags": [ "Approvals" ], "summary": "Approve a staged action (executes it)", "description": "Approves and runs the staged action. Requires `write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Approved and executed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/automations/staged/{id}/reject": { "post": { "tags": [ "Approvals" ], "summary": "Reject a staged action (nothing runs)", "description": "Rejects the staged action. Requires `write`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Rejected" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents": { "get": { "tags": [ "Agents" ], "summary": "List automation agents", "description": "The workspace's scheduled small agents (system + custom). Requires `read`.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Agents", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "agents": { "type": "array", "items": { "type": "object" } } } } } } }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agents/run-history": { "get": { "tags": [ "Agents" ], "summary": "Agent run history (all agents)", "description": "Recent runs across the workspace's agents. Requires `read`.", "parameters": [ { "$ref": "#/components/parameters/WorkspaceHeader" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 25 } } ], "responses": { "200": { "description": "Run history" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agents/{agentKey}": { "get": { "tags": [ "Agents" ], "summary": "Get one agent's detail", "parameters": [ { "name": "agentKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Agent detail" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/agents/{agentKey}/run": { "post": { "tags": [ "Agents" ], "summary": "Run an agent now", "description": "Triggers an immediate run (LLM work; costs apply). Requires `write`.", "parameters": [ { "name": "agentKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Run started" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agents/{agentKey}/enable": { "post": { "tags": [ "Agents" ], "summary": "Enable an agent", "parameters": [ { "name": "agentKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Enabled" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/agents/{agentKey}/disable": { "post": { "tags": [ "Agents" ], "summary": "Disable an agent", "parameters": [ { "name": "agentKey", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/WorkspaceHeader" } ], "responses": { "200": { "description": "Disabled" }, "403": { "$ref": "#/components/responses/Forbidden" } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Your agency app key, e.g. `mk_live_…`. Required on every call." }, "EndUserAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "The end-user session token from /auth/login or /auth/signup." } }, "parameters": { "WorkspaceHeader": { "name": "X-Workspace-Id", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Which workspace to operate on. Must be one of the key's allowed\nworkspaces (see `GET /workspaces`). If omitted, the key's first\nworkspace is used. May also be passed as a `?workspace_id=` query param.\n" } }, "schemas": { "Branding": { "type": "object", "properties": { "app_name": { "type": [ "string", "null" ] }, "tagline": { "type": [ "string", "null" ] }, "logo_url": { "type": [ "string", "null" ] }, "primary_color": { "type": [ "string", "null" ] }, "support_email": { "type": [ "string", "null" ] } } }, "EndUser": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "full_name": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "AuthSuccess": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "data": { "type": "object", "properties": { "token": { "type": "string", "description": "End-user session JWT. Send as `Authorization: Bearer `." }, "user": { "$ref": "#/components/schemas/EndUser" } } } } }, "WorkspaceLite": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "is_default": { "type": "boolean" } } }, "MetricQuery": { "type": "object", "required": [ "metrics" ], "properties": { "metrics": { "type": "array", "minItems": 1, "items": { "type": "string" }, "description": "One or more metric names from /metrics/catalog." }, "groupBy": { "type": "array", "items": { "type": "string" }, "description": "Dimension names to group by." }, "orderBy": { "type": "array", "items": { "type": "string" }, "description": "Sort keys; prefix with '-' for DESC, e.g. '-total_revenue'." }, "limit": { "type": "integer", "minimum": 1 }, "dateRange": { "type": "string", "description": "Named preset: today, yesterday, last_7_days, last_30_days,\nlast_90_days, this_week, last_week, this_month, last_month,\nthis_year, all — or a rolling window like `last_N_days`.\n", "example": "last_30_days" }, "startDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Custom range start (overrides dateRange)." }, "endDate": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "description": "Custom range end." } } }, "MetricQueryResult": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "metrics": { "type": "array", "items": { "type": "string" } }, "group_by": { "type": "array", "items": { "type": "string" } }, "row_count": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "One object per row; keys are the requested metrics + group_by dimensions." } } }, "AutomationRuleInput": { "type": "object", "required": [ "name", "metric", "comparator", "threshold", "action" ], "properties": { "name": { "type": "string", "maxLength": 200 }, "description": { "type": "string", "maxLength": 500 }, "enabled": { "type": "boolean", "default": true }, "platform": { "type": [ "string", "null" ], "enum": [ "google", "meta", null ], "description": "Ad platform; null = any." }, "target_campaign": { "type": [ "string", "null" ], "description": "Campaign name to match; null = all campaigns." }, "metric": { "type": "string", "enum": [ "real_roas", "campaign_reported_roas", "roas_gap", "campaign_spend", "campaign_attributed_revenue", "campaign_attributed_orders", "campaign_impressions", "campaign_cpm", "roas", "cac" ] }, "comparator": { "type": "string", "enum": [ "lt", "lte", "gt", "gte", "eq" ] }, "threshold": { "type": "number" }, "window_days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 4 }, "action": { "type": "string", "enum": [ "pause_campaign", "enable_campaign", "set_budget_multiplier", "set_budget_absolute" ] }, "action_value": { "type": [ "number", "null" ], "description": "Required for set_budget_* actions (multiplier or absolute amount)." }, "mode": { "type": "string", "enum": [ "auto", "suggest" ], "default": "suggest", "description": "auto = execute on match; suggest = stage for approval." }, "schedule_cron": { "type": "string", "default": "*/30 * * * *", "description": "5-field cron for when the rule is evaluated." }, "cooldown_hours": { "type": "integer", "minimum": 0, "default": 24 } } }, "AutomationRule": { "allOf": [ { "$ref": "#/components/schemas/AutomationRuleInput" }, { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "last_evaluated_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_fired_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "Error": { "type": "object", "properties": { "success": { "type": "boolean", "const": false }, "error": { "type": "string" }, "statusCode": { "type": "integer" }, "timestamp": { "type": "string", "format": "date-time" } }, "example": { "success": false, "error": "Requested workspace is not permitted for this API key", "statusCode": 403, "timestamp": "2026-09-22T10:00:00.000Z" } } }, "responses": { "BadRequest": { "description": "Invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing/invalid API key or end-user token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Scope or workspace not permitted for this key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "Already exists (e.g. duplicate email)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UpstreamUnavailable": { "description": "The metrics service is temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }