{ "openapi": "3.1.0", "info": { "title": "Techrace Integration API", "version": "0.241.0", "description": "B2B social, advertising and email integration infrastructure with customer-bound REST, SDK and MCP contracts. Never expose project keys in customer browsers. Bounded native reads preserve provider metrics and missing values. Confirmed actions use durable idempotency, current authority checks, native ownership checks and operation receipts; unknown writes require investigation rather than blind replay. Supports the explicitly listed Meta, Google Ads, social inbox, analytics and Gmail/Outlook mailbox workflows. Created campaigns and ads remain paused. Receipts do not prove delivery, native review or complete snapshots. Live permissions, provider compatibility and hosted capacity require separate verification; unsupported native features are not implied." }, "servers": [ { "url": "/" } ], "security": [ { "projectKey": [] } ], "paths": { "/api/v1/projects/{project_id}/customers": { "get": { "summary": "List downstream customers", "operationId": "get__api_v1_projects_project_id_customers", "x-required-scope": "customers:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "external_id", "in": "query", "schema": { "type": "string", "maxLength": 200 } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "post": { "summary": "Create or retrieve by project-unique external ID", "operationId": "post__api_v1_projects_project_id_customers", "x-required-scope": "customers:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "customer": { "$ref": "#/components/schemas/Customer" } }, "required": [ "customer" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string", "minLength": 1, "maxLength": 200 }, "name": { "type": "string", "minLength": 1, "maxLength": 160 } }, "required": [ "external_id", "name" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/customers/{customer_id}": { "delete": { "summary": "Freeze customer operations and request resumable bounded erasure", "operationId": "delete__api_v1_projects_project_id_customers_customer_id_", "x-required-scope": "customers:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "purging", "media_pending", "complete", "failed" ] }, "phase": { "type": "integer", "minimum": 1 }, "deleted_rows": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "available_at": { "type": "string" }, "completed_at": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "customer_id", "status", "phase", "deleted_rows", "created_at", "updated_at", "available_at", "completed_at", "error_code" ], "additionalProperties": false }, "notice": { "type": "string" } }, "required": [ "request", "notice" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "confirmation" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/customer-deletions/{request_id}": { "get": { "summary": "Inspect customer erasure progress; native content/grants and backups are separate", "operationId": "get__api_v1_projects_project_id_customer_deletions_request_id_", "x-required-scope": "customers:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "purging", "media_pending", "complete", "failed" ] }, "phase": { "type": "integer", "minimum": 1 }, "deleted_rows": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "available_at": { "type": "string" }, "completed_at": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "customer_id", "status", "phase", "deleted_rows", "created_at", "updated_at", "available_at", "completed_at", "error_code" ], "additionalProperties": false } }, "required": [ "request" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/customer-deletions/{request_id}/retry": { "post": { "summary": "Resume an already authorized failed customer erasure after repair", "operationId": "post__api_v1_projects_project_id_customer_deletions_request_id_retry", "x-required-scope": "customers:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "purging", "media_pending", "complete", "failed" ] }, "phase": { "type": "integer", "minimum": 1 }, "deleted_rows": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string" }, "updated_at": { "type": "string" }, "available_at": { "type": "string" }, "completed_at": { "type": [ "string", "null" ] }, "error_code": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "customer_id", "status", "phase", "deleted_rows", "created_at", "updated_at", "available_at", "completed_at", "error_code" ], "additionalProperties": false } }, "required": [ "request" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_resume": { "const": true } }, "required": [ "confirm_resume" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/settings": { "get": { "summary": "Read registered return URLs", "operationId": "get__api_v1_projects_project_id_settings", "x-required-scope": "connections:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "redirect_urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "redirect_urls" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "put": { "summary": "Register exact HTTPS return URLs; console session and admin role required", "operationId": "put__api_v1_projects_project_id_settings", "x-required-scope": "connections:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "settings": { "type": "object", "properties": { "redirect_urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "redirect_urls" ], "additionalProperties": false } }, "required": [ "settings" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_urls": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } }, "required": [ "redirect_urls" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/connect-sessions": { "post": { "summary": "Issue a customer-bound hosted connection link, valid for 15 minutes", "operationId": "post__api_v1_projects_project_id_connect_sessions", "x-required-scope": "connections:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "expires_at" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "return_url": { "type": "string", "format": "uri" }, "google_ads_manager_id": { "type": "string", "pattern": "^[1-9][0-9]{9}$", "description": "Google Ads only. Directly accessible manager; fresh OAuth and bounded native hierarchy verification required. Omit for direct account discovery." }, "google_ads_customer_id": { "type": "string", "pattern": "^[1-9][0-9]{9}$", "description": "Requires google_ads_manager_id and must differ. Limit discovery to this enabled non-manager descendant; each selected client is one ordinary billable connection. No native linking or spend approval." }, "shared_mailbox_id": { "type": "string", "format": "uuid", "description": "Outlook only. Lowercase Entra object ID of a delegated/shared mailbox. Fresh delegated .Shared consent and Inbox access required; polling only. Omit for own mailbox." } }, "required": [ "customer_id", "provider", "return_url" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/connections": { "get": { "summary": "List credential-free customer connections", "operationId": "get__api_v1_projects_project_id_connections", "x-required-scope": "connections:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectionPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/customers/{customer_id}/connections/{connection_id}": { "delete": { "summary": "Disconnect and cancel unstarted jobs; active leases block removal", "operationId": "delete__api_v1_projects_project_id_customers_customer_id_connections_connection_id_", "x-required-scope": "connections:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "disconnected": { "const": true } }, "required": [ "disconnected" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/executions": { "post": { "summary": "Queue one provider action atomically with quota and idempotency", "operationId": "post__api_v1_projects_project_id_executions", "x-required-scope": "executions:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 120 } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } }, "required": [ "id" ], "additionalProperties": false }, "replay": { "type": "boolean" } }, "required": [ "execution" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionRequest" } } } } }, "get": { "summary": "List execution results", "operationId": "get__api_v1_projects_project_id_executions", "x-required-scope": "executions:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/executions/{execution_id}": { "get": { "summary": "Read an execution and its actual provider receipt", "operationId": "get__api_v1_projects_project_id_executions_execution_id_", "x-required-scope": "executions:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "execution_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "execution": { "$ref": "#/components/schemas/Execution" } }, "required": [ "execution" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/events": { "get": { "summary": "List durable customer events", "operationId": "get__api_v1_projects_project_id_events", "x-required-scope": "events:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "customer_id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/webhooks": { "get": { "summary": "List webhook endpoints without signing secrets", "operationId": "get__api_v1_projects_project_id_webhooks", "x-required-scope": "webhooks:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "post": { "summary": "Register an operator-approved destination; reveal secret once", "operationId": "post__api_v1_projects_project_id_webhooks", "x-required-scope": "webhooks:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "endpoint": { "$ref": "#/components/schemas/Endpoint" }, "signing_secret": { "type": "string" } }, "required": [ "endpoint", "signing_secret" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } }, "required": [ "url" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/webhooks/{endpoint_id}": { "delete": { "summary": "Disable future delivery attempts for this endpoint", "operationId": "delete__api_v1_projects_project_id_webhooks_endpoint_id_", "x-required-scope": "webhooks:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "endpoint_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "disabled": { "const": true } }, "required": [ "disabled" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/webhook-deliveries": { "get": { "summary": "Inspect delivery attempts and outcomes", "operationId": "get__api_v1_projects_project_id_webhook_deliveries", "x-required-scope": "webhooks:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDeliveryPage" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/usage": { "get": { "summary": "Read operational counters and project allowances", "operationId": "get__api_v1_projects_project_id_usage", "x-required-scope": "usage:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/billing": { "get": { "summary": "Read the one-plan account count, monthly price and synchronization state", "operationId": "get__api_v1_projects_project_id_billing", "x-required-scope": "usage:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BillingResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/workspaces/{project_id}/billing/checkout": { "post": { "summary": "Enable monthly account billing; interactive owner consent only", "operationId": "post__api_v1_workspaces_project_id_billing_checkout", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "accept_pricing_version": { "const": "2026-09-30" } }, "required": [ "accept_pricing_version" ], "additionalProperties": false } } } } } }, "/api/v1/workspaces/{project_id}/billing/portal": { "post": { "summary": "Open payment management; interactive owner only", "operationId": "post__api_v1_workspaces_project_id_billing_portal", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/projects/{project_id}/inbox/query": { "post": { "summary": "Discover owned published Facebook Page posts with facebook_posts (no post selector), then read owned Facebook Page post comments/replies with explicit facebook_post_id and, for replies, facebook_comment_id. Current Page/post/object/parent binding and read-user-content consent required; optional capability/count values remain null. Also read Page Messenger/Instagram messaging and Instagram engagement, or YouTube owned-channel threads/replies with explicit force-ssl consent. Bounded live pages, bodies opt-in; held/spam thread filters may match replies. Separate reply pages required.", "operationId": "post__api_v1_projects_project_id_inbox_query", "x-required-scope": "inbox:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "enum": [ "facebook", "instagram", "youtube" ] }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "resource": { "enum": [ "conversations", "messages", "media", "comments", "replies", "youtube_threads", "youtube_replies", "facebook_posts", "facebook_comments", "facebook_replies" ] }, "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "updated_at": { "type": "string", "format": "date-time" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "name": { "type": [ "string", "null" ] }, "participant_reference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Facebook Page-scoped pseudonymous correlation for explicitly consented read-watermark events. Not an authorization or individual read proof." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "app_is_thread_owner": { "type": [ "boolean", "null" ] } }, "required": [ "id", "updated_at", "participants" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "created_at": { "type": "string", "format": "date-time" }, "from": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "name": { "type": [ "string", "null" ] }, "participant_reference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Facebook Page-scoped pseudonymous correlation for explicitly consented read-watermark events. Not an authorization or individual read proof." } }, "required": [ "id", "name" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "name": { "type": [ "string", "null" ] }, "participant_reference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Facebook Page-scoped pseudonymous correlation for explicitly consented read-watermark events. Not an authorization or individual read proof." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "from", "to" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "media_type": { "type": "string" }, "media_product_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "caption": { "type": [ "string", "null" ] } }, "required": [ "id", "media_type", "media_product_type", "created_at" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "media_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "parent_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "hidden": { "type": "boolean" }, "from": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "username": { "type": [ "string", "null" ] } }, "required": [ "id", "username" ], "additionalProperties": false }, { "type": "null" } ] }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "media_id", "parent_id", "created_at", "hidden", "from" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "created_at": { "type": "string", "format": "date-time" }, "published": { "const": true }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "page_id", "created_at", "published" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "post_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "parent_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "from": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "name": { "type": [ "string", "null" ] }, "participant_reference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Facebook Page-scoped pseudonymous correlation for explicitly consented read-watermark events. Not an authorization or individual read proof." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "hidden": { "type": [ "boolean", "null" ] }, "private": { "type": [ "boolean", "null" ] }, "revision": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]{43}$" }, "can_reply": { "type": [ "boolean", "null" ] }, "can_hide": { "type": [ "boolean", "null" ] }, "can_remove": { "type": [ "boolean", "null" ] }, "reply_count": { "type": [ "string", "null" ] }, "like_count": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "post_id", "parent_id", "created_at", "from", "hidden", "private", "revision", "can_reply", "can_hide", "can_remove", "reply_count", "like_count" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "channel_id": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, "parent_id": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, { "type": "null" } ] }, "author": { "type": "object", "properties": { "channel_id": { "anyOf": [ { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, { "type": "null" } ] }, "display_name": { "type": [ "string", "null" ] } }, "required": [ "channel_id", "display_name" ], "additionalProperties": false }, "like_count": { "type": "string", "pattern": "^[0-9]+$" }, "moderation_status": { "enum": [ "published", "heldForReview", "likelySpam", "rejected", null ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "etag", "channel_id", "parent_id", "author", "like_count", "moderation_status", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "channel_id": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, "video_id": { "type": [ "string", "null" ] }, "can_reply": { "type": "boolean" }, "is_public": { "type": "boolean" }, "reply_count": { "type": "string", "pattern": "^[0-9]+$" }, "comment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "channel_id": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, "parent_id": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, { "type": "null" } ] }, "author": { "type": "object", "properties": { "channel_id": { "anyOf": [ { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, { "type": "null" } ] }, "display_name": { "type": [ "string", "null" ] } }, "required": [ "channel_id", "display_name" ], "additionalProperties": false }, "like_count": { "type": "string", "pattern": "^[0-9]+$" }, "moderation_status": { "enum": [ "published", "heldForReview", "likelySpam", "rejected", null ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "etag", "channel_id", "parent_id", "author", "like_count", "moderation_status", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "id", "etag", "channel_id", "video_id", "can_reply", "is_public", "reply_count", "comment" ], "additionalProperties": false } ] } }, "next_cursor": { "type": [ "string", "null" ] }, "complete_snapshot": { "const": false }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "provider", "customer_id", "connection_id", "resource", "data", "next_cursor", "complete_snapshot", "read_only", "content_is_untrusted", "fetched_at", "limitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "resource": { "enum": [ "conversations", "messages", "media", "comments", "replies", "youtube_threads", "youtube_replies", "facebook_posts", "facebook_comments", "facebook_replies" ] }, "facebook_post_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "facebook_comment_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "youtube_video_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{11}$" }, "youtube_parent_id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "youtube_moderation": { "enum": [ "published", "heldForReview", "likelySpam" ] }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "media_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "comment_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "include_body": { "type": "boolean", "default": false }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 14000 } }, "required": [ "customer_id", "connection_id", "resource" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "resource": { "enum": [ "facebook_comments", "facebook_replies" ] } } }, "then": { "required": [ "facebook_post_id" ] }, "else": { "not": { "required": [ "facebook_post_id" ] } } }, { "if": { "properties": { "resource": { "const": "facebook_replies" } } }, "then": { "required": [ "facebook_comment_id" ] }, "else": { "not": { "required": [ "facebook_comment_id" ] } } }, { "if": { "properties": { "resource": { "const": "youtube_replies" } } }, "then": { "required": [ "youtube_parent_id" ] }, "else": { "not": { "required": [ "youtube_parent_id" ] } } }, { "if": { "properties": { "resource": { "const": "youtube_threads" } } }, "else": { "not": { "anyOf": [ { "required": [ "youtube_video_id" ] }, { "required": [ "youtube_moderation" ] } ] } } }, { "if": { "properties": { "resource": { "const": "messages" } } }, "then": { "required": [ "conversation_id" ] }, "else": { "not": { "required": [ "conversation_id" ] } } }, { "if": { "properties": { "resource": { "enum": [ "comments", "replies" ] } } }, "then": { "required": [ "media_id" ] }, "else": { "not": { "required": [ "media_id" ] } } }, { "if": { "properties": { "resource": { "const": "replies" } } }, "then": { "required": [ "comment_id" ] }, "else": { "not": { "required": [ "comment_id" ] } } }, { "if": { "properties": { "resource": { "const": "conversations" } } }, "then": { "properties": { "include_body": { "const": false } } } } ] } } } } } }, "/api/v1/projects/{project_id}/inbox/operations": { "post": { "summary": "Queue reply_facebook_comment, set_facebook_comment_hidden or delete_facebook_comment with explicit expected_revision from a body-opt-in read, Page/post/comment and optional parent binding, native capability and current write consent. Separate inbox read/write plus native pages_manage_engagement required. Delete requires confirm_delete. All connection comment actions share ordered ambiguity blocking; no native CAS or automatic uncertain replay. Also queue Facebook or Instagram reply_image with a customer-owned completed PNG/JPEG media_id<=8MiB, expected_sha256 and confirm_share_media:true. Requires additional media:write; uses the same inbound anchor/window and conversation lane, one-hour generation-bound media URL and61-minute native-start pin. Instagram requires expected_provider=instagram; omitted expectation retains Facebook semantics and legacy idempotency. A mismatched connection is rejected before admission and native work. No caller-supplied URL. Queue mark_conversation_seen with confirm_mark_seen:true; expected_provider:instagram explicitly selects Instagram Login while omitted expectation preserves Facebook intent and legacy idempotency and a recent anchor_message_id. This marks the recipient conversation, potentially including later messages; anchor is not a read watermark. Shares the reply ordering lane, no automatic replay of uncertainty. Also queue owned-channel YouTube replies/moderation/rejection/own deletion with expected_etag and explicit confirmation; channel-wide ordering, no author bans, preflight is not native CAS. Also queue Instagram enable_message_push or Facebook enable_facebook_message_push (explicit field replacement; Facebook also accepts [messages,message_deliveries] for exact-ID inbox.message_delivered events with separately labeled provider watermark and observation time, without read inference. Facebook additionally supports explicit message_reads with or without message_deliveries, after messages in canonical order, emitting inbox.read_watermark with a Page-scoped participant_reference also returned by owned inbox participant reads, native provider_watermark_at and local observed_at. It never asserts individual messages read; Instagram also accepts [messages,messaging_seen] for signed inbox.message_read events correlated to successful Techrace sends; no unread inference; outbound mark-seen requires its separate explicit action), Page Messenger or Instagram reply_text, or Instagram reply_comment, set_comment_hidden or delete_comment on owned media. Instagram replies require a visible top-level comment; delete requires confirm_delete. Instagram work orders per media. in_reply_to is an inbound window anchor, not a quoted reply. Max250Facebook/20Instagram messages searched; Instagram text<=1000UTF8bytes;24hour window less30seconds;expires15minutes.", "operationId": "post__api_v1_projects_project_id_inbox_operations", "x-required-scope": "inbox:read and inbox:write;owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9_.:-]+$" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "replayed": { "type": "boolean" } }, "required": [ "id", "status", "replayed" ], "additionalProperties": false }, "delivery_confirmed": { "const": false } }, "required": [ "operation", "delivery_confirmed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "facebook_post_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "facebook_comment_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "action": { "const": "reply_facebook_comment" }, "text": { "type": "string", "minLength": 1, "maxLength": 2000, "pattern": "^(?!.*@\\[)[\\s\\S]+$" } }, "required": [ "customer_id", "connection_id", "facebook_post_id", "facebook_comment_id", "expected_revision", "action", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "facebook_post_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "facebook_comment_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "facebook_parent_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "action": { "const": "set_facebook_comment_hidden" }, "hidden": { "type": "boolean" } }, "required": [ "customer_id", "connection_id", "facebook_post_id", "facebook_comment_id", "expected_revision", "action", "hidden" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "facebook_post_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "facebook_comment_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "facebook_parent_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "action": { "const": "delete_facebook_comment" }, "confirm_delete": { "const": true } }, "required": [ "customer_id", "connection_id", "facebook_post_id", "facebook_comment_id", "expected_revision", "action", "confirm_delete" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "reply_image" }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "recipient_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "in_reply_to": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "media_id": { "type": "string", "format": "uuid" }, "expected_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "confirm_share_media": { "const": true }, "expected_provider": { "enum": [ "facebook", "instagram" ], "description": "Must be instagram for Instagram replies. Omission retains Facebook behavior without injecting a field into idempotency payloads." } }, "required": [ "customer_id", "connection_id", "action", "conversation_id", "recipient_id", "in_reply_to", "media_id", "expected_sha256", "confirm_share_media" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "mark_conversation_seen" }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "recipient_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "anchor_message_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "confirm_mark_seen": { "const": true }, "expected_provider": { "enum": [ "facebook", "instagram" ] } }, "required": [ "customer_id", "connection_id", "action", "conversation_id", "recipient_id", "anchor_message_id", "confirm_mark_seen" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "youtube_comment_id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "expected_etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "action": { "const": "reply_youtube_comment" }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "customer_id", "connection_id", "youtube_comment_id", "expected_etag", "action", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "youtube_comment_id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "expected_etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "action": { "const": "moderate_youtube_comment" }, "moderation_status": { "enum": [ "published", "heldForReview" ] } }, "required": [ "customer_id", "connection_id", "youtube_comment_id", "expected_etag", "action", "moderation_status" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "youtube_comment_id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "expected_etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "action": { "const": "reject_youtube_comment" }, "confirm_reject": { "const": true } }, "required": [ "customer_id", "connection_id", "youtube_comment_id", "expected_etag", "action", "confirm_reject" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "youtube_comment_id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "expected_etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "action": { "const": "delete_youtube_comment" }, "confirm_delete": { "const": true } }, "required": [ "customer_id", "connection_id", "youtube_comment_id", "expected_etag", "action", "confirm_delete" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "enable_facebook_message_push" }, "replace_native_fields": { "type": "array", "enum": [ [ "messages" ], [ "messages", "message_deliveries" ], [ "messages", "message_reads" ], [ "messages", "message_deliveries", "message_reads" ] ] }, "metadata_only": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "replace_native_fields", "metadata_only" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "enable_message_push" }, "replace_native_fields": { "type": "array", "enum": [ [ "messages" ], [ "messages", "messaging_seen" ] ] }, "metadata_only": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "replace_native_fields", "metadata_only" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "reply_text" }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "recipient_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "in_reply_to": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "customer_id", "connection_id", "action", "conversation_id", "recipient_id", "in_reply_to", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "media_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "comment_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "action": { "const": "reply_comment" }, "text": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "customer_id", "connection_id", "media_id", "comment_id", "action", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "media_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "comment_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "action": { "const": "set_comment_hidden" }, "hidden": { "type": "boolean" } }, "required": [ "customer_id", "connection_id", "media_id", "comment_id", "action", "hidden" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "media_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "comment_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "action": { "const": "delete_comment" }, "confirm_delete": { "const": true } }, "required": [ "customer_id", "connection_id", "media_id", "comment_id", "action", "confirm_delete" ], "additionalProperties": false } ] } } } } } }, "/api/v1/projects/{project_id}/inbox/operations/{operation_id}": { "get": { "summary": "Read reply status and receipt; excludes encrypted payload and investigation note", "operationId": "get__api_v1_projects_project_id_inbox_operations_operation_id_", "x-required-scope": "inbox:operations:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "enum": [ "reply_facebook_comment", "set_facebook_comment_hidden", "delete_facebook_comment", "reply_youtube_comment", "moderate_youtube_comment", "reject_youtube_comment", "delete_youtube_comment", "reply_text", "mark_conversation_seen", "reply_image", "enable_message_push", "enable_facebook_message_push", "reply_comment", "set_comment_hidden", "delete_comment" ] }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "provider_data_erased_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Provider receipt deliberately removed under a scoped deletion request; operation status/idempotency remain." }, "attempts": { "type": "integer" }, "provider_receipt": { "anyOf": [ { "type": "object", "properties": { "conversation_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "recipient_id": { "type": "string" }, "anchor_message_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "sender_action": { "const": "mark_seen" }, "native_action_accepted": { "const": true }, "read_receipt_confirmed": { "const": false }, "delivery_confirmed": { "const": false } }, "required": [ "conversation_id", "recipient_id", "anchor_message_id", "sender_action", "native_action_accepted", "read_receipt_confirmed", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "subscription": { "enum": [ "messages", "messages,messaging_seen", "messages,message_deliveries", "messages,message_reads", "messages,message_deliveries,message_reads" ] }, "native_subscription_accepted": { "const": true }, "metadata_only": { "const": true }, "delivery_confirmed": { "const": false } }, "required": [ "subscription", "native_subscription_accepted", "metadata_only", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "media_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "comment_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "reply_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "hidden": { "type": "boolean" }, "deleted": { "const": true }, "delivery_confirmed": { "const": false } }, "required": [ "media_id", "comment_id", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "post_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "comment_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "parent_id": { "type": [ "string", "null" ] }, "reply_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "deleted": { "const": true }, "hidden": { "type": "boolean" }, "native_action_accepted": { "const": true }, "delivery_confirmed": { "const": false } }, "required": [ "post_id", "comment_id", "parent_id", "native_action_accepted", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "channel_id": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, "comment_id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "reply_id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "deleted": { "const": true }, "moderation_status": { "enum": [ "published", "heldForReview", "rejected" ] }, "ban_author": { "const": false }, "delivery_confirmed": { "const": false } }, "required": [ "channel_id", "comment_id", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "conversation_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "recipient_id": { "type": "string" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "delivery_confirmed": { "const": false } }, "required": [ "conversation_id", "recipient_id", "message_id", "delivery_confirmed" ], "additionalProperties": false }, { "type": "null" } ] }, "error_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_by": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "customer_id", "connection_id", "action", "status", "provider_data_erased_at", "attempts", "provider_receipt", "error_code", "created_at", "updated_at", "expires_at", "acknowledged_at", "acknowledged_by" ], "additionalProperties": false } }, "required": [ "operation" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/inbox/operations/{operation_id}/cancel": { "post": { "summary": "Cancel future queued inbox attempts before current native start; no unsend, moderation rollback, existing push removal or refund", "operationId": "post__api_v1_projects_project_id_inbox_operations_operation_id_cancel", "x-required-scope": "inbox:operations:read and inbox:write; owner/admin", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9_]{0,79}(?![\\s\\S])" }, "status": { "const": "cancelled" }, "cancelled": { "const": true }, "future_attempts_cancelled": { "const": true }, "delivery_confirmed": { "const": false }, "replayed": { "type": "boolean" } }, "required": [ "id", "action", "status", "cancelled", "future_attempts_cancelled", "delivery_confirmed", "replayed" ], "additionalProperties": false } }, "required": [ "operation" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_action": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9_]{0,79}(?![\\s\\S])" }, "confirm_cancel": { "const": true } }, "required": [ "expected_action", "confirm_cancel" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/inbox/operations/{operation_id}/acknowledge": { "post": { "summary": "Acknowledge an investigated unknown reply outcome to unblock the conversation; does not retry or claim delivery", "operationId": "post__api_v1_projects_project_id_inbox_operations_operation_id_acknowledge", "x-required-scope": "inbox:write and inbox:operations:read;owner/admin", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "ambiguous" }, "acknowledged": { "const": true }, "replayed": { "type": "boolean" } }, "required": [ "id", "status", "acknowledged", "replayed" ], "additionalProperties": false }, "delivery_confirmed": { "const": false } }, "required": [ "operation", "delivery_confirmed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledge_unknown_outcome": { "const": true }, "note": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "acknowledge_unknown_outcome", "note" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/boost-context": { "post": { "summary": "Inspect one owned eligible published Facebook link post under a same-customer Page and advertiser; reviewed revision/link required for subsequent creation", "operationId": "post__api_v1_projects_project_id_ads_boost_context", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string" }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "post_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}_[1-9][0-9]{0,29}$" }, "post_revision": { "type": "string", "format": "date-time" }, "link_url": { "type": "string", "format": "uri" }, "currency": { "type": "string" }, "eligible_at_read": { "const": true }, "message": { "type": [ "string", "null" ] }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "advertiser_id", "page_id", "post_id", "post_revision", "link_url", "currency", "eligible_at_read", "read_only", "content_is_untrusted", "fetched_at", "limitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "post_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}_[1-9][0-9]{0,29}$" }, "include_body": { "type": "boolean", "default": false } }, "required": [ "customer_id", "connection_id", "page_connection_id", "post_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/instagram-identity": { "post": { "summary": "Read one Page-connected Instagram Marketing API identity under separately authorized same-customer Page and advertiser connections; no connection creation or ad mutation", "operationId": "post__api_v1_projects_project_id_ads_instagram_identity", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "advertiser_id": { "type": "string" }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "username": { "type": [ "string", "null" ] }, "identity_type": { "const": "page_connected" }, "currency": { "type": "string" }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "advertiser_id", "page_id", "instagram_user_id", "username", "identity_type", "currency", "read_only", "content_is_untrusted", "fetched_at", "limitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" } }, "required": [ "customer_id", "connection_id", "page_connection_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/google-search-context": { "post": { "summary": "Inspect one known Search campaign/budget/ad-group/responsive-ad and bounded keyword/geo/language settings; independent reads, not a complete or atomic snapshot", "operationId": "post__api_v1_projects_project_id_ads_google_search_context", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "delivery_diagnostics": { "type": "object", "properties": { "primary_status": { "type": [ "string", "null" ] }, "primary_status_reasons": { "anyOf": [ { "type": "array", "items": { "type": "string" }, "maxItems": 100 }, { "type": "null" } ] }, "policy_topics_state": { "enum": [ "not_requested", "not_returned", "returned" ] }, "policy_topics": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "topic": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "evidences": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "language" }, "language_code": { "type": "string" } }, "required": [ "kind", "language_code" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "websites" }, "websites": { "type": "array", "items": { "type": "string" }, "maxItems": 5 } }, "required": [ "kind", "websites" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "enum": [ "text", "destination_text" ] }, "texts": { "type": "array", "items": { "type": "string" }, "maxItems": 100 } }, "required": [ "kind", "texts" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "destination_mismatch" }, "url_types": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } }, "required": [ "kind", "url_types" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "const": "destination_not_working" }, "expanded_url": { "type": [ "string", "null" ] }, "device": { "type": [ "string", "null" ] }, "last_checked_date_time": { "type": [ "string", "null" ], "description": "Native YYYY-MM-DD HH:mm:ss; no time zone is asserted." }, "time_zone": { "type": "null" }, "dns_error_type": { "type": [ "string", "null" ] }, "http_error_code": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,18})$" } }, "required": [ "kind", "expanded_url", "device", "last_checked_date_time", "time_zone", "dns_error_type", "http_error_code" ], "additionalProperties": false } ] }, "maxItems": 32 }, "constraints": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "kind": { "const": "reseller" } }, "required": [ "kind" ], "additionalProperties": false }, { "type": "object", "properties": { "kind": { "enum": [ "country", "certificate_missing", "certificate_domain_mismatch" ] }, "total_targeted_countries": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 }, "countries": { "type": "array", "items": { "type": "object", "properties": { "country_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] } }, "required": [ "country_id" ], "additionalProperties": false }, "maxItems": 300 } }, "required": [ "kind", "total_targeted_countries", "countries" ], "additionalProperties": false } ] }, "maxItems": 32 } }, "required": [ "topic", "type", "evidences", "constraints" ], "additionalProperties": false }, "maxItems": 50 }, { "type": "null" } ] }, "delivery_confirmed": { "const": false } }, "required": [ "primary_status", "primary_status_reasons", "policy_topics_state", "delivery_confirmed" ], "additionalProperties": false, "description": "Explicit include_policy_details independently selects untrusted native evidence. Omitted topics are not requested; null is not returned; [] is returned empty, not proof of policy compliance. At most262144 UTF-8 bytes for diagnostics. Six reviewed evidence and four constraint forms; malformed, unknown oneof or oversized native results fail closed without passthrough. No appeal, mutation or delivery guarantee." }, "diagnostics_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Diagnostics only; never use as a configuration mutation precondition." }, "advertiser": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": [ "string", "null" ] }, "time_zone": { "type": [ "string", "null" ] } }, "required": [ "id", "currency", "time_zone" ], "additionalProperties": false }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "channel": { "const": "SEARCH" }, "bidding_strategy": { "type": [ "string", "null" ] }, "portfolio_bidding_strategy": { "type": [ "string", "null" ] }, "target_impression_share": { "anyOf": [ { "type": "object", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ] }, "location_fraction_micros": { "type": "string", "pattern": "^(?:[1-9]\\d{0,5}|1000000)$", "description": "Canonical fraction micros1–1000000. 500000 means50%, not currency. Requested auction objective, not guaranteed delivery/share." }, "cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "location", "location_fraction_micros", "cpc_bid_ceiling_micros" ], "additionalProperties": false }, { "type": "null" } ], "description": "Exact returned native location/fraction/ceiling or null when absent. Independent configuration read, not achieved share or guaranteed placement." }, "target_cpa_micros": { "type": [ "string", "null" ] }, "target_roas": { "type": [ "number", "null" ], "minimum": 0 }, "cpc_bid_ceiling_micros": { "type": [ "string", "null" ] }, "start_date_time": { "type": [ "string", "null" ] }, "end_date_time": { "type": [ "string", "null" ] }, "eu_political_advertising": { "type": [ "string", "null" ] }, "networks": { "type": "object", "properties": { "google_search": { "type": [ "boolean", "null" ] }, "search_partners": { "type": [ "boolean", "null" ] }, "display": { "type": [ "boolean", "null" ] }, "partner_search": { "type": [ "boolean", "null" ] } }, "required": [ "google_search", "search_partners", "display", "partner_search" ], "additionalProperties": false }, "geo_presence": { "type": "object", "properties": { "positive": { "type": [ "string", "null" ] }, "negative": { "type": [ "string", "null" ] } }, "required": [ "positive", "negative" ], "additionalProperties": false }, "ai_max": { "type": [ "boolean", "null" ] }, "asset_automation": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] } }, "required": [ "type", "status" ], "additionalProperties": false } } }, "required": [ "id", "name", "status", "channel", "bidding_strategy", "portfolio_bidding_strategy", "target_impression_share", "target_cpa_micros", "target_roas", "cpc_bid_ceiling_micros", "start_date_time", "end_date_time", "eu_political_advertising", "networks", "geo_presence", "ai_max", "asset_automation" ], "additionalProperties": false }, "budget": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "amount_micros": { "type": [ "string", "null" ] }, "explicitly_shared": { "type": [ "boolean", "null" ] }, "period": { "type": [ "string", "null" ] }, "delivery_method": { "type": [ "string", "null" ] } }, "required": [ "id", "amount_micros", "explicitly_shared", "period", "delivery_method" ], "additionalProperties": false }, "ad_group": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "cpc_bid_micros": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "status", "type", "cpc_bid_micros" ], "additionalProperties": false }, "ad": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "status": { "type": [ "string", "null" ] }, "type": { "const": "RESPONSIVE_SEARCH_AD" }, "approval_status": { "type": [ "string", "null" ] }, "review_status": { "type": [ "string", "null" ] }, "final_urls": { "type": "array", "items": { "type": [ "string", "null" ] } }, "headlines": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "pinned_field": { "type": [ "string", "null" ] } }, "required": [ "text", "pinned_field" ], "additionalProperties": false } }, "descriptions": { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "pinned_field": { "type": [ "string", "null" ] } }, "required": [ "text", "pinned_field" ], "additionalProperties": false } }, "path1": { "type": [ "string", "null" ] }, "path2": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "type", "approval_status", "review_status" ], "additionalProperties": false }, "keywords": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "status": { "type": [ "string", "null" ] }, "negative": { "type": [ "boolean", "null" ] }, "match_type": { "type": [ "string", "null" ] }, "cpc_bid_micros": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "status", "negative", "match_type", "cpc_bid_micros" ], "additionalProperties": false } }, "targets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "type": { "enum": [ "LOCATION", "LANGUAGE" ] }, "target_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "negative": { "type": [ "boolean", "null" ] }, "status": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "target_id", "negative", "status" ], "additionalProperties": false } }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "revision_basis": { "enum": [ "selected_configuration_metadata", "selected_configuration_with_body" ] }, "complete_snapshot": { "const": false }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "delivery_diagnostics", "diagnostics_revision", "advertiser", "campaign", "budget", "ad_group", "ad", "keywords", "targets", "revision", "revision_basis", "complete_snapshot", "read_only", "content_is_untrusted", "fetched_at", "limitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "include_body": { "type": "boolean", "default": false }, "include_policy_details": { "type": "boolean", "default": false, "description": "Separate explicit consent to native policy evidence including creative/destination text and URLs. Independent of include_body." } }, "required": [ "customer_id", "connection_id", "campaign_id", "ad_group_id", "ad_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/google-targets": { "post": { "summary": "Look up bounded native Google Ads location suggestions or exact language constants; read-only, no forecast or spend authorization", "operationId": "post__api_v1_projects_project_id_ads_google_targets", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "provider": { "const": "googleads" }, "advertiser_id": { "type": "string" }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "complete_catalog": { "const": false }, "truncated": { "type": "boolean" }, "returned_by_provider": { "type": "integer", "minimum": 0, "maximum": 1000 }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } }, "kind": { "const": "locations" }, "suggestions": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "name": { "type": "string" }, "canonical_name": { "type": [ "string", "null" ] }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "target_type": { "type": "string" }, "status": { "enum": [ "ENABLED", "REMOVAL_PLANNED", "UNKNOWN", "UNSPECIFIED" ] }, "targetable": { "type": "boolean" }, "search_term": { "type": "string" }, "locale": { "type": "string" }, "approximate_reach": { "type": [ "string", "null" ], "pattern": "^(0|[1-9][0-9]{0,18})$" }, "parents": { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "name": { "type": "string" }, "canonical_name": { "type": [ "string", "null" ] }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "target_type": { "type": "string" }, "status": { "enum": [ "ENABLED", "REMOVAL_PLANNED", "UNKNOWN", "UNSPECIFIED" ] }, "targetable": { "type": "boolean" } }, "required": [ "id", "name", "canonical_name", "country_code", "target_type", "status", "targetable" ], "additionalProperties": false } } }, "required": [ "id", "name", "canonical_name", "country_code", "target_type", "status", "targetable", "search_term", "locale", "approximate_reach", "parents" ], "additionalProperties": false } } }, "required": [ "provider", "advertiser_id", "read_only", "content_is_untrusted", "complete_catalog", "truncated", "returned_by_provider", "fetched_at", "limitations", "kind", "suggestions" ], "additionalProperties": false }, { "type": "object", "properties": { "provider": { "const": "googleads" }, "advertiser_id": { "type": "string" }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "complete_catalog": { "const": false }, "truncated": { "type": "boolean" }, "returned_by_provider": { "type": "integer", "minimum": 0, "maximum": 1000 }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } }, "kind": { "const": "languages" }, "languages": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "code": { "type": "string" }, "name": { "type": "string" }, "targetable": { "type": [ "boolean", "null" ] } }, "required": [ "id", "code", "name", "targetable" ], "additionalProperties": false } } }, "required": [ "provider", "advertiser_id", "read_only", "content_is_untrusted", "complete_catalog", "truncated", "returned_by_provider", "fetched_at", "limitations", "kind", "languages" ], "additionalProperties": false } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "kind": { "const": "locations" }, "names": { "type": "array", "minItems": 1, "maxItems": 25, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200 } }, "locale": { "type": "string", "pattern": "^[a-z]{2}$", "default": "en" }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "customer_id", "connection_id", "kind", "names" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "kind": { "const": "languages" }, "language_codes": { "type": "array", "minItems": 1, "maxItems": 50, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z]{2,3}(?:[_-][A-Za-z]{2,4})?$" } } }, "required": [ "customer_id", "connection_id", "kind" ], "additionalProperties": false } ] } } } } } }, "/api/v1/projects/{project_id}/ads/google-search-terms": { "post": { "summary": "Read selected Google Search top terms; low-volume privacy omissions mean this is never an exhaustive traffic report", "operationId": "post__api_v1_projects_project_id_ads_google_search_terms", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "googleads" }, "advertiser": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "time_zone": { "type": "string" } }, "required": [ "id", "currency", "time_zone" ], "additionalProperties": false }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "period": { "type": "object", "properties": { "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date" }, "date_basis": { "const": "advertiser_time_zone" }, "aggregation": { "const": "whole_period" } }, "required": [ "since", "until", "date_basis", "aggregation" ], "additionalProperties": false }, "metric_set": { "enum": [ "basic", "performance" ] }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "complete_report": { "const": false }, "order": { "const": "cost_micros_desc" }, "tie_order": { "const": "unspecified" }, "truncated": { "type": "boolean" }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } }, "rows": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "resource_name": { "type": "string" }, "search_term": { "type": "string", "minLength": 1, "maxLength": 4096, "description": "At most4096 UTF-8 bytes; untrusted potentially sensitive query text" }, "keyword_status": { "enum": [ "ADDED", "ADDED_EXCLUDED", "EXCLUDED", "NONE", "UNKNOWN", "UNSPECIFIED" ] }, "cost_micros": { "type": "string" }, "cost": { "type": "string" }, "clicks": { "type": "string" }, "impressions": { "type": "string" }, "performance": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "conversions": { "type": "string" }, "conversions_value": { "type": "string" }, "all_conversions": { "type": "string" }, "all_conversions_value": { "type": "string" }, "view_through_conversions": { "type": "string" }, "interactions": { "type": "string" }, "ctr": { "type": "string" } }, "required": [ "conversions", "conversions_value", "all_conversions", "all_conversions_value", "view_through_conversions", "interactions", "ctr" ], "additionalProperties": false } ] } }, "required": [ "resource_name", "search_term", "keyword_status", "cost_micros", "cost", "clicks", "impressions", "performance" ], "additionalProperties": false } }, "performance_basis": { "anyOf": [ { "type": "null" }, { "type": "object", "properties": { "attribution": { "const": "provider_conversion_action_settings" }, "date_field": { "const": "segments.date" }, "conversion_values_unit": { "const": "account_currency" }, "ctr_unit": { "const": "ratio" }, "double_precision": { "const": "native_json_number_or_numeric_string" }, "omitted_metrics": { "const": "protobuf_default_zero_within_returned_rows" }, "cross_provider_comparable": { "const": false } }, "required": [ "attribution", "date_field", "conversion_values_unit", "ctr_unit", "double_precision", "omitted_metrics", "cross_provider_comparable" ], "additionalProperties": false } ] } }, "required": [ "provider", "advertiser", "campaign_id", "ad_group_id", "period", "metric_set", "read_only", "content_is_untrusted", "complete_report", "order", "tie_order", "truncated", "fetched_at", "limitations", "rows", "performance_basis" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date", "description": "Inclusive1–31day period, not before since" }, "include_terms": { "const": true }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "metric_set": { "enum": [ "basic", "performance" ], "default": "basic" } }, "required": [ "customer_id", "connection_id", "campaign_id", "ad_group_id", "since", "until", "include_terms" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/google-campaign-conversions": { "post": { "summary": "Read bounded daily conversion-action metrics for one Google Ads campaign; explicit truncation and native attribution", "operationId": "post__api_v1_projects_project_id_ads_google_campaign_conversions", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "googleads" }, "advertiser": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "time_zone": { "type": "string" } }, "required": [ "id", "currency", "time_zone" ], "additionalProperties": false }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "conversion_action_filter": { "anyOf": [ { "type": "string", "pattern": "^customers/[0-9]{10}/conversionActions/[1-9][0-9]{0,18}$", "description": "Native action reference; action ID must fit signed int64. A manager-owned reference never authorizes a lookup in that account." }, { "type": "null" } ] }, "period": { "type": "object", "properties": { "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date" }, "date_basis": { "const": "advertiser_time_zone" }, "aggregation": { "const": "daily_conversion_action" } }, "required": [ "since", "until", "date_basis", "aggregation" ], "additionalProperties": false }, "read_only": { "const": true }, "complete_snapshot": { "const": false }, "truncated": { "type": "boolean" }, "order": { "const": "date_asc_conversion_action_asc" }, "fetched_at": { "type": "string", "format": "date-time" }, "rows": { "type": "array", "maxItems": 1000, "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "conversion_action": { "type": "string", "pattern": "^customers/[0-9]{10}/conversionActions/[1-9][0-9]{0,18}$", "description": "Native action reference; action ID must fit signed int64. A manager-owned reference never authorizes a lookup in that account." }, "category": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$" }, "conversions": { "type": "string" }, "conversions_value": { "type": "string" }, "all_conversions": { "type": "string" }, "all_conversions_value": { "type": "string" } }, "required": [ "date", "conversion_action", "category", "conversions", "conversions_value", "all_conversions", "all_conversions_value" ], "additionalProperties": false } }, "metric_basis": { "type": "object", "properties": { "attribution": { "const": "provider_conversion_action_settings" }, "date_field": { "const": "segments.date" }, "conversion_date_variants": { "const": false }, "conversion_values_unit": { "const": "account_currency" }, "double_precision": { "const": "native_json_number_or_numeric_string" }, "omitted_metrics": { "const": "protobuf_default_zero_within_returned_rows" }, "cross_provider_comparable": { "const": false } }, "required": [ "attribution", "date_field", "conversion_date_variants", "conversion_values_unit", "double_precision", "omitted_metrics", "cross_provider_comparable" ], "additionalProperties": false }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "provider", "advertiser", "campaign_id", "conversion_action_filter", "period", "read_only", "complete_snapshot", "truncated", "order", "fetched_at", "rows", "metric_basis", "limitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date", "description": "Inclusive1–31days, not before since" }, "conversion_action": { "type": "string", "pattern": "^customers/[0-9]{10}/conversionActions/[1-9][0-9]{0,18}$", "description": "Native action reference; action ID must fit signed int64. A manager-owned reference never authorizes a lookup in that account." }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 } }, "required": [ "customer_id", "connection_id", "campaign_id", "since", "until" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/google-campaign-devices": { "post": { "summary": "Read bounded daily device cost/click/impression/conversion metrics for one Google Ads campaign; native sparse and attribution semantics", "operationId": "post__api_v1_projects_project_id_ads_google_campaign_devices", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "googleads" }, "advertiser": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "time_zone": { "type": "string" } }, "required": [ "id", "currency", "time_zone" ], "additionalProperties": false }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "period": { "type": "object", "properties": { "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date" }, "date_basis": { "const": "advertiser_time_zone" }, "aggregation": { "const": "daily_device" } }, "required": [ "since", "until", "date_basis", "aggregation" ], "additionalProperties": false }, "read_only": { "const": true }, "complete_snapshot": { "const": false }, "truncated": { "const": false }, "order": { "const": "date_asc_device_code_asc" }, "fetched_at": { "type": "string", "format": "date-time" }, "rows": { "type": "array", "maxItems": 217, "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "device": { "enum": [ "CONNECTED_TV", "DESKTOP", "MOBILE", "OTHER", "TABLET", "UNKNOWN", "UNSPECIFIED" ] }, "cost_micros": { "type": "string" }, "cost": { "type": "string" }, "clicks": { "type": "string" }, "impressions": { "type": "string" }, "conversions": { "type": "string" }, "conversions_value": { "type": "string" }, "all_conversions": { "type": "string" }, "all_conversions_value": { "type": "string" } }, "required": [ "date", "device", "cost_micros", "cost", "clicks", "impressions", "conversions", "conversions_value", "all_conversions", "all_conversions_value" ], "additionalProperties": false } }, "metric_basis": { "type": "object", "properties": { "attribution": { "const": "provider_conversion_action_settings" }, "date_field": { "const": "segments.date" }, "conversion_date_variants": { "const": false }, "conversion_values_unit": { "const": "account_currency" }, "double_precision": { "const": "native_json_number_or_numeric_string" }, "omitted_metrics": { "const": "protobuf_default_zero_within_returned_rows" }, "cross_provider_comparable": { "const": false }, "cost_unit": { "const": "account_currency" }, "cost_micros_per_unit": { "const": "1000000" } }, "required": [ "attribution", "date_field", "conversion_date_variants", "conversion_values_unit", "double_precision", "omitted_metrics", "cross_provider_comparable", "cost_unit", "cost_micros_per_unit" ], "additionalProperties": false }, "limitations": { "type": "array", "items": { "type": "string" } }, "device_filter": { "anyOf": [ { "enum": [ "CONNECTED_TV", "DESKTOP", "MOBILE", "OTHER", "TABLET", "UNKNOWN", "UNSPECIFIED" ] }, { "type": "null" } ] } }, "required": [ "provider", "advertiser", "campaign_id", "period", "read_only", "complete_snapshot", "truncated", "order", "fetched_at", "rows", "metric_basis", "limitations", "device_filter" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date", "description": "Inclusive1–31days" }, "device": { "enum": [ "CONNECTED_TV", "DESKTOP", "MOBILE", "OTHER", "TABLET", "UNKNOWN", "UNSPECIFIED" ] } }, "required": [ "customer_id", "connection_id", "campaign_id", "since", "until" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/google-campaign-locations": { "post": { "summary": "Read a bounded native country/targeted-flag cost ranking for one Google campaign; period aggregates with explicit truncation and no individual-location or completeness guarantee", "operationId": "post__api_v1_projects_project_id_ads_google_campaign_locations", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "googleads" }, "advertiser": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "time_zone": { "type": "string" } }, "required": [ "id", "currency", "time_zone" ], "additionalProperties": false }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "period": { "type": "object", "properties": { "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date" }, "date_basis": { "const": "advertiser_time_zone" }, "aggregation": { "const": "period_country_targeting_location" } }, "required": [ "since", "until", "date_basis", "aggregation" ], "additionalProperties": false }, "read_only": { "const": true }, "complete_snapshot": { "const": false }, "truncated": { "type": "boolean" }, "order": { "const": "cost_micros_desc_country_id_asc_targeting_location_asc" }, "fetched_at": { "type": "string", "format": "date-time" }, "rows": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "country_criterion_id": { "type": "string", "pattern": "^(0|[1-9][0-9]{0,18})$", "description": "Exact native nonnegative int64 country criterion code; literal0 unresolved, not an ISO code or campaign criterion ID" }, "targeting_location": { "type": "boolean" }, "cost_micros": { "type": "string" }, "cost": { "type": "string" }, "clicks": { "type": "string" }, "impressions": { "type": "string" }, "conversions": { "type": "string" }, "conversions_value": { "type": "string" }, "all_conversions": { "type": "string" }, "all_conversions_value": { "type": "string" } }, "required": [ "country_criterion_id", "targeting_location", "cost_micros", "cost", "clicks", "impressions", "conversions", "conversions_value", "all_conversions", "all_conversions_value" ], "additionalProperties": false } }, "metric_basis": { "type": "object", "properties": { "attribution": { "const": "provider_conversion_action_settings" }, "conversion_date_variants": { "const": false }, "conversion_values_unit": { "const": "account_currency" }, "double_precision": { "const": "native_json_number_or_numeric_string" }, "omitted_metrics": { "const": "protobuf_default_zero_within_returned_rows" }, "cross_provider_comparable": { "const": false }, "date_filter": { "const": "segments.date" }, "location_view": { "const": "user_location_view" }, "location_basis": { "const": "provider_reported_physical_country" }, "targeting_location": { "const": "native_reported_targeted_flag" }, "cost_unit": { "const": "account_currency" }, "cost_micros_per_unit": { "const": "1000000" } }, "required": [ "attribution", "conversion_date_variants", "conversion_values_unit", "double_precision", "omitted_metrics", "cross_provider_comparable", "date_filter", "location_view", "location_basis", "targeting_location", "cost_unit", "cost_micros_per_unit" ], "additionalProperties": false }, "limitations": { "type": "array", "items": { "type": "string" } }, "limit": { "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "provider", "advertiser", "campaign_id", "period", "read_only", "complete_snapshot", "truncated", "order", "fetched_at", "rows", "metric_basis", "limitations", "limit" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date", "description": "Inclusive1–31days, not before since" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "required": [ "customer_id", "connection_id", "campaign_id", "since", "until" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/google-campaign-goals": { "post": { "summary": "Inspect selected campaign conversion goals and custom-action references; no tracking-health or atomic snapshot guarantee", "operationId": "post__api_v1_projects_project_id_ads_google_campaign_goals", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "googleads" }, "advertiser": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string" }, "time_zone": { "type": "string" }, "conversion_customer": { "type": [ "string", "null" ] }, "conversion_tracking_status": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" } }, "required": [ "id", "currency", "time_zone", "conversion_customer", "conversion_tracking_status" ], "additionalProperties": false }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "status": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" }, "channel": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" }, "bidding_strategy": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" } }, "required": [ "id", "status", "channel", "bidding_strategy" ], "additionalProperties": false }, "goal_config_level": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" }, "goals": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "resource_name": { "type": "string" }, "category": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" }, "origin": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" }, "biddable": { "type": "boolean" } }, "required": [ "resource_name", "category", "origin", "biddable" ], "additionalProperties": false } }, "custom_goal": { "anyOf": [ { "type": "object", "properties": { "resource_name": { "type": "string" }, "id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "status": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" }, "conversion_actions": { "type": "array", "maxItems": 1000, "uniqueItems": true, "items": { "type": "string" } } }, "required": [ "resource_name", "id", "status", "conversion_actions" ], "additionalProperties": false }, { "type": "null" } ] }, "revision": { "type": "string" }, "revision_basis": { "const": "selected_conversion_goal_configuration" }, "read_only": { "const": true }, "complete_snapshot": { "const": false }, "truncated": { "const": false }, "tracking_verified": { "const": false }, "limitations": { "type": "array", "items": { "type": "string" } }, "fetched_at": { "type": "string", "format": "date-time" } }, "required": [ "provider", "advertiser", "campaign", "goal_config_level", "goals", "custom_goal", "revision", "revision_basis", "read_only", "complete_snapshot", "truncated", "tracking_verified", "limitations", "fetched_at" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "customer_id", "connection_id", "campaign_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/google-account-goals": { "post": { "summary": "Read bounded advertiser-default conversion goals and reviewed projection revision; not tracking-health proof", "operationId": "post__api_v1_projects_project_id_ads_google_account_goals", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "googleads" }, "advertiser": { "type": "object", "properties": { "id": { "type": "string" }, "currency": { "type": "string" }, "time_zone": { "type": "string" }, "conversion_customer": { "type": [ "string", "null" ] }, "conversion_tracking_status": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" } }, "required": [ "id", "currency", "time_zone", "conversion_customer", "conversion_tracking_status" ], "additionalProperties": false }, "goals": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "resource_name": { "type": "string" }, "category": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" }, "origin": { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$", "description": "Native enum code, preserving UNKNOWN/UNSPECIFIED" }, "biddable": { "type": "boolean" } }, "required": [ "resource_name", "category", "origin", "biddable" ], "additionalProperties": false } }, "revision": { "type": "string" }, "revision_basis": { "const": "selected_account_conversion_goals" }, "read_only": { "const": true }, "complete_snapshot": { "const": false }, "truncated": { "const": false }, "tracking_verified": { "const": false }, "limitations": { "type": "array", "items": { "type": "string" } }, "fetched_at": { "type": "string", "format": "date-time" } }, "required": [ "provider", "advertiser", "goals", "revision", "revision_basis", "read_only", "complete_snapshot", "truncated", "tracking_verified", "limitations", "fetched_at" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" } }, "required": [ "customer_id", "connection_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/meta-assets": { "post": { "summary": "Inspect bounded customer-bound Meta pixel edge metadata (native flags/timestamps, names opt-in; no event data or eligibility guarantee), custom-audience edge metadata/approximate size bounds (names opt-in), image/creative metadata or ad-account video edge membership and native processing phase states/codes; video association is not exclusive ownership or advertising eligibility; metadata by default, explicit exact-creative body opt-in; never a deletion-safety or complete snapshot proof", "operationId": "post__api_v1_projects_project_id_ads_meta_assets", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "metaads" }, "advertiser_id": { "type": "string" }, "resource": { "enum": [ "images", "creatives", "creative", "videos", "audiences", "pixels" ] }, "include_body": { "type": "boolean" }, "data": { "type": "array", "maxItems": 50, "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "kind": { "const": "image" }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "width": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000 }, "height": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000 }, "original_width": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000 }, "original_height": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100000 } }, "required": [ "id", "account_id", "name", "status", "revision", "kind", "image_hash", "width", "height", "original_width", "original_height" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "kind": { "const": "creative" }, "image_hash": { "type": [ "string", "null" ] }, "object_story_id": { "type": [ "string", "null" ] }, "effective_object_story_id": { "type": [ "string", "null" ] }, "video_id": { "type": [ "string", "null" ] }, "object_type": { "type": [ "string", "null" ] }, "body": { "anyOf": [ { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "link_url": { "type": [ "string", "null" ] }, "story": { "anyOf": [ { "type": "object", "properties": { "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "page_id": { "type": [ "string", "null" ] }, "video_data": { "type": "object", "properties": { "video_id": { "type": [ "string", "null" ] }, "image_hash": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "link_description": { "type": [ "string", "null" ] }, "call_to_action": { "anyOf": [ { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] } }, "required": [ "type", "link" ], "additionalProperties": false }, { "type": "null" } ] }, "unmodeled_fields": { "type": "array", "maxItems": 128, "items": { "type": "string" }, "description": "Field paths only; values and native poster/media URLs are suppressed. Not a complete variant/usage inventory." } }, "required": [ "video_id", "image_hash", "message", "title", "link_description", "call_to_action", "unmodeled_fields" ], "additionalProperties": false }, "link_data": { "anyOf": [ { "type": "object", "properties": { "image_hash": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "call_to_action": { "anyOf": [ { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] } }, "required": [ "type", "link" ], "additionalProperties": false }, { "type": "null" } ] }, "cards": { "anyOf": [ { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "image_hash": { "type": [ "string", "null" ] }, "video_id": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "call_to_action": { "anyOf": [ { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] } }, "required": [ "type", "link" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "image_hash", "video_id", "link", "headline", "description", "call_to_action" ], "additionalProperties": false } }, { "type": "null" } ] }, "multi_share_optimized": { "type": [ "boolean", "null" ] }, "multi_share_end_card": { "type": [ "boolean", "null" ] } }, "required": [ "image_hash", "link", "message", "headline", "description", "call_to_action", "cards", "multi_share_optimized", "multi_share_end_card" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "page_id", "link_data" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "text", "title", "link_url", "story" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "account_id", "name", "status", "revision", "kind", "image_hash", "object_story_id", "effective_object_story_id", "video_id", "object_type", "body" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": "null" }, "status": { "type": [ "string", "null" ] }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "kind": { "const": "video" }, "video_reference": { "type": "string", "minLength": 1, "maxLength": 6500, "description": "Encrypted15-minute advertiser-library page locator bound to the current connection credential. Freshly rechecked before video creative/ad actions; not write authorization or exclusive ownership proof." }, "processing_progress": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 4294967295 }, "uploading_phase": { "anyOf": [ { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "error_codes": { "anyOf": [ { "type": "array", "maxItems": 20, "items": { "type": [ "integer", "null" ], "minimum": -2147483648, "maximum": 2147483647 } }, { "type": "null" } ] } }, "required": [ "status", "error_codes" ], "additionalProperties": false }, { "type": "null" } ] }, "processing_phase": { "anyOf": [ { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "error_codes": { "anyOf": [ { "type": "array", "maxItems": 20, "items": { "type": [ "integer", "null" ], "minimum": -2147483648, "maximum": 2147483647 } }, { "type": "null" } ] } }, "required": [ "status", "error_codes" ], "additionalProperties": false }, { "type": "null" } ] }, "publishing_phase": { "anyOf": [ { "type": "object", "properties": { "status": { "type": [ "string", "null" ] }, "error_codes": { "anyOf": [ { "type": "array", "maxItems": 20, "items": { "type": [ "integer", "null" ], "minimum": -2147483648, "maximum": 2147483647 } }, { "type": "null" } ] } }, "required": [ "status", "error_codes" ], "additionalProperties": false }, { "type": "null" } ] }, "association": { "const": "ad_account_video_edge" }, "exclusive_ownership_verified": { "const": false }, "advertising_eligibility_verified": { "const": false } }, "required": [ "id", "account_id", "name", "status", "revision", "kind", "video_reference", "processing_progress", "uploading_phase", "processing_phase", "publishing_phase", "association", "exclusive_ownership_verified", "advertising_eligibility_verified" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "null" }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "kind": { "const": "audience" }, "audience_reference": { "type": "string", "minLength": 1, "maxLength": 6500, "description": "Encrypted15-minute inspected-page locator bound to customer/advertiser/current credentials; never write authority." }, "native_account_id": { "type": [ "string", "null" ], "pattern": "^[1-9][0-9]{0,29}$" }, "subtype": { "type": [ "string", "null" ] }, "approximate_size": { "type": "object", "properties": { "lower_bound": { "type": [ "string", "null" ], "pattern": "^(0|-?[1-9][0-9]{0,29})$" }, "upper_bound": { "type": [ "string", "null" ], "pattern": "^(0|-?[1-9][0-9]{0,29})$" }, "exact": { "const": false } }, "required": [ "lower_bound", "upper_bound", "exact" ], "additionalProperties": false }, "delivery_status_code": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "operation_status_code": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "association": { "const": "ad_account_custom_audience_edge" }, "exclusive_ownership_verified": { "const": false }, "advertising_eligibility_verified": { "const": false } }, "required": [ "id", "account_id", "name", "status", "revision", "kind", "audience_reference", "native_account_id", "subtype", "approximate_size", "delivery_status_code", "operation_status_code", "association", "exclusive_ownership_verified", "advertising_eligibility_verified" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": "null" }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "kind": { "const": "pixel" }, "pixel_reference": { "type": "string", "minLength": 1, "maxLength": 6500, "description": "Encrypted15-minute original advertiser-page locator; bound to customer/advertiser/current credentials. Never write authority or eligibility proof." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "last_fired_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "is_unavailable": { "type": [ "boolean", "null" ] }, "is_restricted_use": { "type": [ "boolean", "null" ] }, "association": { "const": "ad_account_pixel_edge" }, "exclusive_ownership_verified": { "const": false }, "advertising_eligibility_verified": { "const": false }, "event_ingestion_verified": { "const": false } }, "required": [ "id", "account_id", "name", "status", "revision", "kind", "pixel_reference", "created_at", "last_fired_at", "is_unavailable", "is_restricted_use", "association", "exclusive_ownership_verified", "advertising_eligibility_verified", "event_ingestion_verified" ], "additionalProperties": false } ] } }, "next_cursor": { "type": [ "string", "null" ] }, "fetched_at": { "type": "string", "format": "date-time" }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "complete_snapshot": { "const": false }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "provider", "advertiser_id", "resource", "include_body", "data", "next_cursor", "fetched_at", "read_only", "content_is_untrusted", "complete_snapshot", "limitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "resource": { "const": "images" }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "include_body": { "const": false, "default": false }, "cursor": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "customer_id", "connection_id", "resource" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "resource": { "const": "pixels" }, "include_names": { "type": "boolean", "default": false }, "include_body": { "const": false, "default": false }, "cursor": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "customer_id", "connection_id", "resource" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "resource": { "const": "audiences" }, "include_names": { "type": "boolean", "default": false }, "include_body": { "const": false, "default": false }, "cursor": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "customer_id", "connection_id", "resource" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "resource": { "enum": [ "creatives", "videos" ] }, "include_body": { "const": false, "default": false }, "cursor": { "type": "string", "minLength": 1, "maxLength": 10000 } }, "required": [ "customer_id", "connection_id", "resource" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 }, "resource": { "const": "creative" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "include_body": { "type": "boolean", "default": false } }, "required": [ "customer_id", "connection_id", "resource", "creative_id" ], "additionalProperties": false } ] } } } } } }, "/api/v1/projects/{project_id}/ads/meta-locations": { "post": { "summary": "Search or resolve bounded native geographic metadata through an authorized Meta advertiser; no targeting mutation", "operationId": "post__api_v1_projects_project_id_ads_meta_locations", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "metaads" }, "advertiser_id": { "type": "string" }, "mode": { "enum": [ "search", "resolve" ] }, "type": { "enum": [ "country", "region", "city" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "type": { "enum": [ "country", "region", "city" ] }, "name": { "type": "string" }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "country_name": { "type": [ "string", "null" ] }, "region_id": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "supports_city": { "type": [ "boolean", "null" ] }, "supports_region": { "type": [ "boolean", "null" ] } }, "required": [ "key", "type", "name", "country_code", "country_name", "region_id", "region", "supports_city", "supports_region" ], "additionalProperties": false } }, "has_more": { "type": "boolean" }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "complete_catalog": { "const": false }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "provider", "advertiser_id", "mode", "type", "data", "has_more", "read_only", "content_is_untrusted", "complete_catalog", "fetched_at", "limitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "country", "region", "city" ] }, "mode": { "const": "search" }, "query": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Trimmed nonempty UTF8 query; control characters are refused." }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, "required": [ "customer_id", "connection_id", "type", "mode", "query" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "type": { "const": "country" } }, "required": [ "type" ] }, "then": { "not": { "required": [ "country_code" ] } } } ] }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "country", "region", "city" ] }, "mode": { "const": "resolve" }, "keys": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 16 } } }, "required": [ "customer_id", "connection_id", "type", "mode", "keys" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "type": { "const": "country" } }, "required": [ "type" ] }, "then": { "properties": { "keys": { "items": { "type": "string", "pattern": "^[A-Z]{2}$" } } } }, "else": { "properties": { "keys": { "items": { "type": "string", "pattern": "^[1-9][0-9]{0,15}$", "description": "Positive exact geographic key at most9007199254740991. String input avoids JSON rounding; native metadata lookup uses safely checked integers." } } } } } ] } ] } } } } } }, "/api/v1/projects/{project_id}/ads/meta-ad-group-context": { "post": { "summary": "Read selected customer-bound Meta advertiser/campaign/ad-group budget and bid settings; shared25-second native-read budget, independent observations rather than an atomic snapshot", "operationId": "post__api_v1_projects_project_id_ads_meta_ad_group_context", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "metaads" }, "advertiser_id": { "type": "string" }, "currency": { "type": "string" }, "account_status": { "type": "integer" }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "type": [ "string", "null" ] }, "objective": { "type": [ "string", "null" ] }, "buying_type": { "type": [ "string", "null" ] }, "daily_budget_minor": { "type": [ "string", "null" ] }, "lifetime_budget_minor": { "type": [ "string", "null" ] }, "special_ad_categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "ad_group_budget_sharing": { "type": [ "boolean", "null" ] }, "scheduled_budget": { "type": [ "boolean", "null" ] } }, "required": [ "id", "status", "objective", "buying_type", "daily_budget_minor", "lifetime_budget_minor", "special_ad_categories", "ad_group_budget_sharing", "scheduled_budget" ], "additionalProperties": false }, "ad_group": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "type": [ "string", "null" ] }, "daily_budget_minor": { "type": [ "string", "null" ] }, "lifetime_budget_minor": { "type": [ "string", "null" ] }, "bid_amount_minor": { "type": [ "string", "null" ] }, "bid_strategy": { "type": [ "string", "null" ] }, "billing_event": { "type": [ "string", "null" ] }, "optimization_goal": { "type": [ "string", "null" ] }, "destination_type": { "type": [ "string", "null" ] }, "end_time": { "type": [ "string", "null" ] }, "scheduled_budget": { "type": [ "boolean", "null" ] }, "has_delivery_schedule": { "type": [ "boolean", "null" ] }, "pacing_type": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "campaign_id", "status", "daily_budget_minor", "lifetime_budget_minor", "bid_amount_minor", "bid_strategy", "billing_event", "optimization_goal", "destination_type", "end_time", "scheduled_budget", "has_delivery_schedule", "pacing_type" ], "additionalProperties": false }, "conversion": { "type": "object", "properties": { "promoted_object": { "anyOf": [ { "type": "object", "properties": { "pixel_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, { "type": "null" } ] }, "custom_conversion_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, { "type": "null" } ] }, "custom_event_type": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$" }, { "type": "null" } ] } }, "required": [ "pixel_id", "custom_conversion_id", "custom_event_type" ], "additionalProperties": false }, { "type": "null" } ] }, "attribution_spec": { "anyOf": [ { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "object", "properties": { "event_type": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$" }, { "type": "null" } ] }, "window_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 } }, "required": [ "event_type", "window_days" ], "additionalProperties": false } }, { "type": "null" } ] }, "complete_configuration": { "const": false }, "native_eligibility_verified": { "const": false }, "effective_attribution_verified": { "const": false }, "event_ingestion_verified": { "const": false }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "promoted_object", "attribution_spec", "complete_configuration", "native_eligibility_verified", "effective_attribution_verified", "event_ingestion_verified", "revision" ], "additionalProperties": false }, "audience_targeting": { "type": "object", "properties": { "included_ids": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "maxItems": 100, "uniqueItems": true }, "excluded_ids": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "maxItems": 100, "uniqueItems": true }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "complete_targeting": { "const": false } }, "required": [ "included_ids", "excluded_ids", "revision", "complete_targeting" ], "additionalProperties": false }, "targeting": { "type": "object", "properties": { "spec": { "anyOf": [ { "type": "object", "properties": { "age_min": { "type": [ "integer", "null" ], "minimum": 13, "maximum": 65 }, "age_max": { "type": [ "integer", "null" ], "minimum": 13, "maximum": 65 }, "genders": { "anyOf": [ { "type": "array", "maxItems": 2, "uniqueItems": true, "items": { "enum": [ 1, 2 ] } }, { "type": "null" } ] }, "geo_locations": { "anyOf": [ { "type": "object", "properties": { "countries": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 300, "uniqueItems": true }, { "type": "null" } ] }, "regions": { "anyOf": [ { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "country": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Observed native country label, not independently resolved geographic country_code." } }, "required": [ "key", "country" ], "additionalProperties": false } }, { "type": "null" } ] }, "cities": { "anyOf": [ { "type": "array", "maxItems": 250, "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "country": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Observed native country label, not independently resolved geographic country_code." }, "radius": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "distance_unit": { "enum": [ "mile", "kilometer", null ] }, "region_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, { "type": "null" } ] } }, "required": [ "key", "country", "radius", "distance_unit", "region_id" ], "additionalProperties": false } }, { "type": "null" } ] }, "location_types": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] } }, "required": [ "countries", "regions", "cities", "location_types" ], "additionalProperties": false }, { "type": "null" } ] }, "excluded_geo_locations": { "anyOf": [ { "type": "object", "properties": { "countries": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 300, "uniqueItems": true }, { "type": "null" } ] }, "regions": { "anyOf": [ { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "country": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Observed native country label, not independently resolved geographic country_code." } }, "required": [ "key", "country" ], "additionalProperties": false } }, { "type": "null" } ] }, "cities": { "anyOf": [ { "type": "array", "maxItems": 250, "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "country": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Observed native country label, not independently resolved geographic country_code." }, "radius": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "distance_unit": { "enum": [ "mile", "kilometer", null ] }, "region_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, { "type": "null" } ] } }, "required": [ "key", "country", "radius", "distance_unit", "region_id" ], "additionalProperties": false } }, { "type": "null" } ] }, "location_types": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] } }, "required": [ "countries", "regions", "cities", "location_types" ], "additionalProperties": false }, { "type": "null" } ] }, "publisher_platforms": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "facebook_positions": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "instagram_positions": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "effective_publisher_platforms": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "effective_facebook_positions": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "effective_instagram_positions": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "device_platforms": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "targeting_automation": { "anyOf": [ { "type": "object", "properties": { "advantage_audience": { "enum": [ 0, 1, null ] } }, "required": [ "advantage_audience" ], "additionalProperties": false }, { "type": "null" } ] }, "unmodeled_fields": { "type": "array", "maxItems": 200, "uniqueItems": true, "items": { "type": "string" }, "description": "Field paths only; unmodeled values and geographic display names are suppressed. Empty does not imply complete effective targeting." } }, "required": [ "age_min", "age_max", "genders", "geo_locations", "excluded_geo_locations", "publisher_platforms", "facebook_positions", "instagram_positions", "effective_publisher_platforms", "effective_facebook_positions", "effective_instagram_positions", "device_platforms", "targeting_automation", "unmodeled_fields" ], "additionalProperties": false }, { "type": "null" } ] }, "start_time": { "type": [ "string", "null" ], "format": "date-time" }, "end_time": { "type": [ "string", "null" ], "format": "date-time" }, "is_dynamic_creative": { "type": [ "boolean", "null" ] }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Separate selected-targeting revision, not a budget/bid precondition or activation approval." }, "complete_targeting": { "const": false } }, "required": [ "spec", "start_time", "end_time", "is_dynamic_creative", "revision", "complete_targeting" ], "additionalProperties": false }, "transparency": { "type": "object", "properties": { "beneficiary": { "type": [ "string", "null" ], "maxLength": 512 }, "payer": { "type": [ "string", "null" ], "maxLength": 512 }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Selected native transparency revision, separate from the budget/bid revision." } }, "required": [ "beneficiary", "payer", "revision" ], "additionalProperties": false }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "complete_snapshot": { "const": false }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "provider", "advertiser_id", "currency", "account_status", "campaign", "ad_group", "revision", "read_only", "content_is_untrusted", "complete_snapshot", "fetched_at", "limitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "include_conversion": { "type": "boolean", "default": false, "description": "Independent opt-in to selected native pixel/custom-conversion IDs/type and attribution event/window pairs. No rules, URLs, names or event data. Separate selected revision; not complete configuration, ownership, eligibility, effective attribution or event-ingestion proof." }, "include_audiences": { "type": "boolean", "default": false, "description": "Independent explicit opt-in to included/excluded custom-audience IDs. No names, members or rules. Separate selected revision; absent null differs from empty list. Does not prove complete targeting or eligibility." }, "include_targeting": { "type": "boolean", "default": false, "description": "Explicit opt-in to selected native targeting/schedule/dynamic-creative settings and a separate revision. Missing remains unknown and unmodeled values are suppressed." }, "include_transparency": { "type": "boolean", "default": false, "description": "Explicit opt-in to native beneficiary/payer values. Omission suppresses names; the money revision remains unchanged." } }, "required": [ "customer_id", "connection_id", "campaign_id", "ad_group_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/meta-ad-context": { "post": { "summary": "Inspect a selected bound Meta ad/campaign/ad-group/creative graph; seven GETs share a25-second native-read budget with final ad linkage recheck, not atomic or a write reconciliation proof", "operationId": "post__api_v1_projects_project_id_ads_meta_ad_context", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "metaads" }, "advertiser_id": { "type": "string" }, "currency": { "type": "string" }, "account_status": { "type": "integer" }, "campaign": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "type": [ "string", "null" ] }, "objective": { "type": [ "string", "null" ] }, "buying_type": { "type": [ "string", "null" ] }, "daily_budget_minor": { "type": [ "string", "null" ] }, "lifetime_budget_minor": { "type": [ "string", "null" ] }, "special_ad_categories": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "ad_group_budget_sharing": { "type": [ "boolean", "null" ] }, "scheduled_budget": { "type": [ "boolean", "null" ] } }, "required": [ "id", "status", "objective", "buying_type", "daily_budget_minor", "lifetime_budget_minor", "special_ad_categories", "ad_group_budget_sharing", "scheduled_budget" ], "additionalProperties": false }, "ad_group": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "type": [ "string", "null" ] }, "daily_budget_minor": { "type": [ "string", "null" ] }, "lifetime_budget_minor": { "type": [ "string", "null" ] }, "bid_amount_minor": { "type": [ "string", "null" ] }, "bid_strategy": { "type": [ "string", "null" ] }, "billing_event": { "type": [ "string", "null" ] }, "optimization_goal": { "type": [ "string", "null" ] }, "destination_type": { "type": [ "string", "null" ] }, "end_time": { "type": [ "string", "null" ] }, "scheduled_budget": { "type": [ "boolean", "null" ] }, "has_delivery_schedule": { "type": [ "boolean", "null" ] }, "pacing_type": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] } }, "required": [ "id", "campaign_id", "status", "daily_budget_minor", "lifetime_budget_minor", "bid_amount_minor", "bid_strategy", "billing_event", "optimization_goal", "destination_type", "end_time", "scheduled_budget", "has_delivery_schedule", "pacing_type" ], "additionalProperties": false }, "conversion": { "type": "object", "properties": { "promoted_object": { "anyOf": [ { "type": "object", "properties": { "pixel_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, { "type": "null" } ] }, "custom_conversion_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, { "type": "null" } ] }, "custom_event_type": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$" }, { "type": "null" } ] } }, "required": [ "pixel_id", "custom_conversion_id", "custom_event_type" ], "additionalProperties": false }, { "type": "null" } ] }, "attribution_spec": { "anyOf": [ { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "object", "properties": { "event_type": { "anyOf": [ { "type": "string", "pattern": "^[A-Z][A-Z0-9_]{0,99}$" }, { "type": "null" } ] }, "window_days": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 2147483647 } }, "required": [ "event_type", "window_days" ], "additionalProperties": false } }, { "type": "null" } ] }, "complete_configuration": { "const": false }, "native_eligibility_verified": { "const": false }, "effective_attribution_verified": { "const": false }, "event_ingestion_verified": { "const": false }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "promoted_object", "attribution_spec", "complete_configuration", "native_eligibility_verified", "effective_attribution_verified", "event_ingestion_verified", "revision" ], "additionalProperties": false }, "audience_targeting": { "type": "object", "properties": { "included_ids": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "maxItems": 100, "uniqueItems": true }, "excluded_ids": { "type": [ "array", "null" ], "items": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "maxItems": 100, "uniqueItems": true }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "complete_targeting": { "const": false } }, "required": [ "included_ids", "excluded_ids", "revision", "complete_targeting" ], "additionalProperties": false }, "targeting": { "type": "object", "properties": { "spec": { "anyOf": [ { "type": "object", "properties": { "age_min": { "type": [ "integer", "null" ], "minimum": 13, "maximum": 65 }, "age_max": { "type": [ "integer", "null" ], "minimum": 13, "maximum": 65 }, "genders": { "anyOf": [ { "type": "array", "maxItems": 2, "uniqueItems": true, "items": { "enum": [ 1, 2 ] } }, { "type": "null" } ] }, "geo_locations": { "anyOf": [ { "type": "object", "properties": { "countries": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 300, "uniqueItems": true }, { "type": "null" } ] }, "regions": { "anyOf": [ { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "country": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Observed native country label, not independently resolved geographic country_code." } }, "required": [ "key", "country" ], "additionalProperties": false } }, { "type": "null" } ] }, "cities": { "anyOf": [ { "type": "array", "maxItems": 250, "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "country": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Observed native country label, not independently resolved geographic country_code." }, "radius": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "distance_unit": { "enum": [ "mile", "kilometer", null ] }, "region_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, { "type": "null" } ] } }, "required": [ "key", "country", "radius", "distance_unit", "region_id" ], "additionalProperties": false } }, { "type": "null" } ] }, "location_types": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] } }, "required": [ "countries", "regions", "cities", "location_types" ], "additionalProperties": false }, { "type": "null" } ] }, "excluded_geo_locations": { "anyOf": [ { "type": "object", "properties": { "countries": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "maxItems": 300, "uniqueItems": true }, { "type": "null" } ] }, "regions": { "anyOf": [ { "type": "array", "maxItems": 200, "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "country": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Observed native country label, not independently resolved geographic country_code." } }, "required": [ "key", "country" ], "additionalProperties": false } }, { "type": "null" } ] }, "cities": { "anyOf": [ { "type": "array", "maxItems": 250, "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "country": { "type": [ "string", "null" ], "maxLength": 1000, "description": "Observed native country label, not independently resolved geographic country_code." }, "radius": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 9007199254740991 }, "distance_unit": { "enum": [ "mile", "kilometer", null ] }, "region_id": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, { "type": "null" } ] } }, "required": [ "key", "country", "radius", "distance_unit", "region_id" ], "additionalProperties": false } }, { "type": "null" } ] }, "location_types": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] } }, "required": [ "countries", "regions", "cities", "location_types" ], "additionalProperties": false }, { "type": "null" } ] }, "publisher_platforms": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "facebook_positions": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "instagram_positions": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "effective_publisher_platforms": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "effective_facebook_positions": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "effective_instagram_positions": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "device_platforms": { "anyOf": [ { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,99}$" }, "maxItems": 50, "uniqueItems": true }, { "type": "null" } ] }, "targeting_automation": { "anyOf": [ { "type": "object", "properties": { "advantage_audience": { "enum": [ 0, 1, null ] } }, "required": [ "advantage_audience" ], "additionalProperties": false }, { "type": "null" } ] }, "unmodeled_fields": { "type": "array", "maxItems": 200, "uniqueItems": true, "items": { "type": "string" }, "description": "Field paths only; unmodeled values and geographic display names are suppressed. Empty does not imply complete effective targeting." } }, "required": [ "age_min", "age_max", "genders", "geo_locations", "excluded_geo_locations", "publisher_platforms", "facebook_positions", "instagram_positions", "effective_publisher_platforms", "effective_facebook_positions", "effective_instagram_positions", "device_platforms", "targeting_automation", "unmodeled_fields" ], "additionalProperties": false }, { "type": "null" } ] }, "start_time": { "type": [ "string", "null" ], "format": "date-time" }, "end_time": { "type": [ "string", "null" ], "format": "date-time" }, "is_dynamic_creative": { "type": [ "boolean", "null" ] }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Separate selected-targeting revision, not a budget/bid precondition or activation approval." }, "complete_targeting": { "const": false } }, "required": [ "spec", "start_time", "end_time", "is_dynamic_creative", "revision", "complete_targeting" ], "additionalProperties": false }, "transparency": { "type": "object", "properties": { "beneficiary": { "type": [ "string", "null" ], "maxLength": 512 }, "payer": { "type": [ "string", "null" ], "maxLength": 512 }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Selected native transparency revision, separate from the budget/bid revision." } }, "required": [ "beneficiary", "payer", "revision" ], "additionalProperties": false }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "complete_snapshot": { "const": false }, "fetched_at": { "type": "string", "format": "date-time" }, "limitations": { "type": "array", "items": { "type": "string" } }, "ad": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "type": [ "string", "null" ] }, "configured_status": { "type": [ "string", "null" ] }, "effective_status": { "type": [ "string", "null" ] } }, "required": [ "id", "campaign_id", "ad_group_id", "creative_id", "status", "configured_status", "effective_status" ], "additionalProperties": false }, "creative": { "type": "object", "properties": { "id": { "type": "string" }, "account_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "kind": { "const": "creative" }, "image_hash": { "type": [ "string", "null" ] }, "object_story_id": { "type": [ "string", "null" ] }, "effective_object_story_id": { "type": [ "string", "null" ] }, "video_id": { "type": [ "string", "null" ] }, "object_type": { "type": [ "string", "null" ] }, "body": { "anyOf": [ { "type": "object", "properties": { "text": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "link_url": { "type": [ "string", "null" ] }, "story": { "anyOf": [ { "type": "object", "properties": { "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "page_id": { "type": [ "string", "null" ] }, "video_data": { "type": "object", "properties": { "video_id": { "type": [ "string", "null" ] }, "image_hash": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "link_description": { "type": [ "string", "null" ] }, "call_to_action": { "anyOf": [ { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] } }, "required": [ "type", "link" ], "additionalProperties": false }, { "type": "null" } ] }, "unmodeled_fields": { "type": "array", "maxItems": 128, "items": { "type": "string" }, "description": "Field paths only; values and native poster/media URLs are suppressed. Not a complete variant/usage inventory." } }, "required": [ "video_id", "image_hash", "message", "title", "link_description", "call_to_action", "unmodeled_fields" ], "additionalProperties": false }, "link_data": { "anyOf": [ { "type": "object", "properties": { "image_hash": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "call_to_action": { "anyOf": [ { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] } }, "required": [ "type", "link" ], "additionalProperties": false }, { "type": "null" } ] }, "cards": { "anyOf": [ { "type": "array", "maxItems": 10, "items": { "type": "object", "properties": { "image_hash": { "type": [ "string", "null" ] }, "video_id": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "call_to_action": { "anyOf": [ { "type": "object", "properties": { "type": { "type": [ "string", "null" ] }, "link": { "type": [ "string", "null" ] } }, "required": [ "type", "link" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "image_hash", "video_id", "link", "headline", "description", "call_to_action" ], "additionalProperties": false } }, { "type": "null" } ] }, "multi_share_optimized": { "type": [ "boolean", "null" ] }, "multi_share_end_card": { "type": [ "boolean", "null" ] } }, "required": [ "image_hash", "link", "message", "headline", "description", "call_to_action", "cards", "multi_share_optimized", "multi_share_end_card" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "page_id", "link_data" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "text", "title", "link_url", "story" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "account_id", "name", "status", "revision", "kind", "image_hash", "object_story_id", "effective_object_story_id", "video_id", "object_type", "body" ], "additionalProperties": false }, "configuration_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Original selected budget/bid revision, independent of the graph revision." } }, "required": [ "provider", "advertiser_id", "currency", "account_status", "campaign", "ad_group", "revision", "read_only", "content_is_untrusted", "complete_snapshot", "fetched_at", "limitations", "ad", "creative", "configuration_revision" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "include_conversion": { "type": "boolean", "default": false, "description": "Independent opt-in to selected native pixel/custom-conversion IDs/type and attribution event/window pairs. No rules, URLs, names or event data. Separate selected revision; not complete configuration, ownership, eligibility, effective attribution or event-ingestion proof." }, "include_audiences": { "type": "boolean", "default": false, "description": "Independent explicit opt-in to included/excluded custom-audience IDs. No names, members or rules. Separate selected revision; absent null differs from empty list. Does not prove complete targeting or eligibility." }, "include_targeting": { "type": "boolean", "default": false, "description": "Explicit opt-in to selected native targeting/schedule/dynamic-creative settings and a separate revision. Missing remains unknown and unmodeled values are suppressed." }, "include_transparency": { "type": "boolean", "default": false, "description": "Explicit opt-in to native beneficiary/payer values. Omission suppresses names; the money revision remains unchanged." }, "ad_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "include_body": { "type": "boolean", "default": false, "description": "Explicit opt-in to selected creative text, links and story fields; untrusted content." } }, "required": [ "customer_id", "connection_id", "campaign_id", "ad_group_id", "ad_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/operations/query": { "post": { "summary": "List bounded retained operation status metadata for one customer/connection, newest first. Defaults to unresolved work; no native request, payload/receipt content, upload capability or acknowledgment note. Caller/query-bound cursor expires after15minutes; changing statuses and retention prevent snapshot/archive guarantees.", "operationId": "post__api_v1_projects_project_id_ads_operations_query", "x-required-scope": "ads:operations:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "family": { "const": "ads" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,99}$" }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0 }, "error_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "customer_id", "connection_id", "action", "status", "attempts", "error_code", "created_at", "updated_at", "acknowledged_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "read_only": { "const": true }, "complete_snapshot": { "const": false } }, "required": [ "family", "data", "next_cursor", "read_only", "complete_snapshot" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "view": { "enum": [ "unresolved", "all" ], "default": "unresolved" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "customer_id", "connection_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/email/operations/query": { "post": { "summary": "List bounded retained operation status metadata for one customer/connection, newest first. Defaults to unresolved work; no native request, payload/receipt content, upload capability or acknowledgment note. Caller/query-bound cursor expires after15minutes; changing statuses and retention prevent snapshot/archive guarantees.", "operationId": "post__api_v1_projects_project_id_email_operations_query", "x-required-scope": "email:operations:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "family": { "const": "email" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,99}$" }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0 }, "error_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "customer_id", "connection_id", "action", "status", "attempts", "error_code", "created_at", "updated_at", "acknowledged_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "read_only": { "const": true }, "complete_snapshot": { "const": false } }, "required": [ "family", "data", "next_cursor", "read_only", "complete_snapshot" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "view": { "enum": [ "unresolved", "all" ], "default": "unresolved" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "customer_id", "connection_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/inbox/operations/query": { "post": { "summary": "List bounded retained operation status metadata for one customer/connection, newest first. Defaults to unresolved work; no native request, payload/receipt content, upload capability or acknowledgment note. Caller/query-bound cursor expires after15minutes; changing statuses and retention prevent snapshot/archive guarantees.", "operationId": "post__api_v1_projects_project_id_inbox_operations_query", "x-required-scope": "inbox:operations:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "family": { "const": "inbox" }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,99}$" }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0 }, "error_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "customer_id", "connection_id", "action", "status", "attempts", "error_code", "created_at", "updated_at", "acknowledged_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] }, "read_only": { "const": true }, "complete_snapshot": { "const": false } }, "required": [ "family", "data", "next_cursor", "read_only", "complete_snapshot" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "view": { "enum": [ "unresolved", "all" ], "default": "unresolved" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "customer_id", "connection_id" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/operations": { "post": { "summary": "Queue explicitly confirmed known paused Meta entity archival (exact parents, current PAUSED status, one ARCHIVED update; native acceptance only, no descendant inventory or erasure) or Meta image/creative deletion, both with a connection-wide unresolved-work barrier, or verified private MP4 ad-video upload (16 bytes–20MiB; returned ID does not prove processing), private-image upload/new single-image or reviewed2..10-card image-carousel creative/paused ad (6500UTF8bytes configuration maximum; preserve_card_order:true requests native optimization/end-card false; presentation not guaranteed), existing entity status changes or paused Meta traffic campaign/ad-set creation or existing owned-post creative/paused-ad creation or atomic paused Google Search graph or Search daily budget/manual CPC/existing standard Maximize Clicks ceiling edit and keyword lifecycle or reviewed Meta ad-group budget/bid edits; expires after15minutes; explicit spend authority required to enable", "operationId": "post__api_v1_projects_project_id_ads_operations", "x-required-scope": "ads:write; private-image/video upload also requires media:write; enabling, editing budgets/bids or any keyword action also requires ads:spend; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9_.:-]+$" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "replayed": { "type": "boolean" } }, "required": [ "id", "status", "replayed" ], "additionalProperties": false }, "delivery_confirmed": { "const": false } }, "required": [ "operation", "delivery_confirmed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "archive_meta_entity" }, "entity_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?![\\s\\S])" }, "resource": { "enum": [ "campaign", "ad_group", "ad" ] }, "expected_campaign_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?![\\s\\S])" }, "expected_ad_group_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?![\\s\\S])" }, "expected_status": { "const": "paused" }, "confirm_archive": { "const": true }, "confirm_ads_may_be_affected": { "const": true }, "spend_authorized": { "const": false, "default": false } }, "required": [ "customer_id", "connection_id", "action", "entity_id", "resource", "expected_status", "confirm_archive", "confirm_ads_may_be_affected" ], "additionalProperties": false, "oneOf": [ { "properties": { "resource": { "const": "campaign" } }, "not": { "anyOf": [ { "required": [ "expected_campaign_id" ] }, { "required": [ "expected_ad_group_id" ] } ] } }, { "properties": { "resource": { "const": "ad_group" } }, "required": [ "expected_campaign_id" ], "not": { "required": [ "expected_ad_group_id" ] } }, { "properties": { "resource": { "const": "ad" } }, "required": [ "expected_campaign_id", "expected_ad_group_id" ] } ] }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "confirm_delete": { "const": true }, "confirm_ads_may_be_affected": { "const": true }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "delete_meta_ad_image" }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "required": [ "customer_id", "connection_id", "expected_revision", "confirm_delete", "confirm_ads_may_be_affected", "action", "image_hash" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "confirm_delete": { "const": true }, "confirm_ads_may_be_affected": { "const": true }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "delete_meta_ad_creative" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" } }, "required": [ "customer_id", "connection_id", "expected_revision", "confirm_delete", "confirm_ads_may_be_affected", "action", "creative_id" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "upload_meta_ad_image" }, "media_id": { "type": "string", "format": "uuid" }, "expected_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "spend_authorized": { "const": false, "default": false } }, "required": [ "customer_id", "connection_id", "action", "media_id", "expected_sha256" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "upload_meta_ad_video" }, "media_id": { "type": "string", "format": "uuid" }, "expected_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "spend_authorized": { "const": false, "default": false } }, "required": [ "customer_id", "connection_id", "action", "media_id", "expected_sha256" ], "additionalProperties": false }, { "type": "object", "properties": { "placement": { "enum": [ "facebook_feed", "instagram_feed" ] }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "link_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "headline": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 200 }, "call_to_action": { "const": "learn_more" }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "create_video_creative" }, "video_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "video_reference": { "type": "string", "minLength": 1, "maxLength": 6500, "description": "Encrypted15-minute advertiser-library page locator bound to the current connection credential. Freshly rechecked before video creative/ad actions; not write authorization or exclusive ownership proof." } }, "required": [ "customer_id", "connection_id", "page_connection_id", "name", "image_hash", "link_url", "message", "call_to_action", "action", "placement", "video_id", "video_reference" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "placement": { "const": "instagram_feed" } }, "required": [ "placement" ] }, "then": { "required": [ "instagram_user_id" ], "not": { "anyOf": [ { "required": [ "headline" ] }, { "required": [ "description" ] } ] } }, "else": { "required": [ "headline" ], "not": { "required": [ "instagram_user_id" ] } } } ] }, { "type": "object", "properties": { "placement": { "enum": [ "facebook_feed", "instagram_feed" ] }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "link_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "headline": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 200 }, "call_to_action": { "const": "learn_more" }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "create_video_ad" }, "video_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "video_reference": { "type": "string", "minLength": 1, "maxLength": 6500, "description": "Encrypted15-minute advertiser-library page locator bound to the current connection credential. Freshly rechecked before video creative/ad actions; not write authorization or exclusive ownership proof." }, "expected_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "const": "paused" } }, "required": [ "customer_id", "connection_id", "page_connection_id", "name", "image_hash", "link_url", "message", "call_to_action", "action", "placement", "video_id", "video_reference", "campaign_id", "ad_group_id", "creative_id", "status" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "placement": { "const": "instagram_feed" } }, "required": [ "placement" ] }, "then": { "required": [ "instagram_user_id" ], "not": { "anyOf": [ { "required": [ "headline" ] }, { "required": [ "description" ] } ] } }, "else": { "required": [ "headline" ], "not": { "required": [ "instagram_user_id" ] } } } ] }, { "type": "object", "properties": { "placement": { "enum": [ "facebook_feed", "instagram_feed" ] }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "link_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "headline": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 200 }, "call_to_action": { "const": "learn_more" }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "create_image_creative" } }, "required": [ "customer_id", "connection_id", "page_connection_id", "name", "image_hash", "link_url", "message", "call_to_action", "action" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "placement": { "const": "instagram_feed" } }, "required": [ "placement" ] }, "then": { "required": [ "instagram_user_id" ], "not": { "anyOf": [ { "required": [ "headline" ] }, { "required": [ "description" ] } ] } }, "else": { "not": { "required": [ "instagram_user_id" ] }, "required": [ "headline" ] } } ] }, { "type": "object", "properties": { "placement": { "enum": [ "facebook_feed", "instagram_feed" ] }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "link_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "headline": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 200 }, "call_to_action": { "const": "learn_more" }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "create_image_ad" }, "expected_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "status": { "const": "paused" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" } }, "required": [ "customer_id", "connection_id", "page_connection_id", "name", "image_hash", "link_url", "message", "call_to_action", "action", "status", "creative_id", "campaign_id", "ad_group_id" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "placement": { "const": "instagram_feed" } }, "required": [ "placement" ] }, "then": { "required": [ "instagram_user_id" ], "not": { "anyOf": [ { "required": [ "headline" ] }, { "required": [ "description" ] } ] } }, "else": { "not": { "required": [ "instagram_user_id" ] }, "required": [ "headline" ] } } ] }, { "type": "object", "properties": { "placement": { "enum": [ "facebook_feed", "instagram_feed" ] }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "link_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "call_to_action": { "const": "learn_more" }, "spend_authorized": { "const": false, "default": false }, "cards": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "type": "object", "properties": { "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "link_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 }, "headline": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "image_hash", "link_url", "headline" ], "additionalProperties": false } }, "preserve_card_order": { "const": true }, "action": { "const": "create_carousel_creative" } }, "required": [ "customer_id", "connection_id", "page_connection_id", "name", "link_url", "message", "call_to_action", "cards", "preserve_card_order", "action" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "placement": { "const": "instagram_feed" } }, "required": [ "placement" ] }, "then": { "required": [ "instagram_user_id" ], "properties": { "cards": { "items": { "not": { "required": [ "description" ] } } } } }, "else": { "not": { "required": [ "instagram_user_id" ] } } } ] }, { "type": "object", "properties": { "placement": { "enum": [ "facebook_feed", "instagram_feed" ] }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "link_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 }, "message": { "type": "string", "minLength": 1, "maxLength": 2000 }, "call_to_action": { "const": "learn_more" }, "spend_authorized": { "const": false, "default": false }, "cards": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "type": "object", "properties": { "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "link_url": { "type": "string", "format": "uri", "pattern": "^https://", "maxLength": 2000 }, "headline": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "image_hash", "link_url", "headline" ], "additionalProperties": false } }, "preserve_card_order": { "const": true }, "action": { "const": "create_carousel_ad" }, "expected_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "const": "paused" } }, "required": [ "customer_id", "connection_id", "page_connection_id", "name", "link_url", "message", "call_to_action", "cards", "preserve_card_order", "action", "creative_id", "campaign_id", "ad_group_id", "status" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "placement": { "const": "instagram_feed" } }, "required": [ "placement" ] }, "then": { "required": [ "instagram_user_id" ], "properties": { "cards": { "items": { "not": { "required": [ "description" ] } } } } }, "else": { "not": { "required": [ "instagram_user_id" ] } } } ] }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "expected_bid_strategy": { "enum": [ "LOWEST_COST_WITHOUT_CAP", "LOWEST_COST_WITH_BID_CAP" ] }, "spend_authorized": { "const": true }, "action": { "const": "update_meta_ad_group_budget" }, "expected_daily_budget_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "daily_budget_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "expected_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "campaign_id", "ad_group_id", "currency", "expected_revision", "expected_campaign_status", "expected_ad_group_status", "expected_bid_strategy", "spend_authorized", "action", "expected_daily_budget_minor", "daily_budget_minor" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "expected_bid_strategy": { "enum": [ "LOWEST_COST_WITHOUT_CAP", "LOWEST_COST_WITH_BID_CAP" ] }, "spend_authorized": { "const": true }, "action": { "const": "update_meta_ad_group_lifetime_budget" }, "expected_lifetime_budget_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "lifetime_budget_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$", "description": "Total budget for the unchanged existing schedule, not remaining or incremental spend." }, "expected_end_time": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$" }, "expected_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "campaign_id", "ad_group_id", "currency", "expected_revision", "expected_campaign_status", "expected_ad_group_status", "expected_bid_strategy", "spend_authorized", "action", "expected_lifetime_budget_minor", "lifetime_budget_minor", "expected_end_time" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "expected_bid_strategy": { "const": "LOWEST_COST_WITH_BID_CAP" }, "spend_authorized": { "const": true }, "action": { "const": "update_meta_ad_group_bid" }, "expected_bid_amount_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "bid_amount_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "expected_end_time": { "type": "string", "format": "date-time", "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z$", "description": "Explicitly selects lifetime-budget bid editing. Copy the exact canonical UTC end_time from fresh context; omission retains daily-budget behavior. The existing total budget and end date are never changed. At least60seconds must remain after the final authority wait." }, "expected_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "campaign_id", "ad_group_id", "currency", "expected_revision", "expected_campaign_status", "expected_ad_group_status", "expected_bid_strategy", "spend_authorized", "action", "expected_bid_amount_minor", "bid_amount_minor" ], "additionalProperties": false }, { "type": "object", "properties": { "expected_bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ], "description": "Omission preserves manual CPC. Explicit automated strategy requires a matching standard nonportfolio campaign, null current/proposed keyword CPC and no keyword bid action." }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "action": { "const": "create_google_search_keyword" }, "keyword": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 80 }, "match_type": { "enum": [ "exact", "phrase", "broad" ] }, "negative": { "type": "boolean" } }, "required": [ "text", "match_type", "negative" ], "additionalProperties": false }, "cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "ad_group_id", "expected_ad_group_status", "action", "keyword", "cpc_bid_micros" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "expected_bidding_strategy": { "enum": [ "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] } }, "required": [ "expected_bidding_strategy" ] }, "then": { "properties": { "action": { "not": { "const": "update_google_search_keyword_bid" } }, "cpc_bid_micros": { "type": "null" }, "expected_cpc_bid_micros": { "type": "null" } } } }, { "if": { "properties": { "keyword": { "properties": { "negative": { "const": true } }, "required": [ "negative" ] } }, "required": [ "keyword" ] }, "then": { "properties": { "cpc_bid_micros": { "type": "null" } } } } ] }, { "type": "object", "properties": { "expected_bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ], "description": "Omission preserves manual CPC. Explicit automated strategy requires a matching standard nonportfolio campaign, null current/proposed keyword CPC and no keyword bid action." }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "criterion_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_keyword": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 80 }, "match_type": { "enum": [ "exact", "phrase", "broad" ] }, "negative": { "type": "boolean" } }, "required": [ "text", "match_type", "negative" ], "additionalProperties": false }, "expected_keyword_status": { "enum": [ "enabled", "paused" ] }, "expected_cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "action": { "const": "replace_google_search_keyword" }, "keyword": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 80 }, "match_type": { "enum": [ "exact", "phrase", "broad" ] }, "negative": { "type": "boolean" } }, "required": [ "text", "match_type", "negative" ], "additionalProperties": false }, "cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "confirm_replace": { "const": true } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "ad_group_id", "expected_ad_group_status", "criterion_id", "expected_keyword", "expected_keyword_status", "expected_cpc_bid_micros", "action", "keyword", "cpc_bid_micros", "confirm_replace" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "expected_bidding_strategy": { "enum": [ "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] } }, "required": [ "expected_bidding_strategy" ] }, "then": { "properties": { "action": { "not": { "const": "update_google_search_keyword_bid" } }, "cpc_bid_micros": { "type": "null" }, "expected_cpc_bid_micros": { "type": "null" } } } }, { "if": { "properties": { "keyword": { "properties": { "negative": { "const": true } }, "required": [ "negative" ] } }, "required": [ "keyword" ] }, "then": { "properties": { "cpc_bid_micros": { "type": "null" } } } }, { "if": { "properties": { "expected_keyword": { "properties": { "negative": { "const": true } }, "required": [ "negative" ] } } }, "then": { "properties": { "expected_cpc_bid_micros": { "type": "null" }, "expected_keyword_status": { "const": "enabled" } } } } ] }, { "type": "object", "properties": { "expected_bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ], "description": "Omission preserves manual CPC. Explicit automated strategy requires a matching standard nonportfolio campaign, null current/proposed keyword CPC and no keyword bid action." }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "criterion_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_keyword": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 80 }, "match_type": { "enum": [ "exact", "phrase", "broad" ] }, "negative": { "type": "boolean" } }, "required": [ "text", "match_type", "negative" ], "additionalProperties": false }, "expected_keyword_status": { "enum": [ "enabled", "paused" ] }, "expected_cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "action": { "const": "remove_google_search_keyword" }, "confirm_remove": { "const": true } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "ad_group_id", "expected_ad_group_status", "criterion_id", "expected_keyword", "expected_keyword_status", "expected_cpc_bid_micros", "action", "confirm_remove" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "expected_bidding_strategy": { "enum": [ "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] } }, "required": [ "expected_bidding_strategy" ] }, "then": { "properties": { "action": { "not": { "const": "update_google_search_keyword_bid" } }, "cpc_bid_micros": { "type": "null" }, "expected_cpc_bid_micros": { "type": "null" } } } }, { "if": { "properties": { "expected_keyword": { "properties": { "negative": { "const": true } }, "required": [ "negative" ] } } }, "then": { "properties": { "expected_cpc_bid_micros": { "type": "null" }, "expected_keyword_status": { "const": "enabled" } } } } ] }, { "type": "object", "properties": { "expected_bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ], "description": "Omission preserves manual CPC. Explicit automated strategy requires a matching standard nonportfolio campaign, null current/proposed keyword CPC and no keyword bid action." }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "criterion_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_keyword": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 80 }, "match_type": { "enum": [ "exact", "phrase", "broad" ] }, "negative": { "type": "boolean" } }, "required": [ "text", "match_type", "negative" ], "additionalProperties": false }, "expected_keyword_status": { "enum": [ "enabled", "paused" ] }, "expected_cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "action": { "const": "set_google_search_keyword_status" }, "status": { "enum": [ "enabled", "paused" ] } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "ad_group_id", "expected_ad_group_status", "criterion_id", "expected_keyword", "expected_keyword_status", "expected_cpc_bid_micros", "action", "status" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "expected_bidding_strategy": { "enum": [ "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] } }, "required": [ "expected_bidding_strategy" ] }, "then": { "properties": { "action": { "not": { "const": "update_google_search_keyword_bid" } }, "cpc_bid_micros": { "type": "null" }, "expected_cpc_bid_micros": { "type": "null" } } } }, { "if": { "properties": { "expected_keyword": { "properties": { "negative": { "const": true } }, "required": [ "negative" ] } } }, "then": { "properties": { "expected_cpc_bid_micros": { "type": "null" }, "expected_keyword_status": { "const": "enabled" } } } }, { "properties": { "expected_keyword": { "properties": { "negative": { "const": false } } } } } ] }, { "type": "object", "properties": { "expected_bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ], "description": "Omission preserves manual CPC. Explicit automated strategy requires a matching standard nonportfolio campaign, null current/proposed keyword CPC and no keyword bid action." }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "criterion_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_keyword": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 80 }, "match_type": { "enum": [ "exact", "phrase", "broad" ] }, "negative": { "type": "boolean" } }, "required": [ "text", "match_type", "negative" ], "additionalProperties": false }, "expected_keyword_status": { "enum": [ "enabled", "paused" ] }, "expected_cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "action": { "const": "update_google_search_keyword_bid" }, "cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "ad_group_id", "expected_ad_group_status", "criterion_id", "expected_keyword", "expected_keyword_status", "expected_cpc_bid_micros", "action", "cpc_bid_micros" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "expected_bidding_strategy": { "enum": [ "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] } }, "required": [ "expected_bidding_strategy" ] }, "then": { "properties": { "action": { "not": { "const": "update_google_search_keyword_bid" } }, "cpc_bid_micros": { "type": "null" }, "expected_cpc_bid_micros": { "type": "null" } } } }, { "if": { "properties": { "expected_keyword": { "properties": { "negative": { "const": true } }, "required": [ "negative" ] } } }, "then": { "properties": { "expected_cpc_bid_micros": { "type": "null" }, "expected_keyword_status": { "const": "enabled" } } } }, { "properties": { "expected_keyword": { "properties": { "negative": { "const": false } } } } } ] }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "set_status" }, "resource": { "enum": [ "campaign", "ad_group", "ad" ] }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "expected_status": { "enum": [ "enabled", "paused" ] }, "status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "type": "boolean", "default": false } }, "required": [ "customer_id", "connection_id", "action", "resource", "entity_id", "expected_status", "status" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "status": { "const": "enabled" } } }, "then": { "required": [ "spend_authorized" ], "properties": { "spend_authorized": { "const": true } } }, "else": { "properties": { "spend_authorized": { "const": false } } } }, { "if": { "properties": { "resource": { "not": { "const": "ad" } } } }, "then": { "not": { "required": [ "ad_group_id" ] } } } ] }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^\\x00-\\x1f\\x7f]+$" }, "status": { "const": "paused" }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "create_campaign" }, "objective": { "enum": [ "traffic", "sales" ] }, "special_category": { "const": "none" } }, "required": [ "customer_id", "connection_id", "name", "status", "action", "objective", "special_category" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "minLength": 1, "maxLength": 255, "pattern": "^[^\\x00-\\x1f\\x7f]+$" }, "status": { "const": "paused" }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "create_ad_group" }, "conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true }, "pixel_reference": { "type": "string", "minLength": 1, "maxLength": 6500 } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion", "pixel_reference" ], "additionalProperties": false }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "daily_budget_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "lifetime_budget_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$", "description": "Total for the fixed schedule, mutually exclusive with daily_budget_minor." }, "bidding": { "oneOf": [ { "type": "object", "properties": { "strategy": { "const": "lowest_cost" } }, "required": [ "strategy" ], "additionalProperties": false }, { "type": "object", "properties": { "strategy": { "const": "bid_cap" }, "bid_amount_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" } }, "required": [ "strategy", "bid_amount_minor" ], "additionalProperties": false } ], "description": "Optional reviewed strategy. Omission retains lowest cost without cap. A bid cap is an auction input in native account-currency minor units, not a daily/lifetime spend ceiling or delivery guarantee. Paused creation only; native eligibility remains required." }, "start_time": { "type": "string", "format": "date-time", "description": "At least60seconds into the future at execution" }, "end_time": { "type": "string", "format": "date-time", "description": "15minutes–90days after start" }, "transparency": { "type": "object", "properties": { "beneficiary": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Truthful caller-provided beneficiary; outer whitespace is trimmed. May be publicly displayed by Meta." }, "payer": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Truthful caller-provided payer; outer whitespace is trimmed. Maps to dsa_payor. Never inferred from account defaults." }, "confirm_public_disclosure": { "const": true } }, "required": [ "beneficiary", "payer", "confirm_public_disclosure" ], "additionalProperties": false }, "targeting": { "type": "object", "properties": { "countries": { "type": "array", "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "regions": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "description": "Keys must be unique regardless of country_code and re-resolve to their reviewed country before writing.", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,15}$", "description": "Exact native region key; numeric value must be <=9007199254740991." }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" } }, "required": [ "key", "country_code" ], "additionalProperties": false } }, "city": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[1-9][0-9]{0,15}$", "description": "Exact native city key; numeric value must be <=9007199254740991." }, "country_code": { "type": "string", "pattern": "^[A-Z]{2}$" }, "radius": { "type": "integer", "minimum": 10, "maximum": 80 }, "distance_unit": { "enum": [ "mile", "kilometer" ] } }, "required": [ "key", "country_code", "radius", "distance_unit" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "distance_unit": { "const": "mile" } } }, "then": { "properties": { "radius": { "minimum": 10, "maximum": 50 } } }, "else": { "properties": { "radius": { "minimum": 17, "maximum": 80 } } } } ] }, "audiences": { "type": "object", "properties": { "include": { "type": "array", "items": { "type": "object", "properties": { "audience_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "audience_reference": { "type": "string", "minLength": 1, "maxLength": 6500 } }, "required": [ "audience_id", "audience_reference" ], "additionalProperties": false }, "maxItems": 5, "default": [] }, "exclude": { "type": "array", "items": { "type": "object", "properties": { "audience_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "audience_reference": { "type": "string", "minLength": 1, "maxLength": 6500 } }, "required": [ "audience_id", "audience_reference" ], "additionalProperties": false }, "maxItems": 5, "default": [] } }, "required": [], "additionalProperties": false, "description": "1–5 unique audience IDs combined across disjoint include/exclude arrays, with encrypted15-minute references from this advertiser library. Entire canonical creation input <=6500UTF8bytes. Reread before PAUSED creation; edge membership is not eligibility, data rights, exclusive ownership or spending authority." }, "age_min": { "type": "integer", "minimum": 18, "maximum": 65 }, "age_max": { "type": "integer", "minimum": 18, "maximum": 65, "description": "Must be>=age_min;65means65+" }, "gender": { "enum": [ "all", "male", "female" ] }, "placements": { "enum": [ "facebook_feed", "instagram_feed" ] } }, "required": [ "age_min", "age_max", "gender", "placements" ], "additionalProperties": false, "oneOf": [ { "required": [ "countries" ] }, { "required": [ "regions" ] }, { "required": [ "city" ] } ], "description": "Exactly one geography: countries, region set or one city with an explicit radius. Native names are not accepted. No implicit country union." } }, "required": [ "customer_id", "connection_id", "name", "status", "action", "campaign_id", "currency", "start_time", "end_time", "targeting" ], "additionalProperties": false, "oneOf": [ { "required": [ "daily_budget_minor" ], "not": { "required": [ "lifetime_budget_minor" ] } }, { "required": [ "lifetime_budget_minor" ], "not": { "required": [ "daily_budget_minor" ] } } ] }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "post_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}_[1-9][0-9]{0,29}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\x00-\\x1f\\x7f]+$" }, "expected_post_revision": { "type": "string", "format": "date-time" }, "expected_link_url": { "type": "string", "format": "uri", "maxLength": 2000, "pattern": "^https://" }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "create_post_creative" } }, "required": [ "customer_id", "connection_id", "page_connection_id", "post_id", "name", "expected_post_revision", "expected_link_url", "action" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": "string", "format": "uuid" }, "post_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}_[1-9][0-9]{0,29}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 100, "pattern": "^[^\\x00-\\x1f\\x7f]+$" }, "expected_post_revision": { "type": "string", "format": "date-time" }, "expected_link_url": { "type": "string", "format": "uri", "maxLength": 2000, "pattern": "^https://" }, "spend_authorized": { "const": false, "default": false }, "action": { "const": "create_post_ad" }, "expected_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "status": { "const": "paused" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" } }, "required": [ "customer_id", "connection_id", "page_connection_id", "post_id", "name", "expected_post_revision", "expected_link_url", "action", "status", "creative_id", "campaign_id", "ad_group_id" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "create_google_search_campaign" }, "name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\x00-\\x1f\\x7f{}]+$" }, "ad_group_name": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[^\\x00-\\x1f\\x7f{}]+$" }, "status": { "const": "paused" }, "spend_authorized": { "const": false, "default": false }, "eu_political_advertising": { "const": "none" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "time_zone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Valid IANA time zone exactly matching the advertiser." }, "daily_budget_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ], "description": "Omission retains manual CPC; strategy changes are not implicit." }, "impression_share": { "type": "object", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ] }, "location_fraction_micros": { "type": "string", "pattern": "^(?:[1-9]\\d{0,5}|1000000)$", "description": "Canonical fraction micros1–1000000. 500000 means50%, not currency. Requested auction objective, not guaranteed delivery/share." } }, "required": [ "location", "location_fraction_micros" ], "additionalProperties": false }, "cpc_bid_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "target_cpa_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "target_roas": { "type": "number", "minimum": 0.01, "maximum": 1000, "description": "ROAS ratio, not percent;4.5 means450%. Techrace accepts0.01–1000. This is a bidding objective, not guaranteed return." }, "conversion_values_reviewed": { "const": true }, "conversion_goal_review": { "type": "object", "properties": { "revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "use_account_defaults": { "const": true }, "tracking_reviewed": { "const": true } }, "required": [ "revision", "use_account_defaults", "tracking_reviewed" ], "additionalProperties": false }, "start_date": { "type": "string", "format": "date", "pattern": "^20[0-9]{2}-[0-9]{2}-[0-9]{2}$" }, "end_date": { "type": "string", "format": "date", "pattern": "^20[0-9]{2}-[0-9]{2}-[0-9]{2}$" }, "targeting": { "type": "object", "properties": { "location_ids": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "language_ids": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "minItems": 1, "maxItems": 10, "uniqueItems": true }, "location_presence": { "const": "presence" } }, "required": [ "location_ids", "language_ids", "location_presence" ], "additionalProperties": false }, "keywords": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[^\\x00-\\x1f\\x7f{}]+$", "description": "Plain keyword, at most10 whitespace-delimited words." }, "match_type": { "enum": [ "exact", "phrase", "broad" ] }, "negative": { "type": "boolean", "default": false } }, "required": [ "text", "match_type" ], "additionalProperties": false } }, "ad": { "type": "object", "properties": { "final_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTPS public DNS destination; no credentials, port, fragment, whitespace or template. Not fetched by Techrace." }, "headlines": { "type": "array", "minItems": 3, "maxItems": 15, "uniqueItems": true, "items": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 30, "pattern": "^[^\\x00-\\x1f\\x7f{}]+$" }, { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Plain text without controls or customizer braces; trimmed; distinct text within each list." }, "pinned_field": { "enum": [ "HEADLINE_1", "HEADLINE_2", "HEADLINE_3" ] } }, "required": [ "text" ], "additionalProperties": false } ] }, "description": "Distinct normalized text; all three positions must be fillable from pins or distinct unpinned assets. Legacy strings remain unpinned." }, "descriptions": { "type": "array", "minItems": 2, "maxItems": 4, "uniqueItems": true, "items": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 90, "pattern": "^[^\\x00-\\x1f\\x7f{}]+$" }, { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 90, "description": "Plain text without controls or customizer braces; trimmed; distinct text within each list." }, "pinned_field": { "enum": [ "DESCRIPTION_1", "DESCRIPTION_2" ] } }, "required": [ "text" ], "additionalProperties": false } ] }, "description": "Distinct normalized text; both positions must be fillable from pins or distinct unpinned assets. Legacy strings remain unpinned." }, "path1": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,15}$" }, "path2": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,15}$" } }, "required": [ "final_url", "headlines", "descriptions" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "action", "name", "ad_group_name", "status", "eu_political_advertising", "currency", "time_zone", "daily_budget_micros", "start_date", "end_date", "targeting", "keywords", "ad" ], "additionalProperties": false, "oneOf": [ { "properties": { "bidding_strategy": { "const": "manual_cpc" } }, "required": [ "cpc_bid_micros" ], "not": { "anyOf": [ { "required": [ "impression_share" ] }, { "required": [ "target_roas" ] }, { "required": [ "conversion_values_reviewed" ] }, { "required": [ "cpc_bid_ceiling_micros" ] }, { "required": [ "target_cpa_micros" ] }, { "required": [ "conversion_goal_review" ] } ] } }, { "properties": { "bidding_strategy": { "const": "maximize_clicks" } }, "required": [ "bidding_strategy", "cpc_bid_ceiling_micros" ], "not": { "anyOf": [ { "required": [ "impression_share" ] }, { "required": [ "target_roas" ] }, { "required": [ "conversion_values_reviewed" ] }, { "required": [ "cpc_bid_micros" ] }, { "required": [ "target_cpa_micros" ] }, { "required": [ "conversion_goal_review" ] } ] } }, { "properties": { "bidding_strategy": { "const": "maximize_conversions" } }, "required": [ "bidding_strategy", "conversion_goal_review" ], "not": { "anyOf": [ { "required": [ "impression_share" ] }, { "required": [ "target_roas" ] }, { "required": [ "conversion_values_reviewed" ] }, { "required": [ "cpc_bid_micros" ] }, { "required": [ "cpc_bid_ceiling_micros" ] } ] } }, { "properties": { "bidding_strategy": { "const": "maximize_conversion_value" } }, "required": [ "bidding_strategy", "conversion_goal_review", "conversion_values_reviewed" ], "not": { "anyOf": [ { "required": [ "impression_share" ] }, { "required": [ "cpc_bid_micros" ] }, { "required": [ "cpc_bid_ceiling_micros" ] }, { "required": [ "target_cpa_micros" ] } ] } }, { "properties": { "bidding_strategy": { "const": "target_impression_share" } }, "required": [ "bidding_strategy", "impression_share", "cpc_bid_ceiling_micros" ], "not": { "anyOf": [ { "required": [ "cpc_bid_micros" ] }, { "required": [ "target_cpa_micros" ] }, { "required": [ "target_roas" ] }, { "required": [ "conversion_goal_review" ] }, { "required": [ "conversion_values_reviewed" ] } ] } } ], "description": "Atomic Google Ads v25 Search graph. All campaign/ad-group/ad delivery controls paused; one dedicated budget, standard Target Impression Share with explicit native location, fraction micros and CPC ceiling, manual CPC, standard Maximize Clicks with explicit positive CPC ceiling, or standard Maximize Conversions with freshly reviewed account-default goals and optional targetCPA, or Maximize Conversion Value with the same goal review, explicit conversion_values_reviewed:true and optional numeric target_roas ratio0.01–1000. No CPC/CPA fields in value mode; value measurement and returns are not certified. Positive/negative keywords, presence-only geo/language criteria. Start date after advertiser-local today; 1–90 inclusive days. At least one positive keyword, unique normalized (negative,match_type,text) tuples, path2 requires path1. Normalized JSON at most 6500 UTF-8 bytes. Average daily budget is not a hard spend cap. AI Max, text automation, URL expansion and non-Google Search networks off. Native policy and account settings still govern delivery; no campaign activation." }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "action": { "const": "update_google_search_budget" }, "budget_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_daily_budget_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "daily_budget_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "action", "budget_id", "expected_daily_budget_micros", "daily_budget_micros" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "action": { "const": "update_google_search_bid" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_ad_group_status": { "enum": [ "enabled", "paused" ] }, "expected_cpc_bid_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "cpc_bid_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "action", "ad_group_id", "expected_ad_group_status", "expected_cpc_bid_micros", "cpc_bid_micros" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "action": { "const": "update_google_search_click_ceiling" }, "expected_cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "action", "expected_cpc_bid_ceiling_micros", "cpc_bid_ceiling_micros" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "action": { "const": "update_google_search_impression_share" }, "expected_impression_share": { "type": "object", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ] }, "location_fraction_micros": { "type": "string", "pattern": "^(?:[1-9]\\d{0,5}|1000000)$", "description": "Canonical fraction micros1–1000000. 500000 means50%, not currency. Requested auction objective, not guaranteed delivery/share." }, "cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "location", "location_fraction_micros", "cpc_bid_ceiling_micros" ], "additionalProperties": false }, "impression_share": { "type": "object", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ] }, "location_fraction_micros": { "type": "string", "pattern": "^(?:[1-9]\\d{0,5}|1000000)$", "description": "Canonical fraction micros1–1000000. 500000 means50%, not currency. Requested auction objective, not guaranteed delivery/share." }, "cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "location", "location_fraction_micros", "cpc_bid_ceiling_micros" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "action", "expected_impression_share", "impression_share" ], "additionalProperties": false, "description": "Existing standard Search TARGET_IMPRESSION_SHARE, exact reviewed status/currency and complete native settings. Both ads:write and ads:spend required including no-ops, paused objects and reductions. Only three nested target leaves change; native outside edits can race prechecks. No strategy switch, activation, portfolio mutation or null/zero clearing." }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}(?![\\s\\S])" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "action": { "const": "replace_google_search_target" }, "criterion_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "expected_bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] }, "target_type": { "enum": [ "location", "language" ] }, "expected_target_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "target_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "confirm_replace": { "const": true } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "action", "criterion_id", "expected_bidding_strategy", "target_type", "expected_target_id", "target_id", "confirm_replace" ], "additionalProperties": false, "description": "Replace exactly one reviewed positive enabled criterion atomically; ads:write and ads:spend plus explicit confirmations. Exact old/new IDs, campaign/status/currency/standard strategy; location PRESENCE unchanged; nondefault bid modifiers refused. New criterion history does not inherit old history. No activation, budget change, native compare-and-swap or delivery guarantee." }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}(?![\\s\\S])" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "expected_bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] }, "action": { "const": "create_google_search_location_exclusion" }, "location_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "confirm_exclusion": { "const": true } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "expected_bidding_strategy", "action", "location_id", "confirm_exclusion" ], "additionalProperties": false, "description": "One reviewed negative location criterion request; requires ads:write and ads:spend, explicit confirmation and existing negative PRESENCE mode. Removal can broaden reach. Exact current campaign/currency/status/standard strategy; no native compare-and-swap, automatic replay or configuration/delivery guarantee. Creation needs an enabled constant and creation gate; removal binds the exact current criterion and expected constant." }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}(?![\\s\\S])" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "expected_bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] }, "action": { "const": "remove_google_search_location_exclusion" }, "criterion_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "expected_location_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "confirm_remove": { "const": true } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "expected_bidding_strategy", "action", "criterion_id", "expected_location_id", "confirm_remove" ], "additionalProperties": false, "description": "One reviewed negative location criterion request; requires ads:write and ads:spend, explicit confirmation and existing negative PRESENCE mode. Removal can broaden reach. Exact current campaign/currency/status/standard strategy; no native compare-and-swap, automatic replay or configuration/delivery guarantee. Creation needs an enabled constant and creation gate; removal binds the exact current criterion and expected constant." }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "action": { "const": "update_google_search_target_cpa" }, "expected_target_cpa_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ], "description": "Exact reviewed current target; explicit null means the target is absent/default zero on the verified standard campaign." }, "target_cpa_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ], "description": "Positive value adds/changes the reviewed target. Null requires clear_target:true and a positive expected target." }, "clear_target": { "const": true, "description": "Explicitly authorize removing only the reviewed target, preserving the strategy and budget." } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "action", "expected_target_cpa_micros", "target_cpa_micros" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "target_cpa_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "not": { "required": [ "clear_target" ] } }, { "required": [ "clear_target" ], "properties": { "target_cpa_micros": { "type": "null" }, "expected_target_cpa_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } } } ] } ] }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "expected_campaign_status": { "enum": [ "enabled", "paused" ] }, "spend_authorized": { "const": true }, "action": { "const": "update_google_search_target_roas" }, "expected_target_roas": { "anyOf": [ { "type": "number", "minimum": 0.01, "maximum": 1000 }, { "type": "null" } ], "description": "Exact reviewed current target; explicit null means the target is absent/default zero on the verified standard campaign." }, "target_roas": { "anyOf": [ { "type": "number", "minimum": 0.01, "maximum": 1000 }, { "type": "null" } ], "description": "Positive value adds/changes the reviewed target. Null requires clear_target:true and a positive expected target." }, "conversion_values_reviewed": { "const": true }, "clear_target": { "const": true, "description": "Explicitly authorize removing only the reviewed target, preserving the strategy and budget." } }, "required": [ "customer_id", "connection_id", "campaign_id", "currency", "expected_campaign_status", "spend_authorized", "action", "expected_target_roas", "target_roas", "conversion_values_reviewed" ], "additionalProperties": false, "allOf": [ { "oneOf": [ { "properties": { "target_roas": { "type": "number", "minimum": 0.01, "maximum": 1000 } }, "not": { "required": [ "clear_target" ] } }, { "required": [ "clear_target" ], "properties": { "target_roas": { "type": "null" }, "expected_target_roas": { "type": "number", "minimum": 0.01, "maximum": 1000 } } } ] } ] }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "update_google_search_ad_text" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Fresh query_google_search_context include_body:true revision; one paused ad association required." }, "headlines": { "type": "array", "minItems": 3, "maxItems": 15, "description": "Distinct normalized text; all three positions must have eligible assets.", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 30, "description": "Plain text without controls or customizer braces; trimmed; distinct text within each list." }, "pinned_field": { "enum": [ "HEADLINE_1", "HEADLINE_2", "HEADLINE_3" ] } }, "required": [ "text" ], "additionalProperties": false } }, "descriptions": { "type": "array", "minItems": 2, "maxItems": 4, "description": "Distinct normalized text; both positions must have eligible assets.", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 90, "description": "Plain text without controls or customizer braces; trimmed; distinct text within each list." }, "pinned_field": { "enum": [ "DESCRIPTION_1", "DESCRIPTION_2" ] } }, "required": [ "text" ], "additionalProperties": false } }, "spend_authorized": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "campaign_id", "ad_group_id", "ad_id", "expected_revision", "headlines", "descriptions", "spend_authorized" ], "additionalProperties": false } ] } } } } } }, "/api/v1/projects/{project_id}/ads/operations/{operation_id}": { "get": { "summary": "Read an advertiser operation without its encrypted request or acknowledgment note", "operationId": "get__api_v1_projects_project_id_ads_operations_operation_id_", "x-required-scope": "ads:operations:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "page_connection_id": { "type": [ "string", "null" ], "format": "uuid" }, "source_media_id": { "type": [ "string", "null" ], "format": "uuid" }, "action": { "enum": [ "archive_meta_entity", "delete_meta_ad_image", "delete_meta_ad_creative", "upload_meta_ad_image", "upload_meta_ad_video", "create_video_creative", "create_video_ad", "create_image_creative", "create_image_ad", "create_carousel_creative", "create_carousel_ad", "update_meta_ad_group_budget", "update_meta_ad_group_lifetime_budget", "update_meta_ad_group_bid", "create_google_search_keyword", "replace_google_search_keyword", "remove_google_search_keyword", "set_google_search_keyword_status", "update_google_search_keyword_bid", "set_status", "create_campaign", "create_ad_group", "create_post_creative", "create_post_ad", "create_google_search_campaign", "update_google_search_budget", "update_google_search_bid", "update_google_search_click_ceiling", "update_google_search_impression_share", "replace_google_search_target", "create_google_search_location_exclusion", "remove_google_search_location_exclusion", "update_google_search_target_cpa", "update_google_search_target_roas", "update_google_search_ad_text" ] }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "provider_data_erased_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Provider receipt deliberately removed under a scoped deletion request; operation status/idempotency remain." }, "attempts": { "type": "integer" }, "requires_spend": { "type": "boolean" }, "provider_receipt": { "anyOf": [ { "type": "object", "properties": { "resource": { "enum": [ "campaign", "ad_group", "ad" ] }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "requested_status": { "const": "archived" }, "native_archive_accepted": { "const": true }, "native_status_verified": { "const": false }, "descendants_inspected": { "const": false }, "native_erasure_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "delivery_confirmed": { "const": false } }, "required": [ "resource", "entity_id", "requested_status", "native_archive_accepted", "native_status_verified", "descendants_inspected", "native_erasure_confirmed", "atomic_precondition", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "enum": [ "image", "creative" ] }, "entity_id": { "type": "string" }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "reviewed_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "native_deletion_accepted": { "const": true }, "native_erasure_confirmed": { "const": false }, "asset_usage_checked": { "const": false }, "atomic_precondition": { "const": false }, "delivery_confirmed": { "const": false } }, "required": [ "resource", "entity_id", "reviewed_revision", "native_deletion_accepted", "native_erasure_confirmed", "asset_usage_checked", "atomic_precondition", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "requested_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "native_conversion_verified": { "const": false }, "placement": { "const": "instagram_feed" }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "resource": { "enum": [ "image", "creative", "ad" ] }, "entity_id": { "type": "string" }, "status": { "enum": [ "accepted", "paused" ] }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "created_or_reused": { "const": true }, "delivery_confirmed": { "const": false }, "media_id": { "type": "string", "format": "uuid" }, "source_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" } }, "required": [ "resource", "entity_id", "status", "image_hash", "created_or_reused", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "video" }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "video_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_account_id": { "type": "string", "pattern": "^act_[1-9]\\d{0,29}$" }, "media_id": { "type": "string", "format": "uuid" }, "source_sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "status": { "const": "accepted" }, "processing_verified": { "const": false }, "delivery_confirmed": { "const": false } }, "required": [ "resource", "entity_id", "video_id", "ad_account_id", "media_id", "source_sha256", "status", "processing_verified", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "requested_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "native_conversion_verified": { "const": false }, "resource": { "enum": [ "creative", "ad" ] }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "enum": [ "accepted", "paused" ] }, "requested_format": { "const": "video" }, "placement": { "enum": [ "facebook_feed", "instagram_feed" ] }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "video_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "image_hash": { "type": "string", "pattern": "^[a-f0-9]{32}$" }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "native_video_status_at_check": { "const": "ready" }, "advertising_eligibility_verified": { "const": false }, "created_or_reused": { "const": true }, "atomic_precondition": { "const": false }, "delivery_confirmed": { "const": false } }, "required": [ "resource", "entity_id", "status", "requested_format", "placement", "video_id", "image_hash", "page_id", "native_video_status_at_check", "advertising_eligibility_verified", "created_or_reused", "atomic_precondition", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "requested_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "native_conversion_verified": { "const": false }, "placement": { "const": "instagram_feed" }, "instagram_user_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "resource": { "enum": [ "creative", "ad" ] }, "entity_id": { "type": "string" }, "status": { "enum": [ "accepted", "paused" ] }, "image_hashes": { "type": "array", "minItems": 2, "maxItems": 10, "items": { "type": "string", "pattern": "^[a-f0-9]{32}$" } }, "card_count": { "type": "integer", "minimum": 2, "maximum": 10 }, "requested_format": { "const": "image_carousel" }, "card_order_optimization_requested": { "const": false }, "end_card_requested": { "const": false }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "created_or_reused": { "const": true }, "delivery_confirmed": { "const": false } }, "required": [ "resource", "entity_id", "status", "image_hashes", "card_count", "requested_format", "card_order_optimization_requested", "end_card_requested", "page_id", "created_or_reused", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "ad_group" }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "currency": { "type": "string" }, "field": { "enum": [ "daily_budget_minor", "lifetime_budget_minor", "bid_amount_minor" ] }, "previous_amount_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "amount_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" }, "bid_strategy": { "enum": [ "LOWEST_COST_WITHOUT_CAP", "LOWEST_COST_WITH_BID_CAP" ] }, "status": { "enum": [ "enabled", "paused" ] }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "reviewed_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "native_conversion_verified": { "const": false } }, "required": [ "resource", "entity_id", "campaign_id", "currency", "field", "previous_amount_minor", "amount_minor", "bid_strategy", "status", "changed", "delivery_confirmed", "atomic_precondition" ], "additionalProperties": false }, { "type": "object", "properties": { "bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ], "description": "Reviewed strategy matched by native prechecks; included only when explicitly requested. External edits can race the mutation." }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string" }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "resource": { "const": "keyword" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "status": { "enum": [ "enabled", "paused", "removed" ] }, "negative": { "type": "boolean" }, "cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "created": { "type": "boolean" }, "replaced_criterion_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "entity_id", "campaign_id", "currency", "changed", "delivery_confirmed", "atomic_precondition", "resource", "ad_group_id", "status", "negative", "cpc_bid_micros", "created" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "search_campaign" }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "budget_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "keyword_ids": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "minItems": 1, "maxItems": 20, "uniqueItems": true }, "target_criterion_ids": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "minItems": 1, "maxItems": 30, "uniqueItems": true }, "status": { "const": "paused" }, "created": { "const": true }, "changed": { "const": true }, "delivery_confirmed": { "const": false }, "currency": { "type": "string" }, "time_zone": { "type": "string" }, "daily_budget_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] }, "cpc_bid_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "cpc_bid_ceiling_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "start_date": { "type": "string", "format": "date", "pattern": "^20[0-9]{2}-[0-9]{2}-[0-9]{2}$" }, "end_date": { "type": "string", "format": "date", "pattern": "^20[0-9]{2}-[0-9]{2}-[0-9]{2}$" }, "impression_share": { "type": "object", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ] }, "location_fraction_micros": { "type": "string", "pattern": "^(?:[1-9]\\d{0,5}|1000000)$", "description": "Canonical fraction micros1–1000000. 500000 means50%, not currency. Requested auction objective, not guaranteed delivery/share." } }, "required": [ "location", "location_fraction_micros" ], "additionalProperties": false }, "impression_share_verified": { "const": false }, "target_cpa_micros": { "anyOf": [ { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, { "type": "null" } ] }, "target_roas": { "type": [ "number", "null" ] }, "conversion_values_verified": { "const": false }, "conversion_goal_revision": { "type": "string" }, "conversion_tracking_verified": { "const": false }, "goal_precondition_atomic": { "const": false } }, "required": [ "resource", "entity_id", "budget_id", "ad_group_id", "ad_id", "keyword_ids", "target_criterion_ids", "status", "created", "changed", "delivery_confirmed", "currency", "time_zone", "daily_budget_micros", "bidding_strategy", "cpc_bid_micros", "cpc_bid_ceiling_micros", "start_date", "end_date" ], "additionalProperties": false }, { "type": "object", "properties": { "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string" }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "resource": { "const": "campaign_budget" }, "daily_budget_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "previous_daily_budget_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "entity_id", "campaign_id", "currency", "changed", "delivery_confirmed", "atomic_precondition", "resource", "daily_budget_micros", "previous_daily_budget_micros" ], "additionalProperties": false }, { "type": "object", "properties": { "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string" }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "resource": { "const": "ad_group" }, "cpc_bid_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "previous_cpc_bid_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "entity_id", "campaign_id", "currency", "changed", "delivery_confirmed", "atomic_precondition", "resource", "cpc_bid_micros", "previous_cpc_bid_micros" ], "additionalProperties": false }, { "type": "object", "properties": { "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string" }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "resource": { "const": "campaign" }, "bidding_strategy": { "const": "maximize_clicks" }, "cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "previous_cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "entity_id", "campaign_id", "currency", "changed", "delivery_confirmed", "atomic_precondition", "resource", "bidding_strategy", "cpc_bid_ceiling_micros", "previous_cpc_bid_ceiling_micros" ], "additionalProperties": false }, { "type": "object", "properties": { "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string" }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "resource": { "const": "campaign" }, "bidding_strategy": { "const": "target_impression_share" }, "impression_share": { "type": "object", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ] }, "location_fraction_micros": { "type": "string", "pattern": "^(?:[1-9]\\d{0,5}|1000000)$", "description": "Canonical fraction micros1–1000000. 500000 means50%, not currency. Requested auction objective, not guaranteed delivery/share." }, "cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "location", "location_fraction_micros", "cpc_bid_ceiling_micros" ], "additionalProperties": false }, "previous_impression_share": { "type": "object", "properties": { "location": { "enum": [ "ANYWHERE_ON_PAGE", "TOP_OF_PAGE", "ABSOLUTE_TOP_OF_PAGE" ] }, "location_fraction_micros": { "type": "string", "pattern": "^(?:[1-9]\\d{0,5}|1000000)$", "description": "Canonical fraction micros1–1000000. 500000 means50%, not currency. Requested auction objective, not guaranteed delivery/share." }, "cpc_bid_ceiling_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "location", "location_fraction_micros", "cpc_bid_ceiling_micros" ], "additionalProperties": false }, "impression_share_verified": { "const": false } }, "required": [ "entity_id", "campaign_id", "currency", "changed", "delivery_confirmed", "atomic_precondition", "resource", "bidding_strategy", "impression_share", "previous_impression_share", "impression_share_verified" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "campaign_target" }, "entity_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "campaign_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "target_type": { "enum": [ "location", "language" ] }, "target_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "replaced_criterion_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "currency": { "type": "string" }, "bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] }, "status": { "const": "enabled" }, "negative": { "const": false }, "changed": { "type": "boolean" }, "created": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false } }, "required": [ "resource", "entity_id", "campaign_id", "target_type", "target_id", "currency", "bidding_strategy", "status", "negative", "changed", "created", "delivery_confirmed", "atomic_precondition" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "location_exclusion" }, "entity_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "campaign_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "location_id": { "type": "string", "pattern": "^[1-9]\\d{0,18}(?![\\s\\S])", "description": "Exact positive signed-int64 decimal string, maximum9223372036854775807; no whitespace" }, "currency": { "type": "string" }, "bidding_strategy": { "enum": [ "manual_cpc", "maximize_clicks", "maximize_conversions", "maximize_conversion_value", "target_impression_share" ] }, "negative": { "const": true }, "requested_state": { "enum": [ "excluded", "removed" ] }, "native_accepted": { "const": true }, "configuration_verified": { "const": false }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false } }, "required": [ "resource", "entity_id", "campaign_id", "location_id", "currency", "bidding_strategy", "negative", "requested_state", "native_accepted", "configuration_verified", "delivery_confirmed", "atomic_precondition" ], "additionalProperties": false }, { "type": "object", "properties": { "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string" }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "resource": { "const": "campaign" }, "bidding_strategy": { "const": "maximize_conversions" }, "target_cpa_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "previous_target_cpa_micros": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." } }, "required": [ "entity_id", "campaign_id", "currency", "changed", "delivery_confirmed", "atomic_precondition", "resource", "bidding_strategy", "target_cpa_micros", "previous_target_cpa_micros" ], "additionalProperties": false }, { "type": "object", "properties": { "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "currency": { "type": "string" }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "resource": { "const": "campaign" }, "bidding_strategy": { "const": "maximize_conversion_value" }, "target_roas": { "type": "number", "minimum": 0.01, "maximum": 1000 }, "previous_target_roas": { "type": "number", "minimum": 0.01, "maximum": 1000 }, "conversion_values_verified": { "const": false } }, "required": [ "entity_id", "campaign_id", "currency", "changed", "delivery_confirmed", "atomic_precondition", "resource", "bidding_strategy", "target_roas", "previous_target_roas", "conversion_values_verified" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "ad" }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,18}$", "description": "Positive decimal int64 string, at most 9223372036854775807. Micros are 1/1,000,000 of advertiser currency." }, "changed": { "type": "boolean" }, "updated_fields": { "const": [ "headlines", "descriptions" ] }, "activation_requested": { "const": false }, "delivery_confirmed": { "const": false }, "atomic_precondition": { "const": false }, "policy_approval_verified": { "const": false } }, "required": [ "resource", "entity_id", "campaign_id", "ad_group_id", "changed", "updated_fields", "activation_requested", "delivery_confirmed", "atomic_precondition", "policy_approval_verified" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "enum": [ "campaign", "ad_group", "ad" ] }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "enum": [ "enabled", "paused" ] }, "changed": { "type": "boolean" }, "delivery_confirmed": { "const": false } }, "required": [ "resource", "entity_id", "status", "changed", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "enum": [ "campaign", "ad_group" ] }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "const": "paused" }, "changed": { "const": true }, "created": { "const": true }, "delivery_confirmed": { "const": false }, "objective": { "enum": [ "traffic", "sales" ] }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "currency": { "type": "string" }, "daily_budget_minor": { "type": "string" }, "lifetime_budget_minor": { "type": "string" }, "native_budget_verified": { "const": false }, "requested_objective": { "const": "sales" }, "requested_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "native_conversion_verified": { "const": false }, "requested_bidding": { "oneOf": [ { "type": "object", "properties": { "strategy": { "const": "lowest_cost" } }, "required": [ "strategy" ], "additionalProperties": false }, { "type": "object", "properties": { "strategy": { "const": "bid_cap" }, "bid_amount_minor": { "type": "string", "pattern": "^[1-9][0-9]{0,11}$" } }, "required": [ "strategy", "bid_amount_minor" ], "additionalProperties": false } ], "description": "Optional reviewed strategy. Omission retains lowest cost without cap. A bid cap is an auction input in native account-currency minor units, not a daily/lifetime spend ceiling or delivery guarantee. Paused creation only; native eligibility remains required." }, "native_bidding_verified": { "const": false }, "requested_audiences": { "type": "object", "properties": { "included_ids": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "maxItems": 5 }, "excluded_ids": { "type": "array", "items": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "maxItems": 5 } }, "required": [ "included_ids", "excluded_ids" ], "additionalProperties": false }, "requested_geography": { "enum": [ "regions", "city" ] }, "native_targeting_verified": { "const": false }, "transparency_requested": { "const": true }, "transparency_retained_confirmed": { "const": false }, "start_time": { "type": "string", "format": "date-time" }, "end_time": { "type": "string", "format": "date-time" } }, "required": [ "resource", "entity_id", "status", "changed", "created", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "resource": { "const": "creative" }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "const": "accepted" }, "created_or_reused": { "const": true }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "post_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}_[1-9][0-9]{0,29}$" }, "delivery_confirmed": { "const": false } }, "required": [ "resource", "entity_id", "status", "created_or_reused", "page_id", "post_id", "delivery_confirmed" ], "additionalProperties": false }, { "type": "object", "properties": { "requested_conversion": { "type": "object", "properties": { "pixel_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "event_type": { "enum": [ "PURCHASE", "LEAD", "COMPLETE_REGISTRATION", "ADD_TO_CART", "INITIATED_CHECKOUT", "CONTENT_VIEW" ] }, "confirm_website_conversion": { "const": true } }, "required": [ "pixel_id", "event_type", "confirm_website_conversion" ], "additionalProperties": false }, "native_conversion_verified": { "const": false }, "resource": { "const": "ad" }, "entity_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "status": { "const": "paused" }, "created": { "const": true }, "changed": { "const": true }, "ad_group_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "campaign_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "creative_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "post_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}_[1-9][0-9]{0,29}$" }, "delivery_confirmed": { "const": false } }, "required": [ "resource", "entity_id", "status", "created", "changed", "ad_group_id", "campaign_id", "creative_id", "page_id", "post_id", "delivery_confirmed" ], "additionalProperties": false }, { "type": "null" } ] }, "error_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_by": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "id", "customer_id", "connection_id", "page_connection_id", "source_media_id", "action", "status", "provider_data_erased_at", "attempts", "requires_spend", "provider_receipt", "error_code", "created_at", "updated_at", "expires_at", "acknowledged_at", "acknowledged_by" ], "additionalProperties": false } }, "required": [ "operation" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/ads/operations/{operation_id}/cancel": { "post": { "summary": "Cancel future queued advertising attempts before current native start; cancelling a queued pause can leave current spend unchanged; no native pause, rollback or refund", "operationId": "post__api_v1_projects_project_id_ads_operations_operation_id_cancel", "x-required-scope": "ads:operations:read, ads:write and ads:spend; owner/admin", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9_]{0,79}(?![\\s\\S])" }, "status": { "const": "cancelled" }, "cancelled": { "const": true }, "future_attempts_cancelled": { "const": true }, "delivery_confirmed": { "const": false }, "replayed": { "type": "boolean" } }, "required": [ "id", "action", "status", "cancelled", "future_attempts_cancelled", "delivery_confirmed", "replayed" ], "additionalProperties": false } }, "required": [ "operation" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_action": { "type": "string", "minLength": 1, "maxLength": 80, "pattern": "^[a-z][a-z0-9_]{0,79}(?![\\s\\S])" }, "confirm_cancel": { "const": true } }, "required": [ "expected_action", "confirm_cancel" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/operations/{operation_id}/acknowledge": { "post": { "summary": "Owner/admin acknowledges an unknown outcome to unblock later target operations; no retry or claim of delivery", "operationId": "post__api_v1_projects_project_id_ads_operations_operation_id_acknowledge", "x-required-scope": "ads:write and ads:operations:read; owner/admin only", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "ambiguous" }, "acknowledged": { "const": true }, "replayed": { "type": "boolean" } }, "required": [ "id", "status", "acknowledged", "replayed" ], "additionalProperties": false }, "delivery_confirmed": { "const": false } }, "required": [ "operation", "delivery_confirmed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledge_unknown_outcome": { "const": true }, "note": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "acknowledge_unknown_outcome", "note" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/ads/query": { "post": { "summary": "Read customer-bound Meta or Google Ads data; insights date range 1–31 days", "operationId": "post__api_v1_projects_project_id_ads_query", "x-required-scope": "ads:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "enum": [ "metaads", "googleads" ] }, "resource": { "enum": [ "account", "campaigns", "ad_groups", "ads", "insights" ] }, "level": { "enum": [ "account", "campaign", "ad_group", "ad", "keyword", "age_range", "gender", null ] }, "native_level": { "enum": [ "account", "campaign", "ad_group", "adset", "ad", "keyword", "age_range_view", "gender_view", null ] }, "metric_set": { "enum": [ "basic", "performance", "search_share", null ] }, "breakdown": { "enum": [ "age", "gender", "country", "publisher_platform", "device_platform", "age_gender", "placement", null ] }, "breakdown_fields": { "type": [ "array", "null" ], "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "age", "gender", "country", "publisher_platform", "device_platform", "platform_position" ] }, "description": "Exact ordered Meta native fields for the selected report, or null without a Meta breakdown. age_gender maps to age/gender; placement to publisher_platform/platform_position." }, "metrics_basis": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Native attribution/units/absence semantics for performance or search_share insights. Search share has ratio units, native estimates, censored thresholds, missing=null and additive=false; no cross-provider equivalence." }, "complete_snapshot": { "const": false }, "content_is_untrusted": { "const": true }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true, "properties": { "dimensions": { "type": "object", "additionalProperties": false, "minProperties": 1, "maxProperties": 2, "properties": { "age": { "type": "string", "minLength": 1, "maxLength": 80 }, "age_range": { "type": "string", "minLength": 1, "maxLength": 80 }, "gender": { "type": "string", "minLength": 1, "maxLength": 80 }, "country": { "type": "string", "minLength": 1, "maxLength": 80 }, "publisher_platform": { "type": "string", "minLength": 1, "maxLength": 80 }, "device_platform": { "type": "string", "minLength": 1, "maxLength": 80 }, "platform_position": { "type": "string", "minLength": 1, "maxLength": 80 } }, "description": "Present for Meta basic breakdowns or Google age_range/gender levels. Meta age_gender and placement preserve both exact native labels; other reports preserve one. No per-person identity, inferred joins or zero filling. Google demographic levels remain separate aggregates." }, "provider_metrics": { "type": "object", "additionalProperties": true, "description": "For search_share, every field follows GoogleSearchShareMetrics and preserves censoring/nulls. For performance: fixed Google conversion/value/interactions/CTR fields, or Meta reach/frequency/click/action-type fields. Counts/decimals are strings; missing Meta metrics are null. Google DOUBLE values retain native JSON precision. Explicit include_attribution adds bounded native attribution_setting:string|null without interpreting an effective/historical model." } } } }, "next_cursor": { "type": [ "string", "null" ] }, "fetched_at": { "type": "string", "format": "date-time" }, "date_basis": { "const": "ad_account_timezone" }, "read_only": { "const": true }, "limitations": { "type": "array", "items": { "type": "string" } } }, "required": [ "provider", "resource", "level", "native_level", "metric_set", "breakdown", "breakdown_fields", "metrics_basis", "complete_snapshot", "content_is_untrusted", "data", "next_cursor", "fetched_at", "date_basis", "read_only", "limitations" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "metric_set": { "const": "search_share" } }, "required": [ "metric_set" ] }, "then": { "properties": { "provider": { "const": "googleads" }, "resource": { "const": "insights" }, "level": { "const": "campaign" }, "native_level": { "const": "campaign" }, "breakdown": { "type": "null" }, "breakdown_fields": { "type": "null" }, "data": { "type": "array", "items": { "type": "object", "required": [ "provider_metrics" ], "properties": { "provider_metrics": { "$ref": "#/components/schemas/GoogleSearchShareMetrics" } } } } } } } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "resource": { "enum": [ "account", "campaigns", "ad_groups", "ads", "insights" ] }, "level": { "enum": [ "account", "campaign", "ad_group", "ad", "keyword", "age_range", "gender" ], "description": "Insights only; defaults to account. Meta ad_group maps to adset. Google-only age_range/gender are separate daily native ad-group criterion aggregates, never a joint audience distribution. Native unknown/undetermined labels remain distinct; absent rows are not zero-filled. Google-only keyword reports configured positive Search keywords, excluding negative/zero-impression criteria. Not search terms or full inventory. Criterion identity is account/group/criterion; keyword attributes are current, not historical." }, "breakdown": { "enum": [ "age", "gender", "country", "publisher_platform", "device_platform", "age_gender", "placement" ], "description": "One fixed Meta-only BASIC report. age_gender requests native age/gender together; placement requests publisher_platform/platform_position together. Other options select one dimension. No arbitrary pairs, performance or Google keyword/age_range/gender reports. Absent/suppressed buckets are not zero-filled; no inferred joins between reports." }, "include_attribution": { "const": true, "description": "Explicit native attribution_setting readback only for Meta performance ad_group/ad insights. Requested parameters are not proof of effective attribution or reporting time." }, "metric_set": { "enum": [ "basic", "performance", "search_share" ], "description": "Insights only; default basic. Google v25-only search_share requires explicit campaign level and no breakdown/attribution. It returns ten native share/loss estimate objects;0.0999 means below10% share and0.9001 means above90% loss. Missing metrics=null; never sum/average ratios or derive eligible impressions/competitors. Performance adds native provider_metrics. Meta requests the impression-time parameter with7d_click/1d_view and action_type breakdown; effective attribution/report-time are not verified; no arbitrary fields or attribution overrides." }, "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date" }, "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 }, "cursor": { "type": "string", "maxLength": 10000 } }, "required": [ "customer_id", "connection_id", "resource" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "metric_set": { "const": "search_share" } }, "required": [ "metric_set" ] }, "then": { "properties": { "resource": { "const": "insights" }, "level": { "const": "campaign" } }, "required": [ "level" ], "not": { "anyOf": [ { "required": [ "breakdown" ] }, { "required": [ "include_attribution" ] } ] } } }, { "if": { "required": [ "include_attribution" ] }, "then": { "properties": { "resource": { "const": "insights" }, "metric_set": { "const": "performance" }, "level": { "enum": [ "ad_group", "ad" ] } }, "required": [ "metric_set", "level" ] } }, { "if": { "required": [ "breakdown" ] }, "then": { "properties": { "resource": { "const": "insights" }, "include_attribution": { "const": true, "description": "Explicit native attribution_setting readback only for Meta performance ad_group/ad insights. Requested parameters are not proof of effective attribution or reporting time." }, "metric_set": { "const": "basic" }, "level": { "enum": [ "account", "campaign", "ad_group", "ad" ] } } } }, { "if": { "properties": { "resource": { "const": "insights" } } }, "then": { "required": [ "since", "until" ] }, "else": { "not": { "anyOf": [ { "required": [ "since" ] }, { "required": [ "until" ] }, { "required": [ "level" ] }, { "required": [ "metric_set" ] }, { "required": [ "breakdown" ] }, { "required": [ "include_attribution" ] } ] } } } ] } } } } } }, "/api/v1/projects/{project_id}/analytics/search-console/inspect": { "post": { "summary": "Inspect the Google-indexed version of a URL inside one authorized connected property; bounded index/AMP/rich results, no live fetch or indexing request", "operationId": "post__api_v1_projects_project_id_analytics_search_console_inspect", "x-required-scope": "analytics:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "searchconsole" }, "report": { "const": "url_inspection" }, "property": { "type": "string" }, "inspection_url": { "type": "string" }, "language_code": { "type": "string" }, "inspection_result": { "type": "object", "properties": { "index_status": { "type": "object", "properties": { "verdict": { "type": [ "string", "null" ] }, "coverage_state": { "type": [ "string", "null" ] }, "robots_txt_state": { "type": [ "string", "null" ] }, "indexing_state": { "type": [ "string", "null" ] }, "last_crawl_time": { "type": [ "string", "null" ] }, "page_fetch_state": { "type": [ "string", "null" ] }, "google_canonical": { "type": [ "string", "null" ] }, "user_canonical": { "type": [ "string", "null" ] }, "crawled_as": { "type": [ "string", "null" ] }, "sitemaps": { "type": "array", "items": { "type": "string" } }, "referring_urls": { "type": "array", "items": { "type": "string" } } }, "required": [ "verdict", "coverage_state", "robots_txt_state", "indexing_state", "last_crawl_time", "page_fetch_state", "google_canonical", "user_canonical", "crawled_as", "sitemaps", "referring_urls" ], "additionalProperties": false }, "amp": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": [ "string", "null" ] }, "amp_url": { "type": [ "string", "null" ] }, "robots_txt_state": { "type": [ "string", "null" ] }, "indexing_state": { "type": [ "string", "null" ] }, "index_status_verdict": { "type": [ "string", "null" ] }, "last_crawl_time": { "type": [ "string", "null" ] }, "page_fetch_state": { "type": [ "string", "null" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] } }, "required": [ "message", "severity" ], "additionalProperties": false } } }, "required": [ "verdict", "amp_url", "robots_txt_state", "indexing_state", "index_status_verdict", "last_crawl_time", "page_fetch_state", "issues" ], "additionalProperties": false }, { "type": "null" } ] }, "rich_results": { "anyOf": [ { "type": "object", "properties": { "verdict": { "type": [ "string", "null" ] }, "detected_items": { "type": "array", "items": { "type": "object", "properties": { "rich_result_type": { "type": "string" }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] }, "issues": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": [ "string", "null" ] }, "severity": { "type": [ "string", "null" ] } }, "required": [ "message", "severity" ], "additionalProperties": false } } }, "required": [ "name", "issues" ], "additionalProperties": false } } }, "required": [ "rich_result_type", "items" ], "additionalProperties": false } } }, "required": [ "verdict", "detected_items" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "index_status", "amp", "rich_results" ], "additionalProperties": false }, "index_version_only": { "const": true }, "live_test": { "const": false }, "complete_snapshot": { "const": false }, "limitations": { "type": "array", "items": { "type": "string" } }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "fetched_at": { "type": "string", "format": "date-time" } }, "required": [ "provider", "report", "property", "inspection_url", "language_code", "inspection_result", "index_version_only", "live_test", "complete_snapshot", "limitations", "read_only", "content_is_untrusted", "fetched_at" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "inspection_url": { "type": "string", "format": "uri", "maxLength": 2048, "description": "HTTP(S) URL within the exact connected property, without credentials or fragment. No arbitrary property or upstream URL." }, "language_code": { "type": "string", "default": "en-US", "maxLength": 35 } }, "required": [ "customer_id", "connection_id", "inspection_url" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/analytics/search-console/query": { "post": { "summary": "Read fixed authorized Search Console property performance; native top rows, explicit finalized/fresh/hourly data and Pacific date boundaries; no complete-export guarantee", "operationId": "post__api_v1_projects_project_id_analytics_search_console_query", "x-required-scope": "analytics:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "const": "searchconsole" }, "report": { "const": "search_performance" }, "property": { "type": "string" }, "search_type": { "enum": [ "web", "image", "video", "news", "discover", "googleNews" ] }, "aggregation": { "enum": [ "byPage", "byProperty", null ] }, "data_state": { "enum": [ "final", "all", "hourly_all" ] }, "freshness": { "type": "object", "properties": { "may_change": { "type": "boolean" }, "first_incomplete_date": { "type": [ "string", "null" ], "format": "date" }, "first_incomplete_hour": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "may_change", "first_incomplete_date", "first_incomplete_hour" ], "additionalProperties": false }, "data": { "type": "array", "items": { "type": "object", "properties": { "period_start": { "type": [ "string", "null" ], "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "dimensions": { "type": "object", "additionalProperties": { "type": "string" } }, "metrics": { "type": "object", "properties": { "clicks": { "type": [ "string", "null" ] }, "impressions": { "type": [ "string", "null" ] }, "ctr": { "type": [ "string", "null" ] }, "position": { "type": [ "string", "null" ] } }, "required": [ "clicks", "impressions", "ctr", "position" ], "additionalProperties": false } }, "required": [ "period_start", "period_end", "dimensions", "metrics" ], "additionalProperties": false } }, "metric_definitions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "unit": { "enum": [ "count", "ratio", "position" ] }, "description": { "type": "string" } }, "required": [ "unit", "description" ], "additionalProperties": false } }, "date_basis": { "type": "string" }, "traffic_basis": { "type": "string" }, "complete_snapshot": { "const": false }, "limitations": { "type": "array", "items": { "type": "string" } }, "selection": { "type": "object", "properties": { "start_row": { "type": "integer" }, "limit": { "type": "integer" }, "returned_rows": { "type": "integer" }, "at_limit": { "type": "boolean" }, "next_start_row": { "type": [ "integer", "null" ] }, "offset_bound_reached": { "type": "boolean" } }, "required": [ "start_row", "limit", "returned_rows", "at_limit", "next_start_row", "offset_bound_reached" ], "additionalProperties": false }, "read_only": { "const": true }, "content_is_untrusted": { "const": true }, "fetched_at": { "type": "string", "format": "date-time" } }, "required": [ "provider", "report", "property", "search_type", "aggregation", "data_state", "freshness", "data", "metric_definitions", "date_basis", "traffic_basis", "complete_snapshot", "limitations", "selection", "read_only", "content_is_untrusted", "fetched_at" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "since": { "type": "string", "format": "date" }, "until": { "type": "string", "format": "date" }, "data_state": { "enum": [ "final", "all", "hourly_all" ], "default": "final", "description": "hourly_all requires hour dimension and only current/previous9 Pacific dates; all may include fresh data. No implied finality from absent metadata." }, "dimensions": { "type": "array", "items": { "enum": [ "date", "hour", "country", "device", "page", "query", "searchAppearance" ] }, "maxItems": 7, "uniqueItems": true, "default": [ "date" ] }, "search_type": { "enum": [ "web", "image", "video", "news", "discover", "googleNews" ], "default": "web" }, "aggregation": { "enum": [ "auto", "byPage", "byProperty" ], "default": "auto" }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "enum": [ "country", "device", "page", "query", "searchAppearance" ] }, "operator": { "enum": [ "equals", "notEquals", "contains", "notContains" ] }, "expression": { "type": "string", "minLength": 1, "maxLength": 1024 } }, "required": [ "dimension", "operator", "expression" ], "additionalProperties": false }, "maxItems": 5, "default": [] }, "limit": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 250 }, "start_row": { "type": "integer", "minimum": 0, "maximum": 50000, "default": 0 } }, "required": [ "customer_id", "connection_id", "since", "until" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/analytics/query": { "post": { "summary": "Read customer-bound Facebook Page daily/native weekly/28-day and owned-post lifetime metrics, native Instagram account/media insights, YouTube breakdowns, LinkedIn organization/member metrics or owned X post/video counters and post hourly/daily/weekly/total and selected attached-video hourly/daily/total analytics", "operationId": "post__api_v1_projects_project_id_analytics_query", "x-required-scope": "analytics:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "enum": [ "youtube", "linkedin", "instagram", "facebook", "x" ] }, "report": { "enum": [ "daily", "summary", "hourly", "weekly", "media_hourly", "media_daily", "media_summary", "facebook_page_weekly", "facebook_page_28d", "lifetime", "videos", "countries", "traffic_sources", "traffic_source_details", "devices", "operating_systems", "demographics", "retention", "sharing_services", "account_breakdown", "media_breakdown", "audience", "organization_followers_daily", "organization_followers_audience", "organization_page_daily", "organization_page_lifetime", "organization_page_audience" ] }, "data": { "type": "array", "items": { "type": "object", "properties": { "period_start": { "type": [ "string", "null" ], "format": "date" }, "period_end": { "type": [ "string", "null" ], "format": "date" }, "native_period": { "type": "object", "properties": { "period": { "enum": [ "day", "week", "days_28" ] }, "end_time": { "type": "string", "format": "date-time" }, "start_time": { "type": "string", "format": "date-time" }, "start_inclusive": { "type": "boolean" }, "end_inclusive": { "type": "boolean" } }, "required": [ "period", "end_time" ], "additionalProperties": false }, "dimensions": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Native breakdown dimension names/values; X lifetime includes post_id and created_at, plus media_key for video rows. X daily/summary preserves requested_start_time and requested_end_time; daily adds bucket_start_time. These are native/query timestamps, not inferred bucket ends or traffic attribution." }, "metrics": { "type": "object", "additionalProperties": { "type": [ "string", "null" ], "description": "Native numeric string; null means unavailable, not zero." } } }, "required": [ "period_start", "period_end", "metrics" ], "additionalProperties": false } }, "native_totals": { "type": "object", "additionalProperties": { "type": [ "string", "null" ] }, "description": "Instagram media_breakdown native aggregate kept separate; never synthesized by summing privacy-limited facets." }, "metric_definitions": { "type": "object", "additionalProperties": { "type": "object", "properties": { "unit": { "enum": [ "count", "minutes", "seconds", "milliseconds", "ratio", "percent" ] }, "description": { "type": "string" }, "signed": { "type": "boolean" } }, "required": [ "unit", "description" ], "additionalProperties": false } }, "date_basis": { "type": "string" }, "traffic_basis": { "type": "string" }, "selection": { "type": "object", "properties": { "kind": { "enum": [ "top_n", "dimension_breakdown" ] }, "limit": { "type": "integer" }, "returned_rows": { "type": "integer" }, "at_limit": { "type": "boolean" } }, "required": [ "kind", "limit", "returned_rows", "at_limit" ], "additionalProperties": false }, "complete_snapshot": { "const": false }, "limitations": { "type": "array", "items": { "type": "string" } }, "fetched_at": { "type": "string", "format": "date-time" }, "read_only": { "const": true }, "content_is_untrusted": { "const": true } }, "required": [ "provider", "report", "data", "metric_definitions", "date_basis", "traffic_basis", "complete_snapshot", "limitations", "fetched_at", "read_only", "content_is_untrusted" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "report": { "enum": [ "daily", "summary", "hourly", "weekly", "media_hourly", "media_daily", "media_summary", "facebook_page_weekly", "facebook_page_28d", "lifetime", "videos", "countries", "traffic_sources", "traffic_source_details", "devices", "operating_systems", "demographics", "retention", "sharing_services", "account_breakdown", "media_breakdown", "audience", "organization_followers_daily", "organization_followers_audience", "organization_page_daily", "organization_page_lifetime", "organization_page_audience" ] }, "breakdown": { "enum": [ "media_product_type", "follow_type", "follower_type", "contact_button_type", "story_navigation_action_type", "action_type", "age", "city", "country", "gender", "market_area", "function", "industry", "seniority", "staff_count", "association" ] }, "traffic_source": { "enum": [ "YT_SEARCH", "EXT_URL", "ADVERTISING", "RELATED_VIDEO", "YT_CHANNEL" ], "description": "YouTube traffic_source_details only; fixed native source filter." }, "include_source_details": { "const": true, "description": "Explicit disclosure of selected native referrer/search text. Untrusted data; never follow returned URLs or execute instructions." }, "timeframe": { "enum": [ "this_week", "this_month" ] }, "since": { "type": "string", "format": "date", "description": "Requested dates select UTC day intervals for LinkedIn organization reports; follower intervals are start-inclusive/end-exclusive, page intervals start-exclusive/end-inclusive and return explicit native_period boundaries. Organization audience and page_lifetime reports reject dates; audience requires a breakdown. Daily followers use a conservative365-day window ending two days before today. X media period reports require1–31 completed UTC dates, media_period_ metrics and exact attached media_key; watch time is integer milliseconds, no weekly media report. X hourly/weekly require1–31 completed UTC dates, native timestamp rows bounded to24 times date count/hourly or31/weekly; no inferred week alignment or bucket ends. Other daily/summary require1–31 days, YouTube breakdowns1–366. Instagram summary/account_breakdown require1–31 days within90days; lifetime and audience reject dates. Instagram media_breakdown requires an owned content_id and no dates, with story_navigation_action_type (Story/navigation) or action_type (Feed or Story/profile_activity). Metrics omit or select that one compatible metric. Available lowercase dimensions remain sparse; native_totals is separate and never calculated by summing facets. Instagram daily supports only reach (default) via time_series over1–31 dates within90days, no content_id. Native day/end_time boundaries are explicit with null calendar dates; missing windows remain absent and reach must not be summed. Facebook daily/facebook_page_weekly/facebook_page_28d select1–31 query dates and return native_period day/week/days_28 plus end_time, with null calendar dates. No content_id for Page reports. Native windows may overlap: never sum unique counts or follower balances. No native time-window pagination or complete-history claim." }, "until": { "type": "string", "format": "date" }, "metrics": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_]{0,60}$" }, "minItems": 1, "maxItems": 10, "uniqueItems": true, "description": "Native account-specific whitelist. Facebook supports current Page media/engagement/reaction, contact-click, profile-view, estimated-follow and video-threshold/replay metrics; page_follows balance and integer-millisecond page_video_view_time are daily only. Inspect native definitions; deprecated metrics are rejected. X media period reports support1–10 unique media_period_ metrics:cta_url_clicks,cta_watch_clicks,play_from_tap,playback25/50/75,playback_complete,playback_start,video_views,watch_time_ms. No mixing with post/lifetime names. YouTube defaults are report-specific; metrics outside that report are rejected. videos and traffic_source_details require views for fixed ranking. Traffic details accept views,engagedViews,estimatedMinutesWatched only, with1–31 dates. Organization share reports default to supported metrics. Organization follower gains use organicFollowerGain/paidFollowerGain; audience uses combined followerCount. Organization page reports default to allPageViews/allDesktopPageViews/allMobilePageViews and accept native view families or unique_ variants, at most10 selected. LinkedIn member reports accept exactly one metric, default IMPRESSION; memberFollowersCount selects separate follower reporting. Instagram uses current native metrics; summary/account_breakdown use total_value, audience accepts one demographic metric, lifetime requires owned content_id. See /docs/ads." }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "YouTube videos/traffic_sources/traffic_source_details/devices/operating_systems/demographics/sharing_services only." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "description": "Ranked videos:1–200/default50; traffic_source_details:1–25/default25. No continuation." }, "media_key": { "type": "string", "pattern": "^\\d{1,2}_[1-9]\\d{0,29}$", "description": "Required only for X media_hourly/media_daily/media_summary: exact selected video key attached to owned content_id. No arbitrary media lookup, exclusive asset ownership or post-unique attribution is inferred." }, "content_id": { "type": "string", "minLength": 1, "maxLength": 150, "description": "Exact YouTube video ID (required for retention, disallowed for videos) or LinkedIn member share/ugcPost URN or one exact LinkedIn organization share/ugcPost URN for lifetime only (organic, rolling12-month availability; no zero-filled missing row/ownership inference) or Instagram media ID (required for lifetime or media_breakdown), or owned Facebook composite PageID_PostID (lifetime), or numeric owned X post ID (required for lifetime/daily/summary/hourly/weekly/media_hourly/media_daily/media_summary; X daily/summary/hourly/weekly accepts1–31 completed UTC dates with period_ metrics; lifetime accepts no dates). Unsupported report/filter pairs are rejected." } }, "required": [ "customer_id", "connection_id", "report" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "report": { "const": "traffic_source_details" } } }, "then": { "required": [ "traffic_source", "include_source_details", "since", "until" ], "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 25 }, "metrics": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "enum": [ "views", "engagedViews", "estimatedMinutesWatched" ] }, "contains": { "const": "views" } } } }, "else": { "not": { "anyOf": [ { "required": [ "traffic_source" ] }, { "required": [ "include_source_details" ] } ] } } }, { "if": { "properties": { "report": { "enum": [ "videos", "traffic_source_details" ] } } }, "else": { "not": { "required": [ "limit" ] } } }, { "if": { "properties": { "report": { "const": "media_breakdown" } } }, "then": { "required": [ "content_id", "breakdown" ], "not": { "anyOf": [ { "required": [ "country" ] }, { "required": [ "timeframe" ] }, { "required": [ "limit" ] } ] }, "properties": { "content_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}$" }, "breakdown": { "enum": [ "story_navigation_action_type", "action_type" ] }, "metrics": { "type": "array", "minItems": 1, "maxItems": 1 } }, "oneOf": [ { "properties": { "breakdown": { "const": "story_navigation_action_type" }, "metrics": { "items": { "const": "navigation" } } } }, { "properties": { "breakdown": { "const": "action_type" }, "metrics": { "items": { "const": "profile_activity" } } } } ] } }, { "if": { "properties": { "report": { "enum": [ "media_hourly", "media_daily", "media_summary" ] } } }, "then": { "required": [ "media_key", "content_id" ] }, "else": { "not": { "required": [ "media_key" ] } } }, { "if": { "properties": { "report": { "enum": [ "facebook_page_weekly", "facebook_page_28d" ] } } }, "then": { "required": [ "since", "until" ], "not": { "required": [ "content_id" ] } } }, { "if": { "properties": { "report": { "enum": [ "hourly", "weekly" ] } } }, "then": { "required": [ "content_id" ] } }, { "if": { "properties": { "report": { "enum": [ "account_breakdown", "media_breakdown", "audience", "organization_followers_audience", "organization_page_audience" ] } } }, "then": { "required": [ "breakdown" ] }, "else": { "not": { "required": [ "breakdown" ] } } }, { "if": { "properties": { "report": { "const": "audience" } } }, "then": { "required": [ "timeframe" ] }, "else": { "not": { "required": [ "timeframe" ] } } }, { "if": { "properties": { "report": { "enum": [ "lifetime", "media_breakdown", "audience", "organization_followers_audience", "organization_page_audience", "organization_page_lifetime" ] } } }, "then": { "not": { "anyOf": [ { "required": [ "since" ] }, { "required": [ "until" ] } ] } }, "else": { "required": [ "since", "until" ] } } ] } } } } } }, "/api/v1/catalog": { "get": { "summary": "Read researched social and ads backlog; planned does not mean implemented", "operationId": "get__api_v1_catalog", "x-required-scope": "authenticated", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/mcp": { "post": { "summary": "Stateless Streamable HTTP MCP with scoped project key or resource-bound OAuth access token", "operationId": "post__api_v1_projects_project_id_mcp", "x-required-scope": "mcp:access", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Accept", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json, text/event-stream" } }, { "name": "MCP-Protocol-Version", "in": "header", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "202": { "description": "Notification accepted; no body" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "security": [ { "projectKey": [] }, { "mcpOAuth": [] } ] }, "get": { "summary": "No unsolicited SSE stream; use POST", "operationId": "get__api_v1_projects_project_id_mcp", "x-required-scope": "mcp:access", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "405": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "projectKey": [] }, { "mcpOAuth": [] } ] } }, "/api/v1/projects/{project_id}/mcp/grants": { "get": { "summary": "Owner/admin lists authorized MCP applications", "operationId": "get__api_v1_projects_project_id_mcp_grants", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "actor_id": { "type": "string", "format": "uuid" }, "client_id": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "actor_id", "client_id", "scopes", "expires_at", "revoked_at", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "grants", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/projects/{project_id}/mcp/grants/{grant_id}": { "delete": { "summary": "Owner/admin revokes a grant, refresh family and backing execution key", "operationId": "delete__api_v1_projects_project_id_mcp_grants_grant_id_", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "grant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "const": true } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/mcp/consent": { "post": { "summary": "Review a pending request with first-party AAL2 session and bound HttpOnly consent cookie", "operationId": "post__api_v1_mcp_consent", "x-required-scope": "console", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "client_name": { "type": "string" }, "project_id": { "type": "string", "format": "uuid" }, "project_name": { "type": "string" }, "resource": { "type": "string" }, "redirect_uri": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" }, "grant_duration_days": { "const": 30 } }, "required": [ "client_id", "client_name", "project_id", "project_name", "resource", "redirect_uri", "scopes", "expires_at", "grant_duration_days" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, "required": [ "request" ], "additionalProperties": false } } } } } }, "/api/v1/mcp/consent/decision": { "post": { "summary": "Explicitly approve a scope subset or deny; returns only the pre-registered redirect", "operationId": "post__api_v1_mcp_consent_decision", "x-required-scope": "console", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "redirect_to": { "type": "string", "format": "uri" } }, "required": [ "redirect_to" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "approve": { "type": "boolean" }, "scopes": { "type": "array", "items": { "type": "string" } } }, "required": [ "request", "approve", "scopes" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}//.well-known/oauth-authorization-server": { "get": { "summary": "OAuth server metadata; only available when configured", "operationId": "get__api_v1_projects_project_id_well_known_oauth_authorization_server", "x-required-scope": "public", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [] } }, "/api/v1/projects/{project_id}//.well-known/oauth-protected-resource/api/v1/projects/{project_id}/mcp": { "get": { "summary": "Project MCP protected resource metadata", "operationId": "get__api_v1_projects_project_id_well_known_oauth_protected_resource_api_v1_projects_project_id_mcp", "x-required-scope": "public", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [] } }, "/api/v1/projects/{project_id}//oauth/mcp/authorize": { "get": { "summary": "Start PKCE authorization for an exactly registered client/redirect/resource; redirect to first-party consent", "operationId": "get__api_v1_projects_project_id_oauth_mcp_authorize", "x-required-scope": "public", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "client_id", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "response_type", "in": "query", "required": true, "schema": { "const": "code" } }, { "name": "redirect_uri", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "resource", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" } }, { "name": "scope", "in": "query", "required": true, "schema": { "type": "string", "description": "Space-separated pre-registered project/tool scopes. mcp:access is required." } }, { "name": "state", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 512 } }, { "name": "code_challenge", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "code_challenge_method", "in": "query", "required": true, "schema": { "const": "S256" } } ], "responses": { "303": { "description": "Same-origin consent page redirect with browser-bound request; no token issued", "headers": { "Location": { "schema": { "type": "string" } }, "Set-Cookie": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [] } }, "/api/v1/projects/{project_id}//oauth/mcp/token": { "post": { "summary": "Exchange one-time S256 code or rotate refresh token; public pre-registered clients only", "operationId": "post__api_v1_projects_project_id_oauth_mcp_token", "x-required-scope": "public", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "token_type": { "const": "Bearer" }, "expires_in": { "type": "integer", "maximum": 3600 }, "scope": { "type": "string", "description": "Space-separated pre-registered project/tool scopes. mcp:access is required." }, "resource": { "type": "string" } }, "required": [ "access_token", "refresh_token", "token_type", "expires_in", "scope", "resource" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "oneOf": [ { "type": "object", "properties": { "grant_type": { "const": "authorization_code" }, "client_id": { "type": "string" }, "resource": { "type": "string" }, "redirect_uri": { "type": "string" }, "code": { "type": "string" }, "code_verifier": { "type": "string", "minLength": 43, "maxLength": 128 } }, "required": [ "grant_type", "client_id", "resource", "redirect_uri", "code", "code_verifier" ], "additionalProperties": false }, { "type": "object", "properties": { "grant_type": { "const": "refresh_token" }, "client_id": { "type": "string" }, "resource": { "type": "string" }, "refresh_token": { "type": "string" } }, "required": [ "grant_type", "client_id", "resource", "refresh_token" ], "additionalProperties": false } ] } } } } } }, "/api/v1/projects/{project_id}//oauth/mcp/revoke": { "post": { "summary": "Revoke an access/refresh token family belonging to the registered client; unknown tokens also return 200", "operationId": "post__api_v1_projects_project_id_oauth_mcp_revoke", "x-required-scope": "public", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Revoked or unknown token; empty body" }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "client_id": { "type": "string" }, "token": { "type": "string" }, "token_type_hint": { "enum": [ "access_token", "refresh_token" ] } }, "required": [ "client_id", "token" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/customers/{customer_id}/media/{id}": { "get": { "summary": "Read current-authorized upload status and bounded recovery metadata; customer erasure withholds results and private storage references are excluded", "operationId": "get__api_v1_projects_project_id_customers_customer_id_media_id_", "x-required-scope": "media:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "filename": { "type": "string" }, "upload_status": { "enum": [ "ready", "pending_verification" ] }, "integrity_verified": { "type": "boolean" }, "sha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "recovery": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 0 }, "error": { "enum": [ null, "object_absent", "object_mismatch", "head_failed" ] } }, "required": [ "attempts", "error" ], "additionalProperties": false } }, "required": [ "id", "customer_id", "mime_type", "size_bytes", "filename", "upload_status", "integrity_verified" ], "additionalProperties": false } }, "required": [ "media" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/customers/{customer_id}/media": { "post": { "summary": "Upload a customer-owned media asset, maximum20MB. Reuse X-Upload-ID with identical bytes/metadata after a transport error; replay never repeats PUT. Publish only after upload_status=ready.", "operationId": "post__api_v1_projects_project_id_customers_customer_id_media", "x-required-scope": "media:write", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-Upload-ID", "in": "header", "schema": { "type": "string", "format": "uuid" }, "description": "Stable client UUID for retries and status polling. Optional; omitted IDs are generated server-side and cannot be recovered after a lost response." }, { "name": "X-Filename", "in": "header", "schema": { "type": "string" }, "description": "URI-encoded filename" } ], "responses": { "200": { "description": "Identical verified upload replay; no new storage write", "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "filename": { "type": "string" }, "upload_status": { "enum": [ "ready", "pending_verification" ] }, "integrity_verified": { "type": "boolean" }, "sha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "recovery": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 0 }, "error": { "enum": [ null, "object_absent", "object_mismatch", "head_failed" ] } }, "required": [ "attempts", "error" ], "additionalProperties": false } }, "required": [ "id", "customer_id", "mime_type", "size_bytes", "filename", "upload_status", "integrity_verified" ], "additionalProperties": false }, "replay": { "type": "boolean" } }, "required": [ "media", "replay" ], "additionalProperties": false } } } }, "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "filename": { "type": "string" }, "upload_status": { "enum": [ "ready", "pending_verification" ] }, "integrity_verified": { "type": "boolean" }, "sha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "recovery": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 0 }, "error": { "enum": [ null, "object_absent", "object_mismatch", "head_failed" ] } }, "required": [ "attempts", "error" ], "additionalProperties": false } }, "required": [ "id", "customer_id", "mime_type", "size_bytes", "filename", "upload_status", "integrity_verified" ], "additionalProperties": false }, "replay": { "type": "boolean" } }, "required": [ "media", "replay" ], "additionalProperties": false } } } }, "202": { "description": "Durably reserved, pending checksum verification. Poll the status endpoint; unknown or absent objects retain their marker.", "content": { "application/json": { "schema": { "type": "object", "properties": { "media": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "mime_type": { "type": "string" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 20971520 }, "filename": { "type": "string" }, "upload_status": { "enum": [ "ready", "pending_verification" ] }, "integrity_verified": { "type": "boolean" }, "sha256": { "type": [ "string", "null" ], "pattern": "^[a-f0-9]{64}$" }, "recovery": { "type": "object", "properties": { "attempts": { "type": "integer", "minimum": 0 }, "error": { "enum": [ null, "object_absent", "object_mismatch", "head_failed" ] } }, "required": [ "attempts", "error" ], "additionalProperties": false } }, "required": [ "id", "customer_id", "mime_type", "size_bytes", "filename", "upload_status", "integrity_verified" ], "additionalProperties": false }, "replay": { "type": "boolean" } }, "required": [ "media", "replay" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } }, "image/webp": { "schema": { "type": "string", "format": "binary" } }, "video/mp4": { "schema": { "type": "string", "format": "binary" } } } } } }, "/api/v1/capabilities": { "get": { "summary": "Read implemented and enabled provider capabilities", "operationId": "get__api_v1_capabilities", "x-required-scope": "authenticated", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/workspaces": { "get": { "summary": "List developer projects; interactive console session only", "operationId": "get__api_v1_workspaces", "x-required-scope": "console", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] }, "post": { "summary": "Create developer project; interactive console session only", "operationId": "post__api_v1_workspaces", "x-required-scope": "console", "parameters": [], "responses": { "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "timezone": { "type": "string", "default": "UTC" } }, "required": [ "name" ], "additionalProperties": false } } } } } }, "/api/v1/workspaces/{project_id}/keys": { "get": { "summary": "List key metadata in pages of50; interactive admin only", "operationId": "get__api_v1_workspaces_project_id_keys", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 512 }, "description": "Opaque project-bound seek marker from next_cursor. New keys appear after restarting the first page; this is a live list, not a snapshot." } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "keys": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "prefix", "scopes", "expires_at", "revoked_at", "created_at" ], "additionalProperties": false }, "maxItems": 50 }, "next_cursor": { "type": [ "string", "null" ], "maxLength": 512 } }, "required": [ "keys", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] }, "post": { "summary": "Create project key; interactive admin only", "operationId": "post__api_v1_workspaces_project_id_keys", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 80 }, "scopes": { "type": "array", "items": { "enum": [ "customers:read", "customers:write", "connections:read", "connections:write", "executions:read", "executions:write", "events:read", "webhooks:read", "webhooks:write", "usage:read", "media:write", "ads:read", "ads:write", "ads:spend", "ads:operations:read", "inbox:read", "inbox:write", "inbox:operations:read", "analytics:read", "email:read", "email:operations:read", "email:drafts:write", "email:send", "email:modify", "email:sync:write", "inbox:sync:write", "mcp:access" ] }, "minItems": 1, "maxItems": 1000 }, "expires_in_days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "required": [ "name", "scopes" ], "additionalProperties": false } } } } } }, "/api/v1/workspaces/{project_id}/keys/{key_id}": { "delete": { "summary": "Revoke project key; interactive admin only", "operationId": "delete__api_v1_workspaces_project_id_keys_key_id_", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/connect/session": { "get": { "summary": "Read connect session context", "operationId": "get__api_connect_session", "x-required-scope": "connect capability", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "connectSession": [] } ] } }, "/api/connect/start": { "post": { "summary": "Start provider OAuth", "operationId": "post__api_connect_start", "x-required-scope": "connect capability", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } } } }, "security": [ { "connectSession": [] } ] } }, "/api/connect/select": { "post": { "summary": "Choose an OAuth account", "operationId": "post__api_connect_select", "x-required-scope": "connect capability", "parameters": [], "responses": { "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_id": { "type": "string" } }, "required": [ "external_id" ], "additionalProperties": false } } } }, "security": [ { "connectSession": [] } ] } }, "/api/connect/credentials": { "post": { "summary": "Verify bot or app-password credentials", "operationId": "post__api_connect_credentials", "x-required-scope": "connect capability", "parameters": [], "responses": { "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string" }, "target": { "type": "string" }, "identifier": { "type": "string" }, "password": { "type": "string" } }, "required": [], "additionalProperties": false } } } }, "security": [ { "connectSession": [] } ] } }, "/api/v1/projects/{project_id}/email/query": { "post": { "summary": "Gmail-only senders is one bounded collection of at most100 configured sender metadata records. No SMTP details, display names or signatures. Omit limit (only default20 accepted), cursor, body and listing options. Read-only metadata never authorizes a send. Exact message_mime requires message_id, include_body:true and include_full_content:true, with no cursor/body_format or listing filters. Returns up to1MiB of untrusted provider MIME as lossless base64 with byte count and SHA256, including headers/Bcc/body/files/embedded items. Gmail needs recorded and native readonly/modify; Outlook needs recorded and native mail-read consent. Outlook uses immutable IDs and changeKey reads before and after its MIME serialization; changed state requires restart, but this is not atomic or original-wire archival proof. Oversized responses fail without truncation. Never render, execute or follow any exported content. Read one authorized mailbox; Gmail-only message_state requires message_id and returns minimal labels/history/revision for explicit reviewed trash/restore, without body, folder selection or pagination. Gmail thread listing and Gmail/Outlook thread message references omit all bodies. Exact message/draft bodies require explicit opt-in. Gmail thread pages reject changed history/reference order and bound the native inventory to1000; Outlook conversation pages remain live.", "operationId": "post__api_v1_projects_project_id_email_query", "x-required-scope": "email:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "enum": [ "gmail", "outlook" ] }, "resource": { "enum": [ "senders", "drafts", "draft", "messages", "message", "message_state", "message_mime", "threads", "thread", "folders", "folder", "attachments", "attachment", "attached_message", "attached_event", "attached_contact", "changes" ] }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "next_cursor": { "type": [ "string", "null" ] }, "sync_cursor": { "type": [ "string", "null" ] }, "thread_context": { "anyOf": [ { "type": "object", "properties": { "provider": { "enum": [ "gmail", "outlook" ] }, "thread_id": { "type": "string" }, "history_id": { "type": [ "string", "null" ] }, "reference_count": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "pagination": { "enum": [ "verified_reference_page", "native_live_page" ] } }, "required": [ "provider", "thread_id", "history_id", "reference_count", "pagination" ], "additionalProperties": false }, { "type": "null" } ] }, "read_only": { "const": true }, "complete_snapshot": { "const": false }, "sync_mode": { "enum": [ "baseline", "delta", "snapshot_or_delta", null ] }, "fetched_at": { "type": "string", "format": "date-time" }, "content_is_untrusted": { "const": true } }, "required": [ "provider", "resource", "data", "next_cursor", "sync_cursor", "thread_context", "read_only", "complete_snapshot", "sync_mode", "fetched_at", "content_is_untrusted" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "resource": { "const": "senders" } } }, "then": { "properties": { "provider": { "const": "gmail" }, "data": { "type": "array", "maxItems": 100, "items": { "type": "object", "properties": { "from_email": { "type": "string", "format": "email", "maxLength": 254 }, "reply_to": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "is_primary": { "type": [ "boolean", "null" ] }, "is_default": { "type": [ "boolean", "null" ] }, "verification_status": { "enum": [ "verificationStatusUnspecified", "accepted", "pending", null ] }, "external_relay": { "type": "boolean" }, "send_eligible": { "type": "boolean" }, "metadata_only": { "const": true } }, "required": [ "from_email", "reply_to", "is_primary", "is_default", "verification_status", "external_relay", "send_eligible", "metadata_only" ], "additionalProperties": false } }, "next_cursor": { "type": "null" }, "sync_cursor": { "type": "null" }, "sync_mode": { "type": "null" }, "thread_context": { "type": "null" } } } }, { "if": { "properties": { "resource": { "const": "message_mime" } } }, "then": { "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 1, "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "format": { "const": "message/rfc822" }, "encoding": { "const": "base64" }, "content_base64": { "type": "string", "minLength": 4, "maxLength": 1398104, "contentEncoding": "base64" }, "size_bytes": { "type": "integer", "minimum": 1, "maximum": 1048576 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "representation": { "const": "provider_mime" }, "truncated": { "const": false }, "content_is_untrusted": { "const": true } }, "required": [ "id", "format", "encoding", "content_base64", "size_bytes", "sha256", "representation", "truncated", "content_is_untrusted" ], "additionalProperties": false } }, "next_cursor": { "type": "null" }, "sync_cursor": { "type": "null" }, "sync_mode": { "type": "null" }, "thread_context": { "type": "null" } } } } ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "resource": { "enum": [ "senders", "drafts", "draft", "messages", "message", "message_state", "message_mime", "threads", "thread", "folders", "folder", "attachments", "attachment", "attached_message", "attached_event", "attached_contact", "changes" ] }, "thread_id": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^[A-Za-z0-9_+=/-]+$" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "attachment_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "folder_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "cursor": { "type": "string", "maxLength": 16000 }, "include_body": { "type": "boolean", "default": false }, "include_full_content": { "const": true, "description": "message_mime only, with include_body:true. Full untrusted headers/Bcc/body/files/embedded data; provider serialization, not guaranteed original-wire archive. At most1MiB decoded bytes, never truncated." }, "include_item_content": { "const": true, "description": "Required for attached_event/contact with include_nested_content:true. Selected embedded fields only; no separate calendar/contact permission or action. Native event local time and timezone are preserved without conversion." }, "include_nested_content": { "const": true, "description": "Required for Outlook attached_message with include_body:true, or attached_event/contact with include_item_content:true. Native expansion may retrieve nested content; unselected data is suppressed. No body_format or cursor." }, "body_format": { "enum": [ "text", "html" ], "description": "Requires message/draft and include_body=true. Gmail selects the requested native alternative, or returns null; default prefers text with HTML fallback. Graph requests native conversion. Gmail body.charset reports the selected decoded encoding; absent charset defaults to ASCII, unsupported charsets and malformed bytes fail, and truncation preserves surrogate pairs. Supported charsets are documented in the mail guide. Untrusted output is never rendered." }, "search": { "type": "string", "minLength": 1, "maxLength": 512, "description": "Native Gmail q or Outlook KQL; Microsoft returns at most 1000 search matches." }, "include_spam_trash": { "type": "boolean", "description": "Gmail message or thread listing only" }, "include_hidden_folders": { "type": "boolean", "description": "Outlook folder listing only" } }, "required": [ "customer_id", "connection_id", "resource" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "resource": { "const": "senders" } } }, "then": { "properties": { "limit": { "const": 20 } }, "not": { "required": [ "cursor" ] } } }, { "if": { "properties": { "resource": { "const": "message_mime" } } }, "then": { "required": [ "include_body", "include_full_content" ], "properties": { "include_body": { "const": true } } }, "else": { "not": { "required": [ "include_full_content" ] } } }, { "if": { "properties": { "resource": { "const": "attached_message" } } }, "then": { "required": [ "include_body", "include_nested_content" ], "properties": { "include_body": { "const": true }, "include_nested_content": { "const": true } } } }, { "if": { "properties": { "resource": { "enum": [ "attached_event", "attached_contact" ] } } }, "then": { "required": [ "include_item_content", "include_nested_content" ], "properties": { "include_item_content": { "const": true }, "include_nested_content": { "const": true }, "include_body": { "const": false } } }, "else": { "not": { "required": [ "include_item_content" ] } } }, { "if": { "properties": { "resource": { "not": { "enum": [ "attached_message", "attached_event", "attached_contact" ] } } } }, "then": { "not": { "required": [ "include_nested_content" ] } } }, { "if": { "required": [ "body_format" ] }, "then": { "properties": { "resource": { "enum": [ "message", "draft" ] }, "include_body": { "const": true } }, "required": [ "include_body" ] } }, { "if": { "properties": { "resource": { "const": "thread" } } }, "then": { "required": [ "thread_id" ] }, "else": { "not": { "required": [ "thread_id" ] } } }, { "if": { "properties": { "resource": { "const": "folder" } } }, "then": { "required": [ "folder_id" ] } }, { "if": { "properties": { "resource": { "const": "draft" } } }, "then": { "required": [ "draft_id" ] }, "else": { "not": { "required": [ "draft_id" ] } } }, { "if": { "properties": { "resource": { "enum": [ "message", "message_state", "message_mime", "attachments", "attachment", "attached_message", "attached_event", "attached_contact" ] } } }, "then": { "required": [ "message_id" ] }, "else": { "not": { "required": [ "message_id" ] } } }, { "if": { "properties": { "resource": { "enum": [ "attachment", "attached_message", "attached_event", "attached_contact" ] } } }, "then": { "required": [ "attachment_id" ] }, "else": { "not": { "required": [ "attachment_id" ] } } }, { "if": { "properties": { "resource": { "enum": [ "message", "message_state", "message_mime", "draft", "attachment", "attached_message", "attached_event", "attached_contact", "folder" ] } } }, "then": { "not": { "required": [ "cursor" ] } } }, { "if": { "properties": { "resource": { "not": { "enum": [ "messages", "threads", "changes", "folders", "folder" ] } } } }, "then": { "not": { "required": [ "folder_id" ] } } }, { "if": { "properties": { "resource": { "not": { "enum": [ "message", "draft", "attached_message", "message_mime" ] } } } }, "then": { "properties": { "include_body": { "const": false } } } }, { "if": { "properties": { "resource": { "not": { "enum": [ "messages", "threads" ] } } } }, "then": { "not": { "anyOf": [ { "required": [ "search" ] }, { "required": [ "include_spam_trash" ] } ] } } }, { "if": { "properties": { "resource": { "not": { "const": "folders" } } } }, "then": { "not": { "required": [ "include_hidden_folders" ] } } } ] } } } } } }, "/api/v1/projects/{project_id}/email/syncs/{sync_id}/push": { "post": { "summary": "Explicitly enable whole-mailbox Gmail push and automatic renewal on an existing resolved active tracker. Same user/key as tracker creator; authenticated Pub/Sub configured by operator. Preserves checkpoints and polling fallback; no send permission.", "operationId": "post__api_v1_projects_project_id_email_syncs_sync_id_push", "x-required-scope": "email:read and email:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "sync_id": { "type": "string", "format": "uuid" }, "enabled": { "const": true }, "replayed": { "type": "boolean" }, "delivery_confirmed": { "const": false } }, "required": [ "sync_id", "enabled", "replayed", "delivery_confirmed" ], "additionalProperties": false } }, "required": [ "push" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "watch_scope": { "const": "whole_mailbox" }, "enable_automatic_renewal": { "const": true } }, "required": [ "customer_id", "expected_revision", "watch_scope", "enable_automatic_renewal" ], "additionalProperties": false } } } } }, "get": { "summary": "Read current Gmail push authorization, configuration, renewal/error state and expiry; active is not delivery proof", "operationId": "get__api_v1_projects_project_id_email_syncs_sync_id_push", "x-required-scope": "email:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "sync_id": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "active": { "type": "boolean" }, "authorized": { "type": "boolean" }, "configuration_matches": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "renew_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_hint_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "failures": { "type": "integer" }, "delivery_confirmed": { "const": false }, "polling_fallback": { "const": true } }, "required": [ "sync_id", "enabled", "active", "authorized", "configuration_matches", "expires_at", "renew_at", "last_hint_at", "error_code", "failures", "delivery_confirmed", "polling_fallback" ], "additionalProperties": false } }, "required": [ "push" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "delete": { "summary": "Disable local Gmail routing/renewal, preserving poller and shared native watch", "operationId": "delete__api_v1_projects_project_id_email_syncs_sync_id_push", "x-required-scope": "email:read and email:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, { "name": "disable_local_delivery", "in": "query", "required": true, "schema": { "const": "true" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "sync_id": { "type": "string", "format": "uuid" }, "enabled": { "const": false }, "native_watch_stopped": { "const": false } }, "required": [ "sync_id", "enabled", "native_watch_stopped" ], "additionalProperties": false } }, "required": [ "push" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/email/syncs/{sync_id}/outlook-push": { "post": { "summary": "Explicitly enable whole-mailbox Outlook push and automatic renewal on an existing resolved active tracker. Same user/key as tracker creator; Microsoft Graph basic notifications configured by operator; delegated Mail.Read required. Preserves checkpoints and polling fallback; no send permission.", "operationId": "post__api_v1_projects_project_id_email_syncs_sync_id_outlook_push", "x-required-scope": "email:read and email:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "sync_id": { "type": "string", "format": "uuid" }, "enabled": { "const": true }, "replayed": { "type": "boolean" }, "delivery_confirmed": { "const": false } }, "required": [ "sync_id", "enabled", "replayed", "delivery_confirmed" ], "additionalProperties": false } }, "required": [ "push" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "watch_scope": { "const": "whole_mailbox" }, "enable_automatic_renewal": { "const": true } }, "required": [ "customer_id", "expected_revision", "watch_scope", "enable_automatic_renewal" ], "additionalProperties": false } } } } }, "get": { "summary": "Read current Outlook push authorization, configuration, renewal/error state and expiry; active is not delivery proof", "operationId": "get__api_v1_projects_project_id_email_syncs_sync_id_outlook_push", "x-required-scope": "email:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "sync_id": { "type": "string", "format": "uuid" }, "enabled": { "type": "boolean" }, "active": { "type": "boolean" }, "authorized": { "type": "boolean" }, "configuration_matches": { "type": "boolean" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "renew_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_hint_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "failures": { "type": "integer" }, "delivery_confirmed": { "const": false }, "polling_fallback": { "const": true }, "subscription_id": { "type": [ "string", "null" ], "format": "uuid" }, "last_lifecycle": { "type": [ "string", "null" ] } }, "required": [ "sync_id", "enabled", "active", "authorized", "configuration_matches", "expires_at", "renew_at", "last_hint_at", "error_code", "failures", "delivery_confirmed", "polling_fallback", "subscription_id", "last_lifecycle" ], "additionalProperties": false } }, "required": [ "push" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "delete": { "summary": "Disable local Outlook routing/renewal, preserving poller and shared native watch", "operationId": "delete__api_v1_projects_project_id_email_syncs_sync_id_outlook_push", "x-required-scope": "email:read and email:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, { "name": "disable_local_delivery", "in": "query", "required": true, "schema": { "const": "true" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "push": { "type": "object", "properties": { "sync_id": { "type": "string", "format": "uuid" }, "enabled": { "const": false }, "native_watch_stopped": { "const": false } }, "required": [ "sync_id", "enabled", "native_watch_stopped" ], "additionalProperties": false } }, "required": [ "push" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/webhooks/outlook": { "post": { "summary": "Microsoft Graph basic change/lifecycle notifications. Secret clientState hash must match bound callback and current registered native subscription. Durably wakes delta polling without accepting content or changing checkpoints. ValidationToken echoes as text/plain; subscriptions require HTTPS.", "security": [], "parameters": [ { "name": "binding", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" } }, { "name": "validationToken", "in": "query", "schema": { "type": "string", "maxLength": 1024 } } ], "responses": { "200": { "description": "URL validation challenge echoed as text/plain" }, "202": { "description": "Authenticated hints durably accepted; unknown subscriptions ignored" }, "400": { "description": "Invalid envelope or binding" }, "503": { "description": "Disabled, paused or persistence unavailable" } } } }, "/webhooks/meta/{appId}/deauthorize": { "post": { "operationId": "receiveMetaDeauthorization", "summary": "Receive a signed Facebook Login app deauthorization", "security": [], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": false, "required": [ "signed_request" ], "properties": { "signed_request": { "type": "string", "maxLength": 8192 } } } } } }, "responses": { "200": { "description": "Signed historical event durably blocked; bounded credential cleanup scheduled. No customer-data erasure or native-session outcome is asserted." }, "400": { "description": "Invalid signature, app binding or bounded event shape" }, "409": { "description": "Conflicting durable receipt" }, "413": { "description": "Form exceeds byte limit" }, "415": { "description": "application/x-www-form-urlencoded required" }, "503": { "description": "Disabled, maintenance, configuration or durable storage unavailable" } } } }, "/webhooks/meta/{appId}/data-deletion": { "post": { "operationId": "receiveMetaDataDeletionRequest", "summary": "Receive a signed Meta deletion request and initiate affected credential cleanup", "security": [], "parameters": [ { "name": "appId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" } } ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "additionalProperties": false, "required": [ "signed_request" ], "properties": { "signed_request": { "type": "string", "maxLength": 8192 } } } } } }, "responses": { "200": { "description": "Request persisted and matching grant cutoff committed. Full data deletion is not complete.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "confirmation_code": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "url", "confirmation_code" ], "additionalProperties": false } } } }, "400": { "description": "Invalid signed event or form" }, "403": { "description": "Untrusted request origin" }, "409": { "description": "Conflicting request receipt" }, "413": { "description": "Form exceeds byte limit" }, "415": { "description": "Form content type required" }, "503": { "description": "Disabled, maintenance, invalid configuration or durable storage unavailable" } }, "description": "Disabled by default. Durable request intake is distinct from complete data erasure; stored-data scope review remains required. This callback has no user-facing API-key or MCP equivalent." } }, "/privacy/meta-deletion": { "get": { "operationId": "getMetaDataDeletionStatus", "summary": "Private human-readable Meta deletion request status", "security": [], "parameters": [ { "name": "code", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[a-f0-9]{64}$" } } ], "responses": { "200": { "description": "Uncached HTML with credential-cleanup progress and explicit remaining stored-data review. No identity or full-deletion claim.", "content": { "text/html": { "schema": { "type": "string" } } } }, "404": { "description": "Unknown or malformed private status code" }, "503": { "description": "Maintenance or unverifiable persistence" } } } }, "/webhooks/google/security-events": { "post": { "operationId": "receiveGoogleSecurityEvent", "summary": "Receive a signed Google OAuth security event", "security": [], "requestBody": { "required": true, "content": { "application/secevent+jwt": { "schema": { "type": "string", "maxLength": 16384 } } } }, "responses": { "202": { "description": "Verified event durably blocked/scheduled, or a verified non-action event safely ignored. No native cleanup or login-session outcome is asserted." }, "400": { "description": "Invalid signed event" }, "413": { "description": "Event exceeds byte limit" }, "415": { "description": "application/secevent+jwt required" }, "503": { "description": "Disabled, maintenance, discovery/key or durable storage unavailable" } } } }, "/webhooks/gmail": { "post": { "summary": "Authenticated Google Pub/Sub OIDC callback; pinned RS256 issuer/audience/verified service identity, subscription, 10KB payload and 48hour notice window. Durable coalesced wake; history checkpoints untouched.", "security": [], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^Bearer " } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "204": { "description": "Durably scheduled or safely ignored duplicate/stale/unauthorized registration" }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid push identity" }, "413": { "description": "Payload too large" }, "503": { "description": "Disabled, paused, unconfigured or persistence unavailable" } } } }, "/api/v1/projects/{project_id}/inbox/syncs": { "post": { "summary": "Create continued scoped observations using native live pages; up to8 trackers,100 retained batches/10MiB and10000 indexed items per connection. Bodies opt-in. Target eligibility verified by worker, not admission. Missing rows are never deletions. Expired cursors/batches stop with a gap.", "operationId": "post__api_v1_projects_project_id_inbox_syncs", "x-required-scope": "inbox:read and inbox:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required", "deleting" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "replayed": { "type": "boolean" } }, "required": [ "id", "state", "revision", "replayed" ], "additionalProperties": false } }, "required": [ "sync" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "resource": { "enum": [ "conversations", "messages", "media", "comments", "replies", "youtube_threads", "youtube_replies", "facebook_posts", "facebook_comments", "facebook_replies" ] }, "facebook_post_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "facebook_comment_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "youtube_video_id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{11}$" }, "youtube_parent_id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "youtube_moderation": { "enum": [ "published", "heldForReview", "likelySpam" ] }, "conversation_id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "media_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "comment_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "include_body": { "type": "boolean", "default": false }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25 } }, "required": [ "customer_id", "connection_id", "resource" ], "additionalProperties": false, "allOf": [ { "if": { "properties": { "resource": { "enum": [ "facebook_comments", "facebook_replies" ] } } }, "then": { "required": [ "facebook_post_id" ] }, "else": { "not": { "required": [ "facebook_post_id" ] } } }, { "if": { "properties": { "resource": { "const": "facebook_replies" } } }, "then": { "required": [ "facebook_comment_id" ] }, "else": { "not": { "required": [ "facebook_comment_id" ] } } }, { "if": { "properties": { "resource": { "const": "youtube_replies" } } }, "then": { "required": [ "youtube_parent_id" ] }, "else": { "not": { "required": [ "youtube_parent_id" ] } } }, { "if": { "properties": { "resource": { "const": "youtube_threads" } } }, "else": { "not": { "anyOf": [ { "required": [ "youtube_video_id" ] }, { "required": [ "youtube_moderation" ] } ] } } }, { "if": { "properties": { "resource": { "const": "messages" } } }, "then": { "required": [ "conversation_id" ] }, "else": { "not": { "required": [ "conversation_id" ] } } }, { "if": { "properties": { "resource": { "enum": [ "comments", "replies" ] } } }, "then": { "required": [ "media_id" ] }, "else": { "not": { "required": [ "media_id" ] } } }, { "if": { "properties": { "resource": { "const": "replies" } } }, "then": { "required": [ "comment_id" ] }, "else": { "not": { "required": [ "comment_id" ] } } }, { "if": { "properties": { "resource": { "const": "conversations" } } }, "then": { "properties": { "include_body": { "const": false } } } } ] }, "wake_on_messages": { "type": "boolean", "default": false, "description": "Meta conversations/messages only: allow separately consented messages-only notifications to advance an existing tracker, coalesced to at most one new round per minute; no implicit native subscription." }, "interval_seconds": { "type": "integer", "minimum": 300, "maximum": 86400, "default": 900 } }, "required": [ "query" ], "additionalProperties": false } } } } }, "get": { "summary": "List scoped inbox trackers without ciphertext", "operationId": "get__api_v1_projects_project_id_inbox_syncs", "x-required-scope": "inbox:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "connection_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "resource": { "enum": [ "conversations", "messages", "media", "comments", "replies", "youtube_threads", "youtube_replies", "facebook_posts", "facebook_comments", "facebook_replies" ] }, "wake_on_messages": { "type": "boolean" }, "last_push_wake_at": { "type": [ "string", "null" ], "format": "date-time" }, "round_in_progress": { "type": "boolean" }, "interval_seconds": { "type": "integer" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required", "deleting" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "sequence": { "type": "integer" }, "batch_count": { "type": "integer" }, "stored_bytes": { "type": "integer" }, "indexed_count": { "type": "integer" }, "failures": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "last_polled_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "customer_id", "connection_id", "resource", "wake_on_messages", "last_push_wake_at", "round_in_progress", "interval_seconds", "state", "revision", "sequence", "batch_count", "stored_bytes", "indexed_count", "failures", "error_code", "last_polled_at", "last_completed_at", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/inbox/syncs/{sync_id}": { "get": { "summary": "Inspect current inbox tracker revision/backlog/errors", "operationId": "get__api_v1_projects_project_id_inbox_syncs_sync_id_", "x-required-scope": "inbox:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "resource": { "enum": [ "conversations", "messages", "media", "comments", "replies", "youtube_threads", "youtube_replies", "facebook_posts", "facebook_comments", "facebook_replies" ] }, "wake_on_messages": { "type": "boolean" }, "last_push_wake_at": { "type": [ "string", "null" ], "format": "date-time" }, "round_in_progress": { "type": "boolean" }, "interval_seconds": { "type": "integer" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required", "deleting" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "sequence": { "type": "integer" }, "batch_count": { "type": "integer" }, "stored_bytes": { "type": "integer" }, "indexed_count": { "type": "integer" }, "failures": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "last_polled_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "customer_id", "connection_id", "resource", "wake_on_messages", "last_push_wake_at", "round_in_progress", "interval_seconds", "state", "revision", "sequence", "batch_count", "stored_bytes", "indexed_count", "failures", "error_code", "last_polled_at", "last_completed_at", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "sync" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "patch": { "summary": "Pause/resume at current revision; blocked/reset_required requires explicit replacement after resolving the gap", "operationId": "patch__api_v1_projects_project_id_inbox_syncs_sync_id_", "x-required-scope": "inbox:read and inbox:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required", "deleting" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "id", "state", "revision" ], "additionalProperties": false } }, "required": [ "sync" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "enum": [ "active", "paused" ] }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "state", "expected_revision" ], "additionalProperties": false } } } } }, "delete": { "summary": "Fence access and queue bounded cached-data deletion; does not delete native messages", "operationId": "delete__api_v1_projects_project_id_inbox_syncs_sync_id_", "x-required-scope": "inbox:read and inbox:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required", "deleting" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "id", "state", "revision" ], "additionalProperties": false } }, "required": [ "sync" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "confirm_delete": { "const": true } }, "required": [ "expected_revision", "confirm_delete" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/inbox/syncs/{sync_id}/batches": { "get": { "summary": "List current-customer unexpired batch metadata; continue with next_sequence even when batches is empty", "operationId": "get__api_v1_projects_project_id_inbox_syncs_sync_id_batches", "x-required-scope": "inbox:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after_sequence", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 2147483647, "default": 0 } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "batches": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer" }, "round_complete": { "type": "boolean" }, "item_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "sequence", "round_complete", "item_count", "created_at", "expires_at" ], "additionalProperties": false } }, "next_sequence": { "type": [ "integer", "null" ] } }, "required": [ "batches", "next_sequence" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/inbox/syncs/{sync_id}/batches/{batch_id}": { "get": { "summary": "Read encrypted retained observed upserts after rechecking original/current authority. No deletion inference or history-completeness claim; Instagram messages cover at most latest20", "operationId": "get__api_v1_projects_project_id_inbox_syncs_sync_id_batches_batch_id_", "x-required-scope": "inbox:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer" }, "round_complete": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time" }, "sync_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "provider": { "enum": [ "facebook", "instagram", "youtube" ] }, "resource": { "enum": [ "conversations", "messages", "media", "comments", "replies", "youtube_threads", "youtube_replies", "facebook_posts", "facebook_comments", "facebook_replies" ] }, "coverage": { "enum": [ "latest_20_messages", "native_live_pages" ] }, "complete_snapshot": { "const": false }, "observed_at": { "type": "string", "format": "date-time" }, "data": { "type": "array", "items": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "updated_at": { "type": "string", "format": "date-time" }, "participants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "name": { "type": [ "string", "null" ] }, "participant_reference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Facebook Page-scoped pseudonymous correlation for explicitly consented read-watermark events. Not an authorization or individual read proof." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "app_is_thread_owner": { "type": [ "boolean", "null" ] } }, "required": [ "id", "updated_at", "participants" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 600, "pattern": "^(?!.*://)[A-Za-z0-9][A-Za-z0-9_:.=$+/\\-]{0,599}$" }, "created_at": { "type": "string", "format": "date-time" }, "from": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "name": { "type": [ "string", "null" ] }, "participant_reference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Facebook Page-scoped pseudonymous correlation for explicitly consented read-watermark events. Not an authorization or individual read proof." } }, "required": [ "id", "name" ], "additionalProperties": false }, "to": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "name": { "type": [ "string", "null" ] }, "participant_reference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Facebook Page-scoped pseudonymous correlation for explicitly consented read-watermark events. Not an authorization or individual read proof." } }, "required": [ "id", "name" ], "additionalProperties": false } }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "created_at", "from", "to" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "media_type": { "type": "string" }, "media_product_type": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "caption": { "type": [ "string", "null" ] } }, "required": [ "id", "media_type", "media_product_type", "created_at" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "media_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "parent_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "hidden": { "type": "boolean" }, "from": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "username": { "type": [ "string", "null" ] } }, "required": [ "id", "username" ], "additionalProperties": false }, { "type": "null" } ] }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "media_id", "parent_id", "created_at", "hidden", "from" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "page_id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "created_at": { "type": "string", "format": "date-time" }, "published": { "const": true }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "page_id", "created_at", "published" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9]\\d{0,29}(?:_[1-9]\\d{0,29}){0,2}$" }, "post_id": { "type": "string", "pattern": "^[1-9]\\d{0,29}_[1-9]\\d{0,29}$" }, "parent_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "from": { "oneOf": [ { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]{0,29}$" }, "name": { "type": [ "string", "null" ] }, "participant_reference": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$", "description": "Facebook Page-scoped pseudonymous correlation for explicitly consented read-watermark events. Not an authorization or individual read proof." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ] }, "hidden": { "type": [ "boolean", "null" ] }, "private": { "type": [ "boolean", "null" ] }, "revision": { "type": [ "string", "null" ], "pattern": "^[A-Za-z0-9_-]{43}$" }, "can_reply": { "type": [ "boolean", "null" ] }, "can_hide": { "type": [ "boolean", "null" ] }, "can_remove": { "type": [ "boolean", "null" ] }, "reply_count": { "type": [ "string", "null" ] }, "like_count": { "type": [ "string", "null" ] }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "post_id", "parent_id", "created_at", "from", "hidden", "private", "revision", "can_reply", "can_hide", "can_remove", "reply_count", "like_count" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "channel_id": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, "parent_id": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, { "type": "null" } ] }, "author": { "type": "object", "properties": { "channel_id": { "anyOf": [ { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, { "type": "null" } ] }, "display_name": { "type": [ "string", "null" ] } }, "required": [ "channel_id", "display_name" ], "additionalProperties": false }, "like_count": { "type": "string", "pattern": "^[0-9]+$" }, "moderation_status": { "enum": [ "published", "heldForReview", "likelySpam", "rejected", null ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "etag", "channel_id", "parent_id", "author", "like_count", "moderation_status", "created_at", "updated_at" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "channel_id": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, "video_id": { "type": [ "string", "null" ] }, "can_reply": { "type": "boolean" }, "is_public": { "type": "boolean" }, "reply_count": { "type": "string", "pattern": "^[0-9]+$" }, "comment": { "type": "object", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, "etag": { "type": "string", "minLength": 1, "maxLength": 256 }, "channel_id": { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, "parent_id": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z0-9_-][A-Za-z0-9_.-]{0,255}$" }, { "type": "null" } ] }, "author": { "type": "object", "properties": { "channel_id": { "anyOf": [ { "type": "string", "pattern": "^UC[A-Za-z0-9_-]{22}$" }, { "type": "null" } ] }, "display_name": { "type": [ "string", "null" ] } }, "required": [ "channel_id", "display_name" ], "additionalProperties": false }, "like_count": { "type": "string", "pattern": "^[0-9]+$" }, "moderation_status": { "enum": [ "published", "heldForReview", "likelySpam", "rejected", null ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "text": { "type": [ "string", "null" ] } }, "required": [ "id", "etag", "channel_id", "parent_id", "author", "like_count", "moderation_status", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "id", "etag", "channel_id", "video_id", "can_reply", "is_public", "reply_count", "comment" ], "additionalProperties": false } ] } } }, "required": [ "id", "sequence", "round_complete", "created_at", "expires_at", "sync_id", "customer_id", "connection_id", "provider", "resource", "coverage", "complete_snapshot", "observed_at", "data" ], "additionalProperties": false }, "content_is_untrusted": { "const": true } }, "required": [ "batch", "content_is_untrusted" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "delete": { "summary": "Idempotently acknowledge only after durable downstream processing; frees cached data, never marks native messages read", "operationId": "delete__api_v1_projects_project_id_inbox_syncs_sync_id_batches_batch_id_", "x-required-scope": "inbox:read and inbox:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledged": { "const": true } }, "required": [ "acknowledged" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/email/syncs": { "post": { "summary": "Start bounded metadata/reference polling, up to8 scopes per connection; resolves native folder/label IDs and fences credentials. All scopes share100 unacknowledged batches/10MiB. Explicit legacy replacement required; no provider push subscription", "operationId": "post__api_v1_projects_project_id_email_syncs", "x-required-scope": "email:read and email:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "replayed": { "type": "boolean" }, "expired_history_policy": { "enum": [ "stop", "resnapshot" ] }, "generation": { "type": "integer", "minimum": 1 }, "folder_id": { "type": [ "string", "null" ] }, "folder_resolved": { "const": true } }, "required": [ "id", "state", "revision", "replayed", "expired_history_policy", "generation", "folder_id", "folder_resolved" ], "additionalProperties": false } }, "required": [ "sync" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": "string", "minLength": 1, "maxLength": 1000, "pattern": "^[A-Za-z0-9_+=/-]+$" }, "interval_seconds": { "type": "integer", "minimum": 300, "maximum": 86400, "default": 900 }, "page_size": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "expired_history_policy": { "enum": [ "stop", "resnapshot" ], "default": "stop", "description": "Gmail only: opt-in bounded snapshot restart after expired history, with reset/gap markers and a new generation; never recover missing events" } }, "required": [ "customer_id", "connection_id" ], "additionalProperties": false } } } } }, "get": { "summary": "List current-customer mailbox trackers; follow next_cursor as after even when data is empty", "operationId": "get__api_v1_projects_project_id_email_syncs", "x-required-scope": "email:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "customer_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "connection_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "expired_history_policy": { "enum": [ "stop", "resnapshot" ] }, "generation": { "type": "integer", "minimum": 1 }, "last_reset_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": [ "string", "null" ] }, "folder_resolved": { "type": "boolean" }, "interval_seconds": { "type": "integer" }, "page_size": { "type": "integer" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "sequence": { "type": "integer" }, "batch_count": { "type": "integer" }, "stored_bytes": { "type": "integer" }, "failures": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "last_polled_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "expired_history_policy", "generation", "last_reset_at", "id", "customer_id", "connection_id", "folder_id", "folder_resolved", "interval_seconds", "page_size", "state", "revision", "sequence", "batch_count", "stored_bytes", "failures", "error_code", "last_polled_at", "last_completed_at", "created_at", "updated_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/email/syncs/{sync_id}": { "get": { "summary": "Inspect a mailbox tracker and its current revision", "operationId": "get__api_v1_projects_project_id_email_syncs_sync_id_", "x-required-scope": "email:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "expired_history_policy": { "enum": [ "stop", "resnapshot" ] }, "generation": { "type": "integer", "minimum": 1 }, "last_reset_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": [ "string", "null" ] }, "folder_resolved": { "type": "boolean" }, "interval_seconds": { "type": "integer" }, "page_size": { "type": "integer" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 }, "sequence": { "type": "integer" }, "batch_count": { "type": "integer" }, "stored_bytes": { "type": "integer" }, "failures": { "type": "integer" }, "error_code": { "type": [ "string", "null" ] }, "last_polled_at": { "type": [ "string", "null" ], "format": "date-time" }, "last_completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "expired_history_policy", "generation", "last_reset_at", "id", "customer_id", "connection_id", "folder_id", "folder_resolved", "interval_seconds", "page_size", "state", "revision", "sequence", "batch_count", "stored_bytes", "failures", "error_code", "last_polled_at", "last_completed_at", "created_at", "updated_at" ], "additionalProperties": false } }, "required": [ "sync" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "patch": { "summary": "Pause/resume using expected revision; blocked/reset_required needs explicit delete and new baseline", "operationId": "patch__api_v1_projects_project_id_email_syncs_sync_id_", "x-required-scope": "email:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "enum": [ "active", "paused", "blocked", "reset_required" ] }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "id", "state", "revision" ], "additionalProperties": false } }, "required": [ "sync" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "state": { "enum": [ "active", "paused" ] }, "expected_revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "state", "expected_revision" ], "additionalProperties": false } } } } }, "delete": { "summary": "Delete a tracker and its retained encrypted data; fence in-flight results", "operationId": "delete__api_v1_projects_project_id_email_syncs_sync_id_", "x-required-scope": "email:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "expected_revision", "in": "query", "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 2147483646 } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sync": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "const": "deleted" }, "revision": { "type": "integer", "minimum": 1, "maximum": 2147483646 } }, "required": [ "id", "state", "revision" ], "additionalProperties": false } }, "required": [ "sync" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/email/syncs/{sync_id}/batches/{batch_id}": { "get": { "summary": "Read an unexpired mailbox change batch; references/state only, untrusted content", "operationId": "get__api_v1_projects_project_id_email_syncs_sync_id_batches_batch_id_", "x-required-scope": "email:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "sync_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "folder_id": { "type": [ "string", "null" ] }, "sequence": { "type": "integer" }, "mode": { "enum": [ "baseline", "snapshot", "changes", "reset" ] }, "generation": { "type": "integer", "minimum": 1 }, "reset_reason": { "enum": [ "gmail_history_expired", null ] }, "round_complete": { "type": "boolean" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "expires_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "sync_id", "customer_id", "connection_id", "folder_id", "sequence", "mode", "generation", "reset_reason", "round_complete", "data", "expires_at", "created_at" ], "additionalProperties": false }, "content_is_untrusted": { "const": true } }, "required": [ "batch", "content_is_untrusted" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } }, "delete": { "summary": "Acknowledge durably consumed data and remove the cached batch; idempotent", "operationId": "delete__api_v1_projects_project_id_email_syncs_sync_id_batches_batch_id_", "x-required-scope": "email:read and email:sync:write; owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "sync_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "batch_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledged": { "const": true } }, "required": [ "acknowledged" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/email/uploads/{id}": { "get": { "summary": "Read local Outlook upload progress; no capability or file content. Inspect operation receipt before submitting the next chunk.", "operationId": "get__api_v1_projects_project_id_email_uploads_id_", "x-required-scope": "email:operations:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "$ref": "#/components/schemas/EmailUpload" } }, "required": [ "upload" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/email/uploads/{id}/abandon": { "post": { "summary": "Explicitly abandon local upload tracking after native investigation and acknowledgement of unknown operations. Pending/leased operations block this. Does not confirm native cleanup.", "operationId": "post__api_v1_projects_project_id_email_uploads_id_abandon", "x-required-scope": "email:operations:read + email:read + email:drafts:write; owner/admin", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "upload": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "const": "abandoned" }, "native_cleanup_confirmed": { "const": false } }, "required": [ "id", "state", "native_cleanup_confirmed" ], "additionalProperties": false } }, "required": [ "upload" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_unknown_native_state": { "const": true }, "note": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "confirm_unknown_native_state", "note" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/email/operations": { "post": { "summary": "Queue mail, draft lifecycle, reply/forward, message-state or folder changes. Folder operations need email:read+email:modify and use a mailbox-wide ordered lane. Non-create folder actions need metadata expected_revision; Outlook delete/move/copy explicitly confirm contents; Gmail label deletion never deletes messages. Re-read canonical folder/revision after mutation; existing-draft actions require expected_revision; delete requires confirm_delete; unknown outcomes block that draft until acknowledgment. Native prechecks are not atomic against outside edits.", "operationId": "post__api_v1_projects_project_id_email_operations", "x-required-scope": "email:send or email:drafts:write; reply/forward and existing-draft actions additionally require email:read; state/label/move mutations require email:modify", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 8, "maxLength": 200, "pattern": "^[A-Za-z0-9_.:-]+$" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "replayed": { "type": "boolean" } }, "required": [ "id", "status", "replayed" ], "additionalProperties": false }, "delivery_confirmed": { "const": false } }, "required": [ "operation", "delivery_confirmed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "begin_attachment_upload" }, "upload_id": { "type": "string", "format": "uuid" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "minLength": 1, "maxLength": 1000 }, "filename": { "type": "string", "minLength": 1, "maxLength": 120, "description": "Maximum180 UTF-8 bytes; no controls, path separators, dot or dot-dot" }, "size_bytes": { "type": "integer", "minimum": 3000000, "maximum": 150000000 } }, "required": [ "customer_id", "connection_id", "action", "upload_id", "draft_id", "expected_revision", "filename", "size_bytes" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "put_attachment_chunk" }, "upload_id": { "type": "string", "format": "uuid" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "offset": { "type": "integer", "minimum": 0, "maximum": 149999999 }, "content_base64": { "type": "string", "minLength": 4, "maxLength": 1398104, "description": "Canonical base64 for1–1048576 bytes. Offset must equal committed next_offset; wait for each successful receipt." } }, "required": [ "customer_id", "connection_id", "action", "upload_id", "draft_id", "offset", "content_base64" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "cancel_attachment_upload" }, "upload_id": { "type": "string", "format": "uuid" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "confirm_cancel": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "upload_id", "draft_id", "confirm_cancel" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "add_draft_attachment" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "minLength": 1, "maxLength": 1000 }, "attachment": { "type": "object", "properties": { "content_id": { "type": "string", "minLength": 3, "maxLength": 240, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$", "description": "Optional inline PNG/JPEG/GIF Content-ID. Unique within the message and referenced literally as cid:ID in HTML. No remote fetch." }, "filename": { "type": "string", "minLength": 1, "maxLength": 120, "description": "No control characters or path separators; at most180 UTF8 bytes" }, "content_type": { "type": "string", "maxLength": 120 }, "content_base64": { "type": "string", "maxLength": 4000000, "description": "Canonical padded base64; at most2999999 aggregate decoded bytes across at most6 files" } }, "required": [ "filename", "content_type", "content_base64" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "action", "draft_id", "expected_revision", "attachment" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "remove_draft_attachment" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "minLength": 1, "maxLength": 1000 }, "attachment_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "confirm_delete": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "draft_id", "expected_revision", "attachment_id", "confirm_delete" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "create_folder" }, "name": { "type": "string", "minLength": 1, "maxLength": 225, "description": "Maximum225 UTF-8 bytes; trimmed; no controls" }, "parent_folder_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "is_hidden": { "type": "boolean" } }, "required": [ "customer_id", "connection_id", "action", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "rename_folder" }, "folder_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "name": { "type": "string", "minLength": 1, "maxLength": 225 } }, "required": [ "customer_id", "connection_id", "action", "folder_id", "expected_revision", "name" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "delete_folder" }, "folder_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "confirm_delete": { "const": true }, "confirm_delete_contents": { "const": true, "description": "Required for Outlook; omitted for Gmail" } }, "required": [ "customer_id", "connection_id", "action", "folder_id", "expected_revision", "confirm_delete" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "move_folder" }, "folder_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "destination_folder_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "confirm_move_contents": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "folder_id", "expected_revision", "destination_folder_id", "confirm_move_contents" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "copy_folder" }, "folder_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "destination_folder_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "confirm_copy_contents": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "folder_id", "expected_revision", "destination_folder_id", "confirm_copy_contents" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "send_gmail_alias" }, "from_email": { "type": "string", "format": "email", "maxLength": 254, "pattern": "^[\\x21-\\x7e]+$" }, "expected_reply_to": { "type": [ "string", "null" ], "format": "email", "maxLength": 254, "pattern": "^[\\x21-\\x7e]+$" }, "expected_external_relay": { "type": "boolean" }, "confirm_sender": { "const": true }, "message": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "minItems": 1, "maxItems": 20 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "subject": { "type": "string", "maxLength": 998 }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "html": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Optional untrusted HTML; combined text+HTML maximum100000 characters. Gmail preserves a MIME text alternative; Graph JSON selects HTML body." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "content_id": { "type": "string", "minLength": 3, "maxLength": 240, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$", "description": "Optional inline PNG/JPEG/GIF Content-ID. Unique within the message and referenced literally as cid:ID in HTML. No remote fetch." }, "filename": { "type": "string", "minLength": 1, "maxLength": 120, "description": "No control characters or path separators; at most180 UTF8 bytes" }, "content_type": { "type": "string", "maxLength": 120 }, "content_base64": { "type": "string", "maxLength": 4000000, "description": "Canonical padded base64; at most2999999 aggregate decoded bytes across at most6 files" } }, "required": [ "filename", "content_type", "content_base64" ], "additionalProperties": false }, "maxItems": 6 } }, "required": [ "to", "subject", "text" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "action", "from_email", "expected_reply_to", "expected_external_relay", "confirm_sender", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "send" }, "message": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "minItems": 1, "maxItems": 20 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "subject": { "type": "string", "maxLength": 998 }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "html": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Optional untrusted HTML; combined text+HTML maximum100000 characters. Gmail preserves a MIME text alternative; Graph JSON selects HTML body." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "content_id": { "type": "string", "minLength": 3, "maxLength": 240, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$", "description": "Optional inline PNG/JPEG/GIF Content-ID. Unique within the message and referenced literally as cid:ID in HTML. No remote fetch." }, "filename": { "type": "string", "minLength": 1, "maxLength": 120, "description": "No control characters or path separators; at most180 UTF8 bytes" }, "content_type": { "type": "string", "maxLength": 120 }, "content_base64": { "type": "string", "maxLength": 4000000, "description": "Canonical padded base64; at most2999999 aggregate decoded bytes across at most6 files" } }, "required": [ "filename", "content_type", "content_base64" ], "additionalProperties": false }, "maxItems": 6 } }, "required": [ "to", "subject", "text" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "action", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "create_draft" }, "message": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "minItems": 1, "maxItems": 20 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "subject": { "type": "string", "maxLength": 998 }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "html": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Optional untrusted HTML; combined text+HTML maximum100000 characters. Gmail preserves a MIME text alternative; Graph JSON selects HTML body." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "content_id": { "type": "string", "minLength": 3, "maxLength": 240, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$", "description": "Optional inline PNG/JPEG/GIF Content-ID. Unique within the message and referenced literally as cid:ID in HTML. No remote fetch." }, "filename": { "type": "string", "minLength": 1, "maxLength": 120, "description": "No control characters or path separators; at most180 UTF8 bytes" }, "content_type": { "type": "string", "maxLength": 120 }, "content_base64": { "type": "string", "maxLength": 4000000, "description": "Canonical padded base64; at most2999999 aggregate decoded bytes across at most6 files" } }, "required": [ "filename", "content_type", "content_base64" ], "additionalProperties": false }, "maxItems": 6 } }, "required": [ "to", "subject", "text" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "action", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "create_reply_draft" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "message": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "minItems": 1, "maxItems": 20 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "html": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Optional untrusted HTML; combined text+HTML maximum100000 characters. Gmail preserves a MIME text alternative; Graph JSON selects HTML body." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "content_id": { "type": "string", "minLength": 3, "maxLength": 240, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$", "description": "Optional inline PNG/JPEG/GIF Content-ID. Unique within the message and referenced literally as cid:ID in HTML. No remote fetch." }, "filename": { "type": "string", "minLength": 1, "maxLength": 120, "description": "No control characters or path separators; at most180 UTF8 bytes" }, "content_type": { "type": "string", "maxLength": 120 }, "content_base64": { "type": "string", "maxLength": 4000000, "description": "Canonical padded base64; at most2999999 aggregate decoded bytes across at most6 files" } }, "required": [ "filename", "content_type", "content_base64" ], "additionalProperties": false }, "maxItems": 6 } }, "required": [ "to", "text" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "action", "message_id", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "reply" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "message": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "minItems": 1, "maxItems": 20 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "html": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Optional untrusted HTML; combined text+HTML maximum100000 characters. Gmail preserves a MIME text alternative; Graph JSON selects HTML body." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "content_id": { "type": "string", "minLength": 3, "maxLength": 240, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$", "description": "Optional inline PNG/JPEG/GIF Content-ID. Unique within the message and referenced literally as cid:ID in HTML. No remote fetch." }, "filename": { "type": "string", "minLength": 1, "maxLength": 120, "description": "No control characters or path separators; at most180 UTF8 bytes" }, "content_type": { "type": "string", "maxLength": 120 }, "content_base64": { "type": "string", "maxLength": 4000000, "description": "Canonical padded base64; at most2999999 aggregate decoded bytes across at most6 files" } }, "required": [ "filename", "content_type", "content_base64" ], "additionalProperties": false }, "maxItems": 6 } }, "required": [ "to", "text" ], "additionalProperties": false } }, "required": [ "customer_id", "connection_id", "action", "message_id", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "forward" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "to": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "minItems": 1, "maxItems": 20 }, "text": { "type": "string", "maxLength": 10000 }, "include_original_attachments": { "type": "boolean", "default": false }, "include_original_html": { "const": true, "description": "Gmail-only explicit original HTML quotation; literal owned CID images also require independent attachment consent. No remote fetch or rendering. Existing body/file bounds and final current authority apply." } }, "required": [ "customer_id", "connection_id", "action", "message_id", "to", "text" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "send_draft" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "minLength": 1, "maxLength": 1000 } }, "required": [ "customer_id", "connection_id", "action", "draft_id", "expected_revision" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "update_draft" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "minLength": 1, "maxLength": 1000 }, "message": { "type": "object", "properties": { "to": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "minItems": 1, "maxItems": 20 }, "cc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "bcc": { "type": "array", "items": { "type": "string", "format": "email", "maxLength": 254 }, "maxItems": 20 }, "subject": { "type": "string", "maxLength": 998 }, "text": { "type": "string", "minLength": 1, "maxLength": 100000 }, "html": { "type": "string", "minLength": 1, "maxLength": 100000, "description": "Optional untrusted HTML; combined text+HTML maximum100000 characters. Gmail preserves a MIME text alternative; Graph JSON selects HTML body." }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "content_id": { "type": "string", "minLength": 3, "maxLength": 240, "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]*(?:\\.[A-Za-z0-9_-]+)*@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)*$", "description": "Optional inline PNG/JPEG/GIF Content-ID. Unique within the message and referenced literally as cid:ID in HTML. No remote fetch." }, "filename": { "type": "string", "minLength": 1, "maxLength": 120, "description": "No control characters or path separators; at most180 UTF8 bytes" }, "content_type": { "type": "string", "maxLength": 120 }, "content_base64": { "type": "string", "maxLength": 4000000, "description": "Canonical padded base64; at most2999999 aggregate decoded bytes across at most6 files" } }, "required": [ "filename", "content_type", "content_base64" ], "additionalProperties": false }, "maxItems": 6 } }, "required": [ "to", "subject", "text" ], "additionalProperties": false }, "preserve_attachments": { "const": true, "description": "Outlook-only; retain existing attachments during content update; replacement attachments must be empty" } }, "required": [ "customer_id", "connection_id", "action", "draft_id", "expected_revision", "message" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "delete_draft" }, "draft_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "minLength": 1, "maxLength": 1000 }, "confirm_delete": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "draft_id", "expected_revision", "confirm_delete" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "trash_message" }, "expected_provider": { "const": "gmail" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "confirm_trash": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "expected_provider", "message_id", "expected_revision", "confirm_trash" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "restore_message" }, "expected_provider": { "const": "gmail" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "expected_revision": { "type": "string", "pattern": "^[A-Za-z0-9_-]{43}$" }, "confirm_restore": { "const": true } }, "required": [ "customer_id", "connection_id", "action", "expected_provider", "message_id", "expected_revision", "confirm_restore" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "set_read_state" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "is_read": { "type": "boolean" } }, "required": [ "customer_id", "connection_id", "action", "message_id", "is_read" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "move_message" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "destination_folder_id": { "type": "string", "minLength": 1, "maxLength": 1000, "description": "Outlook destination folder id or well-known folder name" } }, "required": [ "customer_id", "connection_id", "action", "message_id", "destination_folder_id" ], "additionalProperties": false }, { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "modify_labels" }, "message_id": { "type": "string", "minLength": 1, "maxLength": 1000 }, "add_label_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "maxItems": 100, "uniqueItems": true, "default": [] }, "remove_label_ids": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 1000 }, "maxItems": 100, "uniqueItems": true, "default": [] } }, "required": [ "customer_id", "connection_id", "action", "message_id" ], "additionalProperties": false, "description": "Gmail-only label changes; at least one change and no label in both lists", "anyOf": [ { "required": [ "add_label_ids" ], "properties": { "add_label_ids": { "minItems": 1 } } }, { "required": [ "remove_label_ids" ], "properties": { "remove_label_ids": { "minItems": 1 } } } ] } ] } } } } } }, "/api/v1/projects/{project_id}/email/operations/{operation_id}/cancel-send": { "post": { "summary": "Cancel future attempts of one outbound intent before its current native start; no recall, delivery confirmation or quota refund", "operationId": "post__api_v1_projects_project_id_email_operations_operation_id_cancel_send", "x-required-scope": "email:operations:read and email:send; owner/admin", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "action": { "enum": [ "send", "send_gmail_alias", "reply", "forward", "send_draft" ] }, "status": { "const": "cancelled" }, "cancelled": { "const": true }, "future_attempts_cancelled": { "const": true }, "delivery_confirmed": { "const": false }, "replayed": { "type": "boolean" } }, "required": [ "id", "action", "status", "cancelled", "future_attempts_cancelled", "delivery_confirmed", "replayed" ], "additionalProperties": false } }, "required": [ "operation" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expected_action": { "enum": [ "send", "send_gmail_alias", "reply", "forward", "send_draft" ] }, "confirm_cancel": { "const": true } }, "required": [ "expected_action", "confirm_cancel" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/email/operations/{operation_id}/acknowledge": { "post": { "summary": "Acknowledge an unknown outcome after native investigation; does not resend or prove delivery", "operationId": "post__api_v1_projects_project_id_email_operations_operation_id_acknowledge", "x-required-scope": "email:operations:read and the original action write scope; owner/admin", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "const": "ambiguous" }, "acknowledged": { "const": true }, "replayed": { "type": "boolean" } }, "required": [ "id", "status", "acknowledged", "replayed" ], "additionalProperties": false }, "delivery_confirmed": { "const": false } }, "required": [ "operation", "delivery_confirmed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "acknowledge_unknown_outcome": { "const": true }, "note": { "type": "string", "minLength": 1, "maxLength": 500 } }, "required": [ "acknowledge_unknown_outcome", "note" ], "additionalProperties": false } } } } } }, "/api/v1/projects/{project_id}/email/operations/{operation_id}": { "get": { "summary": "Read an operation receipt without message content", "operationId": "get__api_v1_projects_project_id_email_operations_operation_id_", "x-required-scope": "email:operations:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation": { "$ref": "#/components/schemas/EmailOperation" } }, "required": [ "operation" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/workspaces/{project_id}/members": { "get": { "summary": "List project teammates; email visible only to owner/admin", "operationId": "get__api_v1_workspaces_project_id_members", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "members": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": [ "string", "null" ] }, "role": { "enum": [ "owner", "admin", "editor", "viewer" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "user_id", "email", "role", "created_at" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "members", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/workspaces/{project_id}/members/{user_id}": { "put": { "summary": "Owner changes or removes existing teammate; last owner protected and removed member keys revoked", "operationId": "put__api_v1_workspaces_project_id_members_user_id_", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "user_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "updated": { "const": true } }, "required": [ "updated" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "enum": [ "owner", "admin", "editor", "viewer", null ] } }, "required": [ "role" ], "additionalProperties": false } } } } } }, "/api/v1/workspaces/{project_id}/invitations": { "get": { "summary": "Owner lists latest 100 invitations", "operationId": "get__api_v1_workspaces_project_id_invitations", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitations": { "type": "array", "items": { "type": "object" } } }, "required": [ "invitations" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] }, "post": { "summary": "Owner creates verified-email invitation; optional configured email is durably queued", "operationId": "post__api_v1_workspaces_project_id_invitations", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "201": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "invitation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string" }, "role": { "enum": [ "admin", "editor", "viewer" ] }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "email", "role", "expires_at" ], "additionalProperties": false }, "url": { "type": "string" }, "emailQueued": { "type": "boolean" }, "emailSent": { "const": false } }, "required": [ "invitation", "url", "emailQueued", "emailSent" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "role": { "enum": [ "admin", "editor", "viewer" ] }, "delivery": { "enum": [ "link", "email" ], "default": "link" } }, "required": [ "email", "role" ], "additionalProperties": false } } } } } }, "/api/v1/workspaces/{project_id}/invitations/{invitation_id}": { "delete": { "summary": "Owner revokes pending invitation with audit receipt", "operationId": "delete__api_v1_workspaces_project_id_invitations_invitation_id_", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "invitation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "revoked": { "type": "boolean" } }, "required": [ "revoked" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/invitations/accept": { "post": { "summary": "Accept one-time invitation using matching verified email", "operationId": "post__api_v1_invitations_accept", "x-required-scope": "console", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "workspaceId": { "type": "string", "format": "uuid" } }, "required": [ "workspaceId" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "token": { "type": "string", "minLength": 32, "maxLength": 100 } }, "required": [ "token" ], "additionalProperties": false } } } } } }, "/api/v1/session/security": { "get": { "summary": "Discover own console MFA requirement; AAL1 permitted", "operationId": "get__api_v1_session_security", "x-required-scope": "console", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "mfaRequired": { "type": "boolean" } }, "required": [ "mfaRequired" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/workspaces/{project_id}": { "delete": { "summary": "Owner requests irreversible bounded project erasure; replay is owner-bound", "operationId": "delete__api_v1_workspaces_project_id_", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "purging", "media_pending", "complete", "failed" ] }, "phase": { "type": "integer", "minimum": 1 }, "deleted_rows": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "available_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "status", "phase", "deleted_rows", "created_at", "updated_at", "available_at", "completed_at", "error_code" ], "additionalProperties": false }, "notice": { "type": "string" } }, "required": [ "request", "notice" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "confirmation" ], "additionalProperties": false } } } } } }, "/api/v1/account/project-deletions": { "get": { "summary": "List own retained project erasure receipts, including after membership removal", "operationId": "get__api_v1_account_project_deletions", "x-required-scope": "console", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "requests": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "purging", "media_pending", "complete", "failed" ] }, "phase": { "type": "integer", "minimum": 1 }, "deleted_rows": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "available_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "status", "phase", "deleted_rows", "created_at", "updated_at", "available_at", "completed_at", "error_code" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "requests", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/account/project-deletions/{request_id}": { "get": { "summary": "Read own project erasure receipt", "operationId": "get__api_v1_account_project_deletions_request_id_", "x-required-scope": "console", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "purging", "media_pending", "complete", "failed" ] }, "phase": { "type": "integer", "minimum": 1 }, "deleted_rows": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "available_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "status", "phase", "deleted_rows", "created_at", "updated_at", "available_at", "completed_at", "error_code" ], "additionalProperties": false } }, "required": [ "request" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/account/project-deletions/{request_id}/retry": { "post": { "summary": "Retry a failed erasure phase after repair; never restores erased data", "operationId": "post__api_v1_account_project_deletions_request_id_retry", "x-required-scope": "console", "parameters": [ { "name": "request_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "workspace_id": { "type": "string", "format": "uuid" }, "status": { "enum": [ "purging", "media_pending", "complete", "failed" ] }, "phase": { "type": "integer", "minimum": 1 }, "deleted_rows": { "type": "integer", "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "available_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] } }, "required": [ "id", "workspace_id", "status", "phase", "deleted_rows", "created_at", "updated_at", "available_at", "completed_at", "error_code" ], "additionalProperties": false } }, "required": [ "request" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "const": "RETRY PROJECT ERASURE" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } } }, "/api/v1/account/deletion": { "get": { "summary": "Inspect own remaining memberships and identity deletion receipt", "operationId": "get__api_v1_account_deletion", "x-required-scope": "console", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object" } }, "request": { "type": [ "object", "null" ] } }, "required": [ "projects", "request" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] }, "post": { "summary": "Request deletion of own login after leaving all projects; explicitly enabled deployments only", "operationId": "post__api_v1_account_deletion", "x-required-scope": "console", "parameters": [], "responses": { "202": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "request": { "type": "object" } }, "required": [ "request" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "const": "DELETE MY ACCOUNT" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } } }, "/api/v1/workspaces/{project_id}/leave": { "post": { "summary": "Leave own project and revoke own keys; sole owner must transfer ownership first", "operationId": "post__api_v1_workspaces_project_id_leave", "x-required-scope": "console", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "left": { "type": "boolean" } }, "required": [ "left" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "confirmation": { "const": "LEAVE PROJECT" } }, "required": [ "confirmation" ], "additionalProperties": false } } } } } }, "/api/v1/operator/access": { "get": { "summary": "Inspect own configured operator eligibility and MFA requirement", "operationId": "get__api_v1_operator_access", "x-required-scope": "console", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operator": { "const": true }, "mfaRequired": { "type": "boolean" } }, "required": [ "operator", "mfaRequired" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/operator/users": { "get": { "summary": "Operator allowlist, AAL2 and live Auth check; audited identity directory", "operationId": "get__api_v1_operator_users", "x-required-scope": "console", "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 20000, "default": 1 } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "users": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "email_verified": { "type": "boolean" }, "last_sign_in_at": { "type": [ "string", "null" ] } }, "required": [ "id", "email", "created_at", "email_verified", "last_sign_in_at" ], "additionalProperties": false } }, "page": { "type": "integer" }, "next_page": { "type": [ "integer", "null" ] } }, "required": [ "users", "page", "next_page" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/operator/projects": { "get": { "summary": "Operator AAL2 required; bounded metadata-only project directory", "operationId": "get__api_v1_operator_projects", "x-required-scope": "console", "parameters": [ { "name": "after", "in": "query", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "projects": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "entitlements": { "type": [ "object", "null" ] } }, "required": [ "id", "name", "created_at", "entitlements" ], "additionalProperties": false } }, "next_cursor": { "type": [ "string", "null" ], "format": "uuid" } }, "required": [ "projects", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/operator/audit": { "get": { "summary": "Operator AAL2 required; latest 100 operator access receipts", "operationId": "get__api_v1_operator_audit", "x-required-scope": "console", "parameters": [], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "actor_id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "request_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "actor_id", "action", "request_id", "created_at" ], "additionalProperties": false } }, "window": { "const": "most_recent_100" } }, "required": [ "events", "window" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "security": [ { "consoleSession": [] } ] } }, "/api/v1/projects/{project_id}/inbox/push/{connection_id}": { "get": { "summary": "Read current local Facebook/Instagram push authority; not delivery or history proof", "operationId": "get__api_v1_projects_project_id_inbox_push_connection_id_", "x-required-scope": "inbox:read", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "active": { "type": "boolean" }, "metadata_only": { "const": true }, "provider": { "enum": [ "instagram", "facebook" ] }, "automatic_history_recovery": { "const": false }, "read_receipt_events_enabled": { "type": "boolean" }, "read_receipt_events_active": { "type": "boolean" }, "delivery_receipt_events_enabled": { "type": "boolean" }, "delivery_receipt_events_active": { "type": "boolean" } }, "required": [ "connection_id", "customer_id", "active", "metadata_only", "provider", "automatic_history_recovery", "read_receipt_events_enabled", "read_receipt_events_active", "delivery_receipt_events_enabled", "delivery_receipt_events_active" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "502": { "description": "Invalid stored result or inconsistent project/customer/operation binding; no private data returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance mode or required service configuration unavailable" } } } }, "/api/v1/projects/{project_id}/inbox/push/{connection_id}/disable": { "post": { "summary": "Disable local message hints without unsubscribing shared native app; pending enables cancelled", "operationId": "post__api_v1_projects_project_id_inbox_push_connection_id_disable", "x-required-scope": "inbox:read and inbox:write;owner/admin/editor", "parameters": [ { "name": "project_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "connection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful request. 202 means accepted, not delivered.", "content": { "application/json": { "schema": { "type": "object", "properties": { "connection_id": { "type": "string", "format": "uuid" }, "active": { "const": false }, "native_subscription_removed": { "const": false } }, "required": [ "connection_id", "active", "native_subscription_removed" ], "additionalProperties": false } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authentication required" }, "402": { "description": "Billing activation or published usage allowance required" }, "403": { "description": "Project, role or scope denied" }, "409": { "description": "State, ownership, idempotency or configuration conflict" }, "429": { "description": "Rate limit; respect Retry-After" }, "503": { "description": "Maintenance mode or required service configuration unavailable" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "disable_local_delivery": { "const": true } }, "required": [ "customer_id", "disable_local_delivery" ], "additionalProperties": false } } } } } }, "/webhooks/instagram": { "get": { "summary": "Native Meta callback verification; operator-configured verify token required", "security": [], "parameters": [ { "name": "hub.mode", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "hub.verify_token", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "hub.challenge", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exact native challenge", "content": { "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Verification failed" }, "503": { "description": "Disabled, unconfigured or maintenance" } } }, "post": { "summary": "Raw-body Meta HMAC-SHA256 verified Instagram message hints, max2MB/1000updates; durable dedup before200; message bodies discarded", "security": [], "parameters": [ { "name": "X-Hub-Signature-256", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-fA-F0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "type": "array", "items": { "type": "object" } } ] } } } }, "responses": { "200": { "description": "Accepted or safely ignored; not message delivery", "content": { "text/plain": { "schema": { "const": "EVENT_RECEIVED" } } } }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid signature" }, "413": { "description": "Payload too large" }, "503": { "description": "Disabled, unconfigured, persistence unavailable or maintenance" } } } }, "/webhooks/facebook": { "get": { "summary": "Native Meta callback verification; operator-configured verify token required", "security": [], "parameters": [ { "name": "hub.mode", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "hub.verify_token", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "hub.challenge", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Exact native challenge", "content": { "text/plain": { "schema": { "type": "string" } } } }, "403": { "description": "Verification failed" }, "503": { "description": "Disabled, unconfigured or maintenance" } } }, "post": { "summary": "Raw-body Meta HMAC-SHA256 verified Facebook Page message hints, max2MB/1000updates; durable dedup before200; message bodies discarded", "security": [], "parameters": [ { "name": "X-Hub-Signature-256", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[a-fA-F0-9]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object" }, { "type": "array", "items": { "type": "object" } } ] } } } }, "responses": { "200": { "description": "Accepted or safely ignored; not message delivery", "content": { "text/plain": { "schema": { "const": "EVENT_RECEIVED" } } } }, "400": { "description": "Invalid payload" }, "401": { "description": "Invalid signature" }, "413": { "description": "Payload too large" }, "503": { "description": "Disabled, unconfigured, persistence unavailable or maintenance" } } } } }, "components": { "securitySchemes": { "projectKey": { "type": "http", "scheme": "bearer", "description": "Project-scoped server API key; a developer-console Supabase JWT is also accepted where documented." }, "mcpOAuth": { "type": "http", "scheme": "bearer", "description": "Opaque OAuth access token for the exact project MCP resource. Rejected by direct REST and console routes; PKCE consent and scopes apply." }, "consoleSession": { "type": "http", "scheme": "bearer", "description": "First-party Supabase session JWT with AAL2, verified email and an active verified factor. Explicit security-discovery endpoints accept AAL1. Required project role varies by operation. Project keys and third-party OAuth client tokens are rejected." }, "connectSession": { "type": "http", "scheme": "bearer", "description": "Short-lived cs_ capability extracted from a hosted connect link. Not a project API key." } }, "schemas": { "BillingResult": { "type": "object", "properties": { "pricing": { "type": "object", "properties": { "id": { "const": "connected_accounts_v1" }, "version": { "const": "2026-09-30" }, "name": { "const": "One plan" }, "currency": { "const": "usd" }, "interval": { "const": "month" }, "freeAccounts": { "const": 3 }, "additionalAccountCents": { "const": 100 }, "maxAccounts": { "const": 1000000 } }, "required": [ "id", "version", "name", "currency", "interval", "freeAccounts", "additionalAccountCents", "maxAccounts" ], "additionalProperties": false }, "configured": { "type": "boolean" }, "billing": { "type": "object", "properties": { "plan": { "const": "single" }, "linked_accounts": { "type": "integer", "minimum": 0 }, "free_accounts": { "type": "integer", "minimum": 0, "maximum": 3 }, "paid_accounts": { "type": "integer", "minimum": 0 }, "monthly_cents": { "type": "integer", "minimum": 0 }, "currency": { "const": "usd" }, "interval": { "const": "month" }, "billing_status": { "type": "string" }, "paid_accounts_enabled": { "type": "boolean" }, "has_subscription": { "type": "boolean" }, "has_customer": { "type": "boolean" }, "checked_at": { "type": [ "string", "null" ], "format": "date-time" }, "sync_error": { "type": [ "string", "null" ] }, "pending_changes": { "type": "integer", "minimum": 0 } }, "required": [ "plan", "linked_accounts", "free_accounts", "paid_accounts", "monthly_cents", "currency", "interval", "billing_status", "paid_accounts_enabled", "has_subscription", "has_customer", "checked_at", "sync_error", "pending_changes" ], "additionalProperties": false } }, "required": [ "pricing", "configured", "billing" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, "Customer": { "type": "object", "properties": { "deletion_requested_at": { "type": [ "string", "null" ], "format": "date-time" }, "id": { "type": "string", "format": "uuid" }, "external_id": { "type": "string" }, "name": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "deletion_requested_at", "id", "external_id", "name", "created_at" ], "additionalProperties": false }, "Connection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "external_id": { "type": "string" }, "name": { "type": "string" }, "status": { "enum": [ "connected", "expired", "disconnected" ] }, "scopes": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "customer_id", "provider", "external_id", "name", "status", "scopes", "metadata", "created_at" ], "additionalProperties": false }, "ExecutionRequest": { "type": "object", "properties": { "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "const": "publish" }, "input": { "type": "object", "properties": { "content": { "type": "string", "maxLength": 65000 }, "title": { "type": "string", "maxLength": 160 }, "media_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 10 }, "options": { "type": "object" } }, "required": [ "content" ], "additionalProperties": false }, "execute_at": { "type": "string", "format": "date-time" } }, "required": [ "customer_id", "connection_id", "action", "input" ], "additionalProperties": false }, "Execution": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "attempts": { "type": "integer" }, "available_at": { "type": "string", "format": "date-time" }, "external_id": { "type": [ "string", "null" ] }, "external_url": { "type": [ "string", "null" ] }, "provider_data_erased_at": { "type": [ "string", "null" ], "format": "date-time" }, "error_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "customer_id", "connection_id", "action", "status", "attempts", "available_at", "external_id", "external_url", "provider_data_erased_at", "error_code", "created_at" ], "additionalProperties": false }, "Event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "type": { "type": "string" }, "data": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "customer_id", "type", "data", "created_at" ], "additionalProperties": false }, "Endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "enabled", "created_at" ], "additionalProperties": false }, "WebhookDelivery": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "event_id": { "type": "string", "format": "uuid" }, "endpoint_id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "attempts": { "type": "integer" }, "http_status": { "type": [ "integer", "null" ] }, "error_code": { "type": [ "string", "null" ] }, "available_at": { "type": "string", "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "event_id", "endpoint_id", "status", "attempts", "http_status", "error_code", "available_at", "delivered_at", "created_at" ], "additionalProperties": false }, "CustomerPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false, "description": "Current-access scan page. Erasing or removed customers are omitted. Continue while next_cursor is present, including when data is empty; the boundary advances over scanned records." }, "ConnectionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Connection" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false, "description": "Current-access scan page. Erasing or removed customers are omitted. Continue while next_cursor is present, including when data is empty; the boundary advances over scanned records." }, "ExecutionPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false, "description": "Current-access scan page. Erasing or removed customers are omitted. Continue while next_cursor is present, including when data is empty; the boundary advances over scanned records." }, "EventPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false, "description": "Current-access scan page. Erasing or removed customers are omitted. Continue while next_cursor is present, including when data is empty; the boundary advances over scanned records." }, "EndpointPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Endpoint" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false }, "WebhookDeliveryPage": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "next_cursor" ], "additionalProperties": false, "description": "Current-access scan page. Erasing or removed customers are omitted. Continue while next_cursor is present, including when data is empty; the boundary advances over scanned records." }, "GoogleSearchShareValue": { "type": "object", "properties": { "reported_ratio": { "type": "string", "minLength": 1, "maxLength": 80 }, "interpretation": { "enum": [ "reported", "below_threshold", "above_threshold" ] }, "threshold_ratio": { "enum": [ "0.1", "0.9", null ] } }, "required": [ "reported_ratio", "interpretation", "threshold_ratio" ], "additionalProperties": false }, "GoogleSearchShareMetrics": { "type": "object", "properties": { "search_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_exact_match_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_top_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_absolute_top_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_budget_lost_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_rank_lost_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_budget_lost_top_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_rank_lost_top_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_budget_lost_absolute_top_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] }, "search_rank_lost_absolute_top_impression_share": { "anyOf": [ { "$ref": "#/components/schemas/GoogleSearchShareValue" }, { "type": "null" } ] } }, "required": [ "search_impression_share", "search_exact_match_impression_share", "search_top_impression_share", "search_absolute_top_impression_share", "search_budget_lost_impression_share", "search_rank_lost_impression_share", "search_budget_lost_top_impression_share", "search_rank_lost_top_impression_share", "search_budget_lost_absolute_top_impression_share", "search_rank_lost_absolute_top_impression_share" ], "additionalProperties": false }, "GmailSender": { "type": "object", "properties": { "from_email": { "type": "string", "format": "email", "maxLength": 254 }, "reply_to": { "type": [ "string", "null" ], "format": "email", "maxLength": 254 }, "is_primary": { "type": [ "boolean", "null" ] }, "is_default": { "type": [ "boolean", "null" ] }, "verification_status": { "enum": [ "verificationStatusUnspecified", "accepted", "pending", null ] }, "external_relay": { "type": "boolean" }, "send_eligible": { "type": "boolean" }, "metadata_only": { "const": true } }, "required": [ "from_email", "reply_to", "is_primary", "is_default", "verification_status", "external_relay", "send_eligible", "metadata_only" ], "additionalProperties": false }, "EmailOperation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "action": { "enum": [ "send", "send_gmail_alias", "create_draft", "create_reply_draft", "send_draft", "update_draft", "add_draft_attachment", "remove_draft_attachment", "begin_attachment_upload", "put_attachment_chunk", "cancel_attachment_upload", "delete_draft", "reply", "forward", "trash_message", "restore_message", "set_read_state", "modify_labels", "move_message", "create_folder", "rename_folder", "delete_folder", "move_folder", "copy_folder" ] }, "status": { "enum": [ "pending", "leased", "succeeded", "failed", "ambiguous", "cancelled" ] }, "attempts": { "type": "integer", "minimum": 0 }, "provider_receipt": { "type": [ "object", "null" ], "additionalProperties": true }, "error_code": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "customer_id", "connection_id", "action", "status", "attempts", "provider_receipt", "error_code", "created_at", "updated_at" ], "additionalProperties": false }, "EmailUpload": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "customer_id": { "type": "string", "format": "uuid" }, "connection_id": { "type": "string", "format": "uuid" }, "state": { "enum": [ "creating", "active", "completed", "cancelled", "failed", "ambiguous", "abandoned" ] }, "size_bytes": { "type": "integer", "minimum": 3000000, "maximum": 150000000 }, "next_offset": { "type": "integer", "minimum": 0, "maximum": 150000000 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "customer_id", "connection_id", "state", "size_bytes", "next_offset", "expires_at", "created_at", "updated_at" ], "additionalProperties": false } } } }