{ "openapi": "3.1.0", "info": { "title": "AFFMAX Funnel API", "version": "v1", "description": "Create and edit funnels and their node artifacts (landing pages, lead forms, path flows, listicles, offer walls) over a token-authenticated REST API. Authenticate with a team-scoped Sanctum bearer token; abilities funnels:read|write|publish gate each endpoint. Funnels are created via plan -> build (to draft) and published explicitly; their graph is edited with an atomic operation list." }, "servers": [ { "url": "https://affmax.com/api/v1" } ], "security": [ { "http": [] } ], "paths": { "/ping": { "get": { "operationId": "funnels.ping", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "team_id": { "type": "string" } }, "required": [ "ok", "team_id" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/analytics/exports": { "post": { "operationId": "analytics.exports.store", "summary": "POST /exports \u2014 submit an async export; 202 {id, status}", "tags": [ "AnalyticsExport" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitAnalyticsExportRequest" } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/analytics/exports/{reportExport}": { "get": { "operationId": "analytics.exports.show", "summary": "GET /exports/{reportExport} \u2014 poll status; signed download URL once completed", "tags": [ "AnalyticsExport" ], "parameters": [ { "name": "reportExport", "in": "path", "required": true, "description": "The report export ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`ReportExportResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ReportExportResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/analytics/reports": { "post": { "operationId": "analytics.reports.store", "tags": [ "AnalyticsReport" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunAnalyticsReportRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "mode": { "type": "string", "const": "breakdown" }, "rows": { "type": "array", "items": [] }, "total": { "type": "integer" }, "meta": { "type": "array", "items": [] } }, "required": [ "mode", "rows", "total", "meta" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "totals" }, "visits": { "type": "number" }, "clicks": { "type": "number" }, "lpClicks": { "type": "number" }, "leads": { "type": "number" }, "conversions": { "type": "number" }, "revenue": { "type": "number" }, "cost": { "type": "number" }, "profit": { "type": "number" }, "ctr": { "type": "number" }, "cr": { "type": "number" }, "cv": { "type": "number" }, "roi": { "type": "number" }, "epv": { "type": "number" }, "epc": { "type": "number" }, "cpv": { "type": "number" }, "cpc": { "type": "number" }, "cpa": { "type": "number" }, "aov": { "type": "number" }, "meta": { "type": "array", "items": [] } }, "required": [ "mode", "visits", "clicks", "lpClicks", "leads", "conversions", "revenue", "cost", "profit", "ctr", "cr", "cv", "roi", "epv", "epc", "cpv", "cpc", "cpa", "aov", "meta" ] }, { "type": "object", "properties": { "mode": { "type": "string", "const": "timeseries" }, "rows": { "type": "array", "items": [] }, "meta": { "type": "array", "items": [] } }, "required": [ "mode", "rows", "meta" ] } ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/analytics/saved-reports": { "get": { "operationId": "analytics.saved-reports.index", "tags": [ "AnalyticsSavedReport" ], "responses": { "200": { "description": "Array of `SavedReportResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SavedReportResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/destinations": { "get": { "operationId": "funnels.destinations.index", "tags": [ "Destination" ], "parameters": [ { "name": "type", "in": "query", "schema": { "$ref": "#/components/schemas/DestinationType" } } ], "responses": { "200": { "description": "Array of `DestinationResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DestinationResource" } } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/flights": { "get": { "operationId": "funnels.flights.index", "summary": "GET /flights \u2014 paginated list of the team's flights", "tags": [ "Flight" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "draft", "pending", "active", "paused", "completed", "failed" ] } }, { "name": "funnel_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "traffic_source_account_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated set of `FlightSummaryResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FlightSummaryResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/flights/{flight}": { "get": { "operationId": "funnels.flights.show", "summary": "GET /flights/{flight} \u2014 full detail incl. stats + compiled Autopilot rules", "tags": [ "Flight" ], "parameters": [ { "name": "flight", "in": "path", "required": true, "description": "The flight ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`FlightResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FlightResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/autopilot-rules": { "get": { "operationId": "funnels.autopilot-rules.index", "summary": "GET /autopilot-rules \u2014 team-wide, optionally filtered by ?flight_id", "tags": [ "FlightAutopilotRule" ], "parameters": [ { "name": "flight_id", "in": "query", "schema": { "type": [ "integer", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "workflow_id": { "type": "integer" }, "flight_id": { "type": "integer" }, "metric": [], "threshold": [], "window_hours": [], "action": [], "cooldown_minutes": [], "scope": [], "status": { "type": "string" }, "last_fired_at": [] }, "required": [ "workflow_id", "flight_id", "metric", "threshold", "window_hours", "action", "cooldown_minutes", "scope", "status", "last_fired_at" ] } } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/flights/{flight}/autopilot-rules": { "get": { "operationId": "funnels.flights.autopilot-rules.index", "summary": "GET /flights/{flight}/autopilot-rules \u2014 rules for one flight", "tags": [ "FlightAutopilotRule" ], "parameters": [ { "name": "flight", "in": "path", "required": true, "description": "The flight ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "workflow_id": { "type": "integer" }, "flight_id": { "type": "integer" }, "metric": [], "threshold": [], "window_hours": [], "action": [], "cooldown_minutes": [], "scope": [], "status": { "type": "string" }, "last_fired_at": [] }, "required": [ "workflow_id", "flight_id", "metric", "threshold", "window_hours", "action", "cooldown_minutes", "scope", "status", "last_fired_at" ] } } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "put": { "operationId": "funnels.flights.autopilot-rules.update", "summary": "PUT /flights/{flight}/autopilot-rules \u2014 compile a new Autopilot rule\nonto the flight. Capability gating mirrors the MCP tool exactly: a\nbudget-mutation action requires the flight's traffic source adapter to\nimplement {@see HasBudgetManagement}; an `ad_set` scope requires\n{@see HasAdSetManagement}", "tags": [ "FlightAutopilotRule" ], "parameters": [ { "name": "flight", "in": "path", "required": true, "description": "The flight ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertAutopilotRuleRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "workflow_id": { "type": "integer" }, "flight_id": { "type": "integer" }, "metric": [], "threshold": [], "window_hours": [], "action": [], "cooldown_minutes": [], "scope": [], "status": { "type": "string" }, "last_fired_at": [] }, "required": [ "workflow_id", "flight_id", "metric", "threshold", "window_hours", "action", "cooldown_minutes", "scope", "status", "last_fired_at" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/flights/{flight}/budget": { "put": { "operationId": "funnels.flights.budget", "tags": [ "FlightBudget" ], "parameters": [ { "name": "flight", "in": "path", "required": true, "description": "The flight ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetFlightBudgetRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "applied": { "type": "boolean" }, "flight_id": { "type": "integer" }, "mode": { "type": "string", "const": "set" }, "amount_minor": { "type": "integer" } }, "required": [ "applied", "flight_id", "mode", "amount_minor" ] }, { "type": "object", "properties": { "applied": { "type": "boolean" }, "flight_id": { "type": "integer" }, "mode": { "type": "string", "const": "adjust" }, "factor": { "type": "number" } }, "required": [ "applied", "flight_id", "mode", "factor" ] } ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/flights/{flight}/pause": { "post": { "operationId": "funnels.flights.pause", "tags": [ "FlightPause" ], "parameters": [ { "name": "flight", "in": "path", "required": true, "description": "The flight ID", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "const": "pausing" } }, "required": [ "id", "status" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/flights/{flight}/resume": { "post": { "operationId": "funnels.flights.resume", "tags": [ "FlightResume" ], "parameters": [ { "name": "flight", "in": "path", "required": true, "description": "The flight ID", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string", "const": "resuming" } }, "required": [ "id", "status" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/funnels": { "get": { "operationId": "funnels.index", "summary": "GET /funnels \u2014 list the team's funnels", "tags": [ "Funnel" ], "responses": { "200": { "description": "Array of `FunnelResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FunnelResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/funnels/{funnel}": { "get": { "operationId": "funnels.show", "summary": "GET /funnels/{funnel} \u2014 the funnel's routing graph", "tags": [ "Funnel" ], "parameters": [ { "name": "funnel", "in": "path", "required": true, "description": "The funnel ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`FunnelGraphResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FunnelGraphResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/funnel-builds": { "post": { "operationId": "funnels.builds.store", "summary": "POST /funnel-builds \u2014 create a build (Planning) + dispatch the planner.\nReturns 202; the client polls `show` until AwaitingApproval / Failed", "tags": [ "FunnelBuild" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreFunnelBuildRequest" } } } }, "responses": { "202": { "description": "`FunnelBuildResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FunnelBuildResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/funnel-builds/{build}": { "get": { "operationId": "funnels.builds.show", "summary": "GET /funnel-builds/{build} \u2014 poll the build's lifecycle state", "tags": [ "FunnelBuild" ], "parameters": [ { "name": "build", "in": "path", "required": true, "description": "The build ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`FunnelBuildResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FunnelBuildResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/funnel-builds/{build}/plan": { "put": { "operationId": "funnels.builds.plan", "summary": "PUT /funnel-builds/{build}/plan \u2014 replace the plan while AwaitingApproval.\n409 if not AwaitingApproval; 422 if the plan can't hydrate the DTO", "tags": [ "FunnelBuild" ], "parameters": [ { "name": "build", "in": "path", "required": true, "description": "The build ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateFunnelPlanRequest" } } } }, "responses": { "200": { "description": "`FunnelBuildResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FunnelBuildResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "plan can only be edited while awaiting_approval" } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/funnel-builds/{build}/build": { "post": { "operationId": "funnels.builds.build", "summary": "POST /funnel-builds/{build}/build \u2014 execute the plan into a draft funnel.\n409 if not AwaitingApproval. Returns 202; the client polls for Built", "tags": [ "FunnelBuild" ], "parameters": [ { "name": "build", "in": "path", "required": true, "description": "The build ID", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "`FunnelBuildResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FunnelBuildResource" } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "build can only run while awaiting_approval" } }, "required": [ "error" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "funnel limit reached for your plan" } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/funnels/{funnel}/operations": { "post": { "operationId": "funnels.operations.store", "summary": "POST /funnels/{funnel}/operations \u2014 apply the operation list atomically", "tags": [ "FunnelOperation" ], "parameters": [ { "name": "funnel", "in": "path", "required": true, "description": "The funnel ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyFunnelOperationsRequest" } } } }, "responses": { "200": { "description": "`FunnelGraphResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FunnelGraphResource" }, "results": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "op": { "type": "string" }, "status": { "type": "string", "const": "applied" }, "ref": { "type": "string" } }, "required": [ "op", "status", "ref" ] }, { "type": "object", "properties": { "op": { "type": "string" }, "status": { "type": "string", "const": "applied" } }, "required": [ "op", "status" ] } ] } } }, "required": [ "data", "results" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/funnels/{funnel}/publish": { "post": { "operationId": "funnels.publish", "summary": "POST /funnels/{funnel}/publish \u2014 gate, then publish the funnel", "tags": [ "FunnelPublish" ], "parameters": [ { "name": "funnel", "in": "path", "required": true, "description": "The funnel ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "published": { "type": "boolean" }, "warnings": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "string" } } ], "minItems": 3, "maxItems": 3, "additionalItems": false } }, "required": [ "published", "warnings" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "published": { "type": "boolean" }, "warnings": { "type": "array", "prefixItems": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } }, { "type": "array", "items": { "type": "string" } } ], "minItems": 3, "maxItems": 3, "additionalItems": false }, "message": { "type": "string", "const": "acknowledge_policy required to publish over policy warnings" } }, "required": [ "published", "warnings", "message" ] } } } }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "published": { "type": "boolean" }, "blocked": { "type": "array", "prefixItems": [ { "type": [ "string", "null" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false } }, "required": [ "published", "blocked" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/landing-pages": { "get": { "operationId": "funnels.landing-pages.index", "summary": "GET /landing-pages \u2014 list the team's landing pages (optional ?page_type filter)", "tags": [ "LandingPage" ], "responses": { "200": { "description": "Array of `LandingPageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LandingPageResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "funnels.landing-pages.store", "description": "Mode (a) generate (`generate:true`): resolve the offer (team-scoped 404),\nrun the generator synchronously, and return the created vN variant (201).\nMode (b) manual: create the page from exact content, baking the design-token\nblock into html_content (mirrors CreateLandingPage / EditLandingPage) (201).", "summary": "POST /landing-pages \u2014 create a raw-HTML page", "tags": [ "LandingPage" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreLandingPageRequest" } } } }, "responses": { "201": { "description": "`LandingPageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LandingPageResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/landing-pages/{landingPage}": { "get": { "operationId": "funnels.landing-pages.show", "summary": "GET /landing-pages/{landingPage} \u2014 one page (team-scoped 404)", "tags": [ "LandingPage" ], "parameters": [ { "name": "landingPage", "in": "path", "required": true, "description": "The landing page ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`LandingPageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LandingPageResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "patch": { "operationId": "funnels.landing-pages.update", "description": "Item-driven pages own html_content via the item machinery, so editing their\nHTML/css/title here would be clobbered: they accept ONLY\n{additional_offer_ids}, which re-runs the materializer over the new offer set\n(offer-slot routing stays graph-owned). Any other field on an item-driven\npage \u2014 or additional_offer_ids on a raw-HTML page \u2014 is a 422. Raw-HTML pages\nget the design-token block re-baked in (mirror EditLandingPage::save).", "summary": "PATCH /landing-pages/{landingPage} \u2014 manual raw-HTML edit, OR (for\nitem-driven pages) re-materialize the curated offer set", "tags": [ "LandingPage" ], "parameters": [ { "name": "landingPage", "in": "path", "required": true, "description": "The landing page ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLandingPageRequest" } } } }, "responses": { "200": { "description": "`LandingPageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LandingPageResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/landing-pages/{landingPage}/ai-edit": { "post": { "operationId": "funnels.landing-pages.ai-edit", "description": "Rejects item-driven pages (422 \u2014 use the item endpoints). Runs the\nstructured editor synchronously and persists its html/css/design, returning\nthe refreshed resource + the editor's explanation.", "summary": "POST /landing-pages/{landingPage}/ai-edit \u2014 structured AI HTML edit", "tags": [ "LandingPage" ], "parameters": [ { "name": "landingPage", "in": "path", "required": true, "description": "The landing page ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiEditLandingPageRequest" } } } }, "responses": { "200": { "description": "`LandingPageResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LandingPageResource" }, "explanation": { "type": "string" } }, "required": [ "data", "explanation" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/lead-buyers": { "get": { "operationId": "funnels.lead-buyers.index", "summary": "GET /lead-buyers \u2014 paginated list of the team's lead buyers", "tags": [ "LeadBuyer" ], "parameters": [ { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated set of `LeadBuyerSummaryResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadBuyerSummaryResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "funnels.lead-buyers.store", "summary": "POST /lead-buyers \u2014 create a lead buyer (201)", "tags": [ "LeadBuyer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreLeadBuyerRequest" } } } }, "responses": { "201": { "description": "`LeadBuyerResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadBuyerResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/lead-buyers/{leadBuyer}": { "get": { "operationId": "funnels.lead-buyers.show", "summary": "GET /lead-buyers/{leadBuyer} \u2014 full detail plus posting endpoints", "tags": [ "LeadBuyer" ], "parameters": [ { "name": "leadBuyer", "in": "path", "required": true, "description": "The lead buyer ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`LeadBuyerResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadBuyerResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/lead-buyers/{leadBuyer}/endpoints": { "post": { "operationId": "funnels.lead-buyers.endpoints.store", "summary": "POST /lead-buyers/{leadBuyer}/endpoints \u2014 create a posting endpoint\n(Destination + LeadBuyerEndpoint) atomically (201). The returned\n`destination_id` is what a funnel's `lead` edge routes to", "tags": [ "LeadBuyerEndpoint" ], "parameters": [ { "name": "leadBuyer", "in": "path", "required": true, "description": "The lead buyer ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreLeadBuyerEndpointRequest" } } } }, "responses": { "201": { "description": "`LeadBuyerEndpointResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadBuyerEndpointResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/lead-buyer-endpoints/{endpoint}": { "patch": { "operationId": "funnels.lead-buyer-endpoints.update", "summary": "PATCH /lead-buyer-endpoints/{endpoint} \u2014 edit an existing posting\nendpoint. `lead_buyer_id` retargets it to a different lead buyer\n(team-scoped; a foreign id 404s); `name` renames the wired Destination.\nNever changes the endpoint's team or which Destination row it is wired\nto", "tags": [ "LeadBuyerEndpoint" ], "parameters": [ { "name": "endpoint", "in": "path", "required": true, "description": "The endpoint ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadBuyerEndpointRequest" } } } }, "responses": { "200": { "description": "`LeadBuyerEndpointResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadBuyerEndpointResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/lead-forms": { "get": { "operationId": "funnels.lead-forms.index", "summary": "GET /lead-forms \u2014 list the team's lead forms", "tags": [ "LeadForm" ], "responses": { "200": { "description": "Array of `LeadFormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadFormResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "funnels.lead-forms.store", "description": "Mode (a) generate: AIService::generateFormConfig($vertical, $instructions)\n\u2192 FormConfigBuilderService::fromAiResult (forces the single default\n'submitted' outcome) (201). Mode (b) manual: LeadFormService::createManual\n(FormConfig::create + the default 'submitted' outcome) (201).", "summary": "POST /lead-forms \u2014 create a lead form", "tags": [ "LeadForm" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreLeadFormRequest" } } } }, "responses": { "201": { "description": "`LeadFormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadFormResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/lead-forms/{form}": { "get": { "operationId": "funnels.lead-forms.show", "summary": "GET /lead-forms/{form} \u2014 one form with its ordered outcomes (team-scoped 404)", "tags": [ "LeadForm" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`LeadFormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadFormResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "patch": { "operationId": "funnels.lead-forms.update", "summary": "PATCH /lead-forms/{form} \u2014 partial edit of the form surface; bumps version", "tags": [ "LeadForm" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadFormRequest" } } } }, "responses": { "200": { "description": "`LeadFormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadFormResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/lead-forms/{form}/ai-edit": { "post": { "operationId": "funnels.lead-forms.ai-edit", "description": "Runs FormAiEditor::apply (one LLM call \u2192 a routing-locked op set that\npersists field/consent/thank-you/outcome changes and cascades outcome\nrenames/deletes onto funnel lead_form nodes). Returns the refreshed resource\n+ {applied, dropped}.", "summary": "POST /lead-forms/{form}/ai-edit \u2014 structured AI edit", "tags": [ "LeadForm" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiEditLeadFormRequest" } } } }, "responses": { "200": { "description": "`LeadFormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadFormResource" }, "applied": { "type": "array", "items": { "type": "string" } }, "dropped": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Malformed operation (not an array)" ] } ] } } }, "required": [ "data", "applied", "dropped" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/lead-forms/{form}/steps": { "patch": { "operationId": "funnels.lead-forms.steps", "summary": "PATCH /lead-forms/{form}/steps \u2014 apply discrete manual step ops\n(add_step/edit_step/remove_step/reorder_steps/move_field/set_branch_rules)\nin one transaction. FormStepNormalizer owns the step invariants\n(illegal branch rules dropped, orphan fields pinned, keys deduped) \u2014 the\ncontroller does not re-implement them; it delegates straight to\n{@see LeadFormService::applyStepOps}, which also re-bakes every bound\nlead-form page", "tags": [ "LeadForm" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadFormStepsRequest" } } } }, "responses": { "200": { "description": "`LeadFormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadFormResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/lead-forms/{form}/outcomes": { "patch": { "operationId": "funnels.lead-forms.outcomes", "description": "Each op mirrors the AI editor's outcome vocabulary. Rules are validated with\nthe SAME checks FormAiEditor::sanitizeOutcomeRules applies (PII fields and\nbad in_list/domain values rejected) \u2014 but here an invalid rule is a 422, not\na silent drop, so a manual caller gets explicit feedback. All ops run in one\ntransaction, then OutcomeCascadeService::cascade re-wires funnel lead_form\nnodes for any rename/removal \u2014 all inside {@see LeadFormService::applyOutcomeOps}.", "summary": "PATCH /lead-forms/{form}/outcomes \u2014 apply discrete manual outcome ops", "tags": [ "LeadForm" ], "parameters": [ { "name": "form", "in": "path", "required": true, "description": "The form ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLeadFormOutcomesRequest" } } } }, "responses": { "200": { "description": "`LeadFormResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/LeadFormResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/landing-pages/{landingPage}/items/ai-edit": { "post": { "operationId": "funnels.landing-pages.items.ai-edit", "description": "Runs the structured listicle editor synchronously; returns the editor's\napplied-op summaries + the rebuilt item list.", "summary": "POST /landing-pages/{landingPage}/items/ai-edit \u2014 instruction-based AI edit", "tags": [ "Listicle" ], "parameters": [ { "name": "landingPage", "in": "path", "required": true, "description": "The landing page ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiEditListicleItemsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "applied": { "type": "array", "items": { "type": "string" } }, "data": { "type": "array", "items": [] } }, "required": [ "applied", "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/landing-pages/{landingPage}/items": { "patch": { "operationId": "funnels.landing-pages.items.update", "description": "Each op mirrors the AI editor's vocabulary; all are applied in one\ntransaction before a single rebuild so routing (offer_slot) and the served\nHTML never drift or get observed half-updated. Returns the rebuilt items.", "summary": "PATCH /landing-pages/{landingPage}/items \u2014 apply discrete manual ops", "tags": [ "Listicle" ], "parameters": [ { "name": "landingPage", "in": "path", "required": true, "description": "The landing page ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateListicleItemsRequest" } } } }, "responses": { "200": { "description": "Array of `ListicleItemResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ListicleItemResource" } } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/path-flows": { "get": { "operationId": "funnels.path-flows.index", "summary": "GET /path-flows \u2014 list the team's path flows", "tags": [ "PathFlow" ], "responses": { "200": { "description": "Array of `PathFlowResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PathFlowResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "funnels.path-flows.store", "description": "Mode (a) generate: PathFlowBuilderService::fromAiResult($offer,\nAIService::generatePathFlow($offer, $instruction)) (201). The builder owns\nkey/value sanitization, LandingPage provisioning, and the rebuild.\n\nMode (b) manual: PathFlowService::createManual \u2014 PathFlow::create + steps/\noutcomes (densified positions), provision the served quiz LandingPage, then\nrebuild (201).", "summary": "POST /path-flows \u2014 create a path flow", "tags": [ "PathFlow" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StorePathFlowRequest" } } } }, "responses": { "201": { "description": "`PathFlowResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PathFlowResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/path-flows/{pathFlow}": { "get": { "operationId": "funnels.path-flows.show", "summary": "GET /path-flows/{pathFlow} \u2014 one flow with steps + outcomes (team-scoped 404)", "tags": [ "PathFlow" ], "parameters": [ { "name": "pathFlow", "in": "path", "required": true, "description": "The path flow ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`PathFlowResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PathFlowResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "patch": { "operationId": "funnels.path-flows.update", "summary": "PATCH /path-flows/{pathFlow} \u2014 partial edit of the flow surface; bumps version", "tags": [ "PathFlow" ], "parameters": [ { "name": "pathFlow", "in": "path", "required": true, "description": "The path flow ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePathFlowRequest" } } } }, "responses": { "200": { "description": "`PathFlowResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PathFlowResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/path-flows/{pathFlow}/ai-edit": { "post": { "operationId": "funnels.path-flows.ai-edit", "description": "Runs PathFlowAiEditor::apply (one LLM call \u2192 a routing-locked op set that\npersists step/option/goto/rule/copy changes + rebuilds). Returns the\nrefreshed resource + {applied, dropped}.", "summary": "POST /path-flows/{pathFlow}/ai-edit \u2014 structured AI edit", "tags": [ "PathFlow" ], "parameters": [ { "name": "pathFlow", "in": "path", "required": true, "description": "The path flow ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AiEditPathFlowRequest" } } } }, "responses": { "200": { "description": "`PathFlowResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PathFlowResource" }, "applied": { "type": "array", "items": { "type": "string" } }, "dropped": { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Malformed operation (not an array)" ] } ] } } }, "required": [ "data", "applied", "dropped" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/path-flows/{pathFlow}/steps": { "patch": { "operationId": "funnels.path-flows.steps", "description": "Each op mirrors PathFlowAiEditor's op handlers (goto-merge on options\nreplacement, dangling-goto / outcome-reference guards). All ops run in one\ntransaction, then PathFlowRebuilder::rebuild re-bakes the quiz page +\nresequences positions \u2014 all inside {@see PathFlowService::applyStepOps}.", "summary": "PATCH /path-flows/{pathFlow}/steps \u2014 apply discrete manual step ops", "tags": [ "PathFlow" ], "parameters": [ { "name": "pathFlow", "in": "path", "required": true, "description": "The path flow ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePathFlowStepsRequest" } } } }, "responses": { "200": { "description": "`PathFlowResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PathFlowResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/path-flows/{pathFlow}/outcomes": { "patch": { "operationId": "funnels.path-flows.outcomes", "description": "add_outcome / edit_outcome_rules validate rules (the same vocabulary\nPathFlowAiEditor::sanitizeOutcomeRules + FunnelPublisher::flowRuleError\nenforce) \u2014 an invalid rule is a 422, not a silent drop. rename_outcome and\nremove_outcome are the moves the AI editor excludes; here they cascade onto\nevery funnel path_flow node bound to this flow (mirror PathFlowEditor::\ncascadeOutcomeChanges) \u2014 all inside {@see PathFlowService::applyOutcomeOps}.", "summary": "PATCH /path-flows/{pathFlow}/outcomes \u2014 apply discrete manual outcome ops", "tags": [ "PathFlow" ], "parameters": [ { "name": "pathFlow", "in": "path", "required": true, "description": "The path flow ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePathFlowOutcomesRequest" } } } }, "responses": { "200": { "description": "`PathFlowResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PathFlowResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/workflows": { "get": { "operationId": "funnels.workflows.index", "summary": "GET /workflows \u2014 the team's workflows, optionally filtered by ?status", "tags": [ "Workflow" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "draft", "active", "archived" ] } } ], "responses": { "200": { "description": "Array of `WorkflowResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowResource" } } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "funnels.workflows.store", "summary": "POST /workflows \u2014 create an empty DRAFT workflow (manual trigger\nunless trigger_type/event say otherwise, applied through the SAME\nset_trigger op {@see WorkflowOperationDispatcher} validates elsewhere)", "tags": [ "Workflow" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWorkflowRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "trigger_type": { "type": "string" } }, "required": [ "id", "name", "slug", "status", "trigger_type" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/workflows/{workflow}": { "get": { "operationId": "funnels.workflows.show", "summary": "GET /workflows/{workflow} \u2014 the workflow's full graph", "tags": [ "Workflow" ], "parameters": [ { "name": "workflow", "in": "path", "required": true, "description": "The workflow ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`WorkflowGraphResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowGraphResource" }, "workflow": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "description": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "status", "description" ] }, "positions": { "type": "array", "items": { "type": "object", "properties": { "x": { "type": "number" }, "y": { "type": "number" } }, "required": [ "x", "y" ] } } }, "required": [ "data", "workflow", "positions" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/workflow-approvals/{step}": { "post": { "operationId": "funnels.workflow-approvals.store", "tags": [ "WorkflowApproval" ], "parameters": [ { "name": "step", "in": "path", "required": true, "description": "The step ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DecideApprovalRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "run_id": { "type": "integer" }, "step_id": { "type": "integer" }, "approved": { "type": "boolean" }, "status": { "type": "string" } }, "required": [ "run_id", "step_id", "approved", "status" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/workflow-node-types": { "get": { "operationId": "funnels.workflow-node-types.index", "tags": [ "WorkflowNodeType" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "node_types": { "type": "array", "items": { "type": "string" } }, "trigger_events": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "description": { "type": "string" } }, "required": [ "key", "label", "description" ] } } }, "required": [ "node_types", "trigger_events" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/workflows/{workflow}/operations": { "post": { "operationId": "funnels.workflows.operations.store", "summary": "POST /workflows/{workflow}/operations \u2014 apply the operation list atomically", "tags": [ "WorkflowOperation" ], "parameters": [ { "name": "workflow", "in": "path", "required": true, "description": "The workflow ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyWorkflowOperationsRequest" } } } }, "responses": { "200": { "description": "`WorkflowGraphResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowGraphResource" }, "results": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "op": { "type": "string", "const": "add_node" }, "status": { "type": "string", "const": "applied" }, "ref": { "type": "string" } }, "required": [ "op", "status", "ref" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "remove_node" }, "status": { "type": "string", "const": "applied" } }, "required": [ "op", "status" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "set_node_config" }, "status": { "type": "string", "const": "applied" } }, "required": [ "op", "status" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "set_edge" }, "status": { "type": "string", "const": "applied" } }, "required": [ "op", "status" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "remove_edge" }, "status": { "type": "string", "const": "applied" } }, "required": [ "op", "status" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "move_node" }, "status": { "type": "string", "const": "applied" } }, "required": [ "op", "status" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "set_trigger" }, "status": { "type": "string", "const": "applied" } }, "required": [ "op", "status" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "set_input_form" }, "status": { "type": "string", "const": "applied" }, "notes": { "type": "string" } }, "required": [ "op", "status", "notes" ] } ] } } }, "required": [ "data", "results" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/workflows/{workflow}/runs": { "get": { "operationId": "funnels.workflows.runs.index", "summary": "GET /workflows/{workflow}/runs \u2014 paginated list of the workflow's runs", "tags": [ "WorkflowRun" ], "parameters": [ { "name": "workflow", "in": "path", "required": true, "description": "The workflow ID", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "Paginated set of `WorkflowRunSummaryResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRunSummaryResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "funnels.workflows.runs.store", "summary": "POST /workflows/{workflow}/runs \u2014 start a run (or a preview/test run).\nRuns are ASYNC \u2014 202 {id, status}; poll GET /workflow-runs/{run}", "tags": [ "WorkflowRun" ], "parameters": [ { "name": "workflow", "in": "path", "required": true, "description": "The workflow ID", "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunWorkflowRequest" } } } }, "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "workflow_id": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "workflow_id", "status" ] }, { "type": "object", "properties": { "id": { "type": "integer" }, "workflow_id": { "type": "integer" }, "status": { "type": "string" }, "is_preview": { "type": "boolean" }, "preview_live": { "type": "boolean" } }, "required": [ "id", "workflow_id", "status", "is_preview", "preview_live" ] } ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": [ "string", "null" ] } }, "required": [ "error" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/workflow-runs/{run}": { "get": { "operationId": "funnels.workflow-runs.show", "summary": "GET /workflow-runs/{run} \u2014 one run's status + per-step detail", "tags": [ "WorkflowRun" ], "parameters": [ { "name": "run", "in": "path", "required": true, "description": "The run ID", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "`WorkflowRunResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WorkflowRunResource" } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/workflow-runs/{run}/replay": { "post": { "operationId": "funnels.workflow-runs.replay", "tags": [ "WorkflowRunReplay" ], "parameters": [ { "name": "run", "in": "path", "required": true, "description": "The run ID", "schema": { "type": "integer" } } ], "responses": { "202": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "workflow_id": { "type": "integer" }, "status": { "type": "string" }, "replayed_from_run_id": { "type": [ "integer", "null" ] } }, "required": [ "id", "workflow_id", "status", "replayed_from_run_id" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/workflows/{workflow}/status": { "put": { "operationId": "funnels.workflows.status.update", "tags": [ "WorkflowStatus" ], "parameters": [ { "name": "workflow", "in": "path", "required": true, "description": "The workflow ID", "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetWorkflowStatusRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" } }, "required": [ "id", "status" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "const": "Cannot activate: this workflow has an event trigger but no configured event. Set one with POST .../operations {op: \"set_trigger\", trigger_type: \"event\", event: \"\"} first." } }, "required": [ "error" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "AiEditLandingPageRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/landing-pages/{landingPage}/ai-edit`\n(spec 2026-06-18-artifact-crud-api-design \u00a7A \u2014 edit AI).\n\nA single natural-language `instruction` the structured HTML editor applies\nsynchronously (`AIService::editLandingPageHtml`). Authorization is the route's\n`ability:funnels:write` middleware, so authorize() is open.", "properties": { "instruction": { "type": "string" } }, "required": [ "instruction" ], "title": "AiEditLandingPageRequest" }, "AiEditLeadFormRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/lead-forms/{form}/ai-edit` (spec\n2026-06-18-artifact-crud-api-design \u00a7C \u2014 edit AI).\n\nA single natural-language `instruction` the structured editor applies\nsynchronously (`FormAiEditor::apply`). Authorization is the route's\n`ability:funnels:write` middleware, so authorize() is open.", "properties": { "instruction": { "type": "string" } }, "required": [ "instruction" ], "title": "AiEditLeadFormRequest" }, "AiEditListicleItemsRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/landing-pages/{landingPage}/items/ai-edit`\n(spec 2026-06-18-artifact-crud-api-design \u00a7B \u2014 edit AI).\n\nA single natural-language `instruction` the structured listicle editor applies\nsynchronously (`ListicleAiEditor::apply` \u2192 AIService::editListicleArticle, one\nLLM call). The editor emits its own routing-locked op set; this request only\ncarries the instruction. Authorization is the route's `ability:funnels:write`\nmiddleware, so authorize() is open.", "properties": { "instruction": { "type": "string" } }, "required": [ "instruction" ], "title": "AiEditListicleItemsRequest" }, "AiEditPathFlowRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/path-flows/{pathFlow}/ai-edit` (spec\n2026-06-18-artifact-crud-api-design \u00a7D \u2014 edit AI).\n\nA single natural-language `instruction` the structured editor applies\nsynchronously (`PathFlowAiEditor::apply`). Authorization is the route's\n`ability:funnels:write` middleware, so authorize() is open.", "properties": { "instruction": { "type": "string" } }, "required": [ "instruction" ], "title": "AiEditPathFlowRequest" }, "ApplyFunnelOperationsRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/funnels/{funnel}/operations`.\n\nShallow shape only \u2014 each op must carry an `op` string. The detailed per-op\nshape (refs, destination_id, weight, \u2026) is enforced by\n{@see FunnelOperationDispatcher}, which fails the\nwhole atomic batch with the offending op's index (422). Authorization is the\nroute's `ability:funnels:write` middleware.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" } }, "required": [ "op" ] }, "minItems": 1 } }, "required": [ "operations" ], "title": "ApplyFunnelOperationsRequest" }, "ApplyWorkflowOperationsRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/workflows/{workflow}/operations`.\n\nShallow shape only \u2014 each op must carry an `op` string. The detailed\nper-op shape (refs, config, from/to/handle, trigger_type, \u2026) is enforced by\n{@see WorkflowOperationDispatcher}, which fails the whole atomic batch with\nthe offending op's index (422). Authorization is the route's\n`ability:workflows:write` middleware.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" } }, "required": [ "op" ] }, "minItems": 1 } }, "required": [ "operations" ], "title": "ApplyWorkflowOperationsRequest" }, "AuthType": { "type": "string", "enum": [ "api_key", "bearer", "basic", "none" ], "title": "AuthType" }, "CreateWorkflowRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/workflows` \u2014 the same fields\n{@see CreateWorkflowTool} validates. Authorization is enforced by the\nroute's `ability:workflows:write` middleware, so authorize() is open here.", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "trigger_type": { "type": "string", "enum": [ "manual", "scheduled", "event", "webhook" ] }, "event": { "type": [ "string", "null" ] }, "trigger_config": { "type": "array", "items": { "type": "string" } } }, "required": [ "name" ], "title": "CreateWorkflowRequest" }, "DecideApprovalRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/workflow-approvals/{step}` \u2014 the\nsame fields {@see DecideApprovalTool} validates. Authorization is\nenforced by the route's `ability:workflows:run` middleware, so\nauthorize() is open here.", "properties": { "approved": { "type": "boolean" }, "note": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "approved" ], "title": "DecideApprovalRequest" }, "DestinationResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "type": { "type": "string" }, "type_label": { "type": "string" }, "network": { "type": "string" }, "network_label": { "type": "string" }, "network_account": { "type": "string" } }, "required": [ "id", "name", "type", "type_label", "network", "network_label", "network_account" ], "title": "DestinationResource" }, "DestinationType": { "type": "string", "enum": [ "affiliate_offer", "rsoc_feed", "lead_buyer_endpoint", "external_redirect", "hosted_offer" ], "title": "DestinationType" }, "FlightResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "traffic_source": { "type": "string" }, "funnel_id": { "type": "integer" }, "traffic_source_account_id": { "type": [ "integer", "null" ] }, "media_buying_campaign_id": { "type": [ "string", "null" ] }, "daily_budget": { "type": [ "number", "null" ] }, "total_spend": { "type": "number" }, "total_revenue": { "type": "number" }, "roi": { "type": [ "number", "null" ] }, "launched_at": { "type": "string" }, "ad_url": { "type": [ "string", "null" ] }, "bid_amount": { "type": [ "number", "null" ] }, "total_impressions": { "type": "integer" }, "total_clicks": { "type": "integer" }, "total_conversions": { "type": "integer" }, "last_stats_synced_at": { "type": "string" }, "autopilot_rules": { "type": "array", "items": { "type": "object", "properties": { "workflow_id": { "type": "integer" }, "flight_id": { "type": "integer" }, "metric": [], "threshold": [], "window_hours": [], "action": [], "cooldown_minutes": [], "scope": [], "status": { "type": "string" }, "last_fired_at": [] }, "required": [ "workflow_id", "flight_id", "metric", "threshold", "window_hours", "action", "cooldown_minutes", "scope", "status", "last_fired_at" ] } } }, "required": [ "id", "name", "status", "traffic_source", "funnel_id", "traffic_source_account_id", "media_buying_campaign_id", "daily_budget", "total_spend", "total_revenue", "roi", "launched_at", "ad_url", "bid_amount", "total_impressions", "total_clicks", "total_conversions", "last_stats_synced_at", "autopilot_rules" ], "title": "FlightResource" }, "FlightSummaryResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "traffic_source": { "type": "string" }, "funnel_id": { "type": "integer" }, "traffic_source_account_id": { "type": [ "integer", "null" ] }, "media_buying_campaign_id": { "type": [ "string", "null" ] }, "daily_budget": { "type": [ "number", "null" ] }, "total_spend": { "type": "number" }, "total_revenue": { "type": "number" }, "roi": { "type": [ "number", "null" ] }, "launched_at": { "type": "string" } }, "required": [ "id", "name", "status", "traffic_source", "funnel_id", "traffic_source_account_id", "media_buying_campaign_id", "daily_budget", "total_spend", "total_revenue", "roi", "launched_at" ], "title": "FlightSummaryResource" }, "FunnelBuildResource": { "type": "object", "properties": { "id": { "type": "integer" }, "status": { "type": "string" }, "instruction": { "type": "string" }, "plan": { "type": [ "array", "null" ], "items": [] }, "funnel_id": { "type": [ "integer", "null" ] }, "log": { "type": [ "array", "null" ], "items": [] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "status", "instruction", "plan", "funnel_id", "log", "created_at", "updated_at" ], "title": "FunnelBuildResource" }, "FunnelGraphResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "entity_type": { "type": [ "string", "null" ] }, "entity_id": { "type": [ "integer", "null" ] }, "label": { "type": "string" } }, "required": [ "ref", "type", "entity_type", "entity_id", "label" ] } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "kind": { "type": "string", "enum": [ "outcome", "slot", "lead", "flow" ] }, "weight": { "type": "integer" }, "outcome_key": { "type": "string" }, "slot": { "type": "integer" } }, "required": [ "from", "to", "kind", "weight", "outcome_key", "slot" ] } } }, "required": [ "id", "name", "status", "nodes", "edges" ], "title": "FunnelGraphResource" }, "FunnelResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "name", "status", "slug" ], "title": "FunnelResource" }, "LandingPageResource": { "type": "object", "properties": { "id": { "type": "integer" }, "slug": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "page_type": { "type": "string" }, "status": { "type": "string" }, "compliance_status": { "type": "string" }, "generation_status": { "type": "string", "description": "Async generation lifecycle (MCP create_landing_page). null when the\npage was authored manually / never went through async generation." }, "generation_error": { "type": [ "string", "null" ] }, "generation_warnings": { "type": [ "array", "null" ], "description": "Non-fatal issues recorded during generation (e.g. a requested offer\nthat needed AI repair or a guaranteed fallback to stay covered).", "items": [] }, "html_content": { "type": [ "string", "null" ] }, "css_custom": { "type": [ "string", "null" ] }, "design": { "type": [ "array", "null" ], "items": [] }, "domain_id": { "type": [ "integer", "null" ] }, "offer_id": { "type": [ "integer", "null" ] }, "additional_offer_ids": { "type": [ "array", "null" ], "items": [] }, "variant_label": { "type": [ "string", "null" ] }, "items": { "type": "array", "description": "Item-driven pages (listicle/offer_wall) carry their ordered items \u2014\nthe routing-bearing rows the item endpoints (\u00a7B) create/edit. Raw-HTML\npages omit the key entirely.", "items": { "$ref": "#/components/schemas/ListicleItemResource" } }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "slug", "name", "title", "page_type", "status", "compliance_status", "generation_status", "generation_error", "generation_warnings", "html_content", "css_custom", "design", "domain_id", "offer_id", "additional_offer_ids", "variant_label", "updated_at" ], "title": "LandingPageResource" }, "LeadBuyerEndpointResource": { "type": "object", "properties": { "id": { "type": "integer" }, "destination_id": { "type": [ "integer", "null" ] }, "lead_buyer_id": { "type": "integer" }, "post_url": { "type": "string" }, "post_method": { "type": "string" }, "post_format": { "type": "string" }, "field_mapping": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "response_parser_config": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "strip_referrer": { "type": "boolean" }, "require_trustedform": { "type": "boolean" }, "cap_config": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] } }, "required": [ "id", "destination_id", "lead_buyer_id", "post_url", "post_method", "post_format", "field_mapping", "response_parser_config", "strip_referrer", "require_trustedform", "cap_config" ], "title": "LeadBuyerEndpointResource" }, "LeadBuyerResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "endpoint_url": { "type": "string" }, "auth_type": { "type": "string" }, "has_credentials": { "type": "boolean" }, "posting_format": { "type": "string" }, "field_mapping": { "type": "array", "items": [] }, "response_parsing": { "type": "array", "items": [] }, "post_timeout_ms": { "type": "integer" }, "daily_cap": { "type": [ "integer", "null" ] }, "monthly_cap": { "type": [ "integer", "null" ] }, "priority": { "type": "integer" }, "endpoints": { "type": "array", "items": { "$ref": "#/components/schemas/LeadBuyerEndpointResource" } } }, "required": [ "id", "name", "is_active", "endpoint_url", "auth_type", "has_credentials", "posting_format", "field_mapping", "response_parsing", "post_timeout_ms", "daily_cap", "monthly_cap", "priority" ], "title": "LeadBuyerResource" }, "LeadBuyerSummaryResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "is_active": { "type": "boolean" }, "endpoint_count": { "type": "string" }, "daily_cap": { "type": [ "integer", "null" ] }, "priority": { "type": "integer" } }, "required": [ "id", "name", "is_active", "endpoint_count", "daily_cap", "priority" ], "title": "LeadBuyerSummaryResource" }, "LeadFormResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "vertical": { "type": [ "string", "null" ] }, "landing_page_id": [], "steps": { "type": "array", "items": [] }, "fields": { "type": "array", "items": [] }, "consent_language": { "type": "string" }, "thank_you_config": { "type": [ "array", "null" ], "items": [] }, "is_active": { "type": "boolean" }, "version": { "type": "integer" }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "rules": { "type": "array", "items": [] }, "is_default": { "type": "boolean" }, "post_submit_mode": { "type": "string" }, "confirm_heading": { "type": [ "string", "null" ] }, "confirm_message": { "type": [ "string", "null" ] }, "confirm_seconds": { "type": [ "integer", "null" ] } }, "required": [ "key", "label", "rules", "is_default", "post_submit_mode", "confirm_heading", "confirm_message", "confirm_seconds" ] } } }, "required": [ "id", "name", "vertical", "landing_page_id", "steps", "fields", "consent_language", "thank_you_config", "is_active", "version", "outcomes" ], "title": "LeadFormResource" }, "ListicleItemResource": { "type": "object", "properties": { "id": { "type": "integer" }, "position": { "type": "integer" }, "type": { "type": "string" }, "offer_slot": { "type": [ "integer", "null" ] }, "destination_id": { "type": [ "integer", "null" ] }, "heading": { "type": "string" }, "body": { "type": "string" }, "cta": { "type": "null" }, "rating": { "type": [ "string", "null" ] }, "badge": { "type": [ "string", "null" ] }, "is_module": { "type": "boolean" } }, "required": [ "id", "position", "type", "offer_slot", "destination_id", "heading", "body", "cta", "rating", "badge", "is_module" ], "title": "ListicleItemResource" }, "PathFlowResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string" }, "vertical": { "type": [ "string", "null" ] }, "version": { "type": "integer" }, "landing_page_id": { "type": [ "integer", "null" ] }, "steps": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "position": { "type": "integer" }, "question": { "type": "string" }, "help_text": { "type": [ "string", "null" ] }, "answer_type": { "type": "string" }, "options": { "type": "array", "items": [] }, "is_required": { "type": "boolean" } }, "required": [ "key", "position", "question", "help_text", "answer_type", "options", "is_required" ] } }, "outcomes": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "rules": { "type": "array", "items": [] }, "is_fallback": { "type": "boolean" }, "position": { "type": "integer" } }, "required": [ "key", "label", "rules", "is_fallback", "position" ] } } }, "required": [ "id", "name", "status", "vertical", "version", "landing_page_id", "steps", "outcomes" ], "title": "PathFlowResource" }, "PostFormat": { "type": "string", "enum": [ "form", "json", "xml" ], "title": "PostFormat" }, "PostMethod": { "type": "string", "enum": [ "POST", "GET", "PUT" ], "title": "PostMethod" }, "PostSubmitMode": { "type": "string", "description": "What the visitor sees after a lead submit resolves to an outcome. Routing stays graph-owned (the outcome edge is the only routing truth) \u2014 this enum is presentation: hop instantly, flash a confirmation first, or end on the static thank-you with no hop at all.\n", "enum": [ "redirect", "confirm_then_redirect", "message_only" ], "title": "PostSubmitMode" }, "PostingFormat": { "type": "string", "enum": [ "json", "form_encoded", "xml" ], "title": "PostingFormat" }, "ReportExportResource": { "type": "object", "properties": { "id": { "type": "integer" }, "source": { "type": "string" }, "format": { "type": "string" }, "status": { "type": "string" }, "row_count": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "download_url": { "type": "string" }, "created_at": { "type": "string" } }, "required": [ "id", "source", "format", "status", "row_count", "error", "download_url", "created_at" ], "title": "ReportExportResource" }, "RunAnalyticsReportRequest": { "type": "object", "description": "POST /api/v1/analytics/reports body validation (agent-platform REST-parity\nplan \u00a73 Phase 5). Extends {@see BuildsReportQuery} rather than inventing a\nparallel schema \u2014 the SAME enum-vocabulary rules the reporting island's\nsession-authed endpoints and the `RunReportTool` MCP tool\nuse, plus the from<=to / id-backed-filter cross-field guards inherited from\n{@see BuildsReportQuery::withValidator()} (these fire for real here because\nthis class IS resolved as a container-injected FormRequest, unlike the MCP\ntool which has to re-implement the from<=to check manually against a bare\nRequest::validate() call). Only `mode` is added on top.\n\nteamId/tz are NOT read from this request's `reportingTeamId()`/\n`reportingTeamTz()` (those read a `reporting_team_id` attribute the\nreporting island's `resolve-reporting-team` middleware injects, which does\nnot run on this Sanctum-token route) \u2014 the controller builds the\n`ReportQuery` DTO explicitly from the\ntoken's own team via {@see BuildsReportQuery::reportQueryFromArray()}.", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "tz": { "type": "string", "maxLength": 64 }, "granularity": { "type": [ "string", "null" ], "enum": [ "hour", "day", "week", "month", "day_of_week", "hour_of_day" ] }, "conversionTimeMode": { "type": "string", "enum": [ "visit", "postback" ] }, "sortBy": { "type": [ "string", "null" ], "enum": [ "date", "hour", "week", "month", "funnel", "flight", "traffic_source", "offer", "destination", "lander", "page_type", "country", "region", "city", "zip", "device", "browser", "os", "browser_version", "os_version", "isp", "connection_type", "referrer_domain", "sub1", "sub2", "sub3", "sub4", "sub5", "c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8", "c9", "c10", "event_type", "outcome_key", "keyword", "campaign", "adset", "ad", "buyer", "publisher", "hosted_offer", "variation", "traffic_type", "bot_kind", "user_gesture" ] }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ] }, "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 50000 }, "includeBots": { "type": "boolean" }, "hourStart": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 }, "hourEnd": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 }, "cursor": { "type": [ "string", "null" ], "description": "Event-log only:" }, "sinceId": { "type": [ "string", "null" ], "description": "Live-feed cursor mode (D3) \u2014 walks newer than this opaque id instead of\n`cursor`'s older-walk. See LogQuery::$sinceId." }, "clickId": { "type": [ "string", "null" ] }, "buyerScope": { "type": [ "string", "null" ], "description": "\u00a74 additive per-buyer scope (designed-for, off by default; landed in P3/P5)." }, "mode": { "type": [ "string", "null" ], "enum": [ "breakdown", "timeseries", "totals" ] }, "groupBy": { "type": "array", "items": { "type": "string", "enum": [ "date", "hour", "week", "month", "funnel", "flight", "traffic_source", "offer", "destination", "lander", "page_type", "country", "region", "city", "zip", "device", "browser", "os", "browser_version", "os_version", "isp", "connection_type", "referrer_domain", "sub1", "sub2", "sub3", "sub4", "sub5", "c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8", "c9", "c10", "event_type", "outcome_key", "keyword", "campaign", "adset", "ad", "buyer", "publisher", "hosted_offer", "variation", "traffic_type", "bot_kind", "user_gesture" ] }, "maxItems": 4 }, "metrics": { "type": "array", "items": { "type": "string", "enum": [ "visits", "clicks", "lp_clicks", "leads", "conversions", "revenue", "cost", "profit", "ctr", "cr", "cv", "roi", "epv", "epc", "cpv", "cpc", "cpa", "aov" ] } }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "date", "hour", "week", "month", "funnel", "flight", "traffic_source", "offer", "destination", "lander", "page_type", "country", "region", "city", "zip", "device", "browser", "os", "browser_version", "os_version", "isp", "connection_type", "referrer_domain", "sub1", "sub2", "sub3", "sub4", "sub5", "c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8", "c9", "c10", "event_type", "outcome_key", "keyword", "campaign", "adset", "ad", "buyer", "publisher", "hosted_offer", "variation", "traffic_type", "bot_kind", "user_gesture" ] }, "op": { "type": "string", "enum": [ "eq", "in", "neq", "like" ] }, "values": { "type": "array", "items": { "type": "string" } } } } } }, "required": [ "from", "to" ], "title": "RunAnalyticsReportRequest" }, "RunWorkflowRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/workflows/{workflow}/runs` \u2014 the\nsame fields {@see RunWorkflowTool} validates. Authorization is enforced\nby the route's `ability:workflows:run` middleware, so authorize() is\nopen here.", "properties": { "context": { "type": "array", "items": { "type": "string" } }, "inputs": { "type": "array", "items": { "type": "string" } }, "preview": { "type": "boolean" }, "preview_live": { "type": "boolean" }, "sample": { "type": "array", "items": { "type": "string" } } }, "title": "RunWorkflowRequest" }, "SavedReportResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "user_id": { "type": "integer" }, "is_starred": { "type": "boolean" }, "is_shared": { "type": "boolean" }, "config": { "type": "string" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "user_id", "is_starred", "is_shared", "config", "created_at", "updated_at" ], "title": "SavedReportResource" }, "SetFlightBudgetRequest": { "type": "object", "description": "Validates the body for `PUT /api/v1/flights/{flight}/budget` \u2014 the same\nmodes/bounds {@see SetFlightBudgetTool} validates.\n`mode: set` writes an absolute daily budget (`amount_minor`, minor units,\ne.g. cents); `mode: adjust` multiplies the live platform budget by\n`factor`. Authorization is enforced by the route's `ability:flights:write`\nmiddleware, so authorize() is open here.", "properties": { "mode": { "type": "string", "enum": [ "set", "adjust" ] }, "amount_minor": { "type": "integer", "minimum": 0 }, "factor": { "type": "number", "minimum": 0 } }, "required": [ "mode" ], "title": "SetFlightBudgetRequest" }, "SetWorkflowStatusRequest": { "type": "object", "description": "Validates the body for `PUT /api/v1/workflows/{workflow}/status` \u2014 the\nsame fields {@see SetWorkflowStatusTool} validates. Authorization is\nenforced by the route's `ability:workflows:run` middleware, so\nauthorize() is open here; the event-trigger-needs-event guard lives in\nthe controller, mirroring the tool.", "properties": { "status": { "type": "string", "enum": [ "draft", "active", "archived" ] } }, "required": [ "status" ], "title": "SetWorkflowStatusRequest" }, "StoreFunnelBuildRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/funnel-builds`.\n\n`instruction` is the natural-language intent; `inputs` is an optional\nstructured hint object folded into the planner context (offer_ids, domain,\nvertical). Authorization is enforced by the route's `ability:funnels:write`\nmiddleware, so authorize() is open here.", "properties": { "instruction": { "type": "string" }, "inputs": { "type": "object", "properties": { "offer_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "domain": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] } } } }, "required": [ "instruction" ], "title": "StoreFunnelBuildRequest" }, "StoreLandingPageRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/landing-pages` (spec\n2026-06-18-artifact-crud-api-design \u00a7A \u2014 create).\n\nTwo mutually-exclusive modes share one endpoint:\n - generate (`generate:true`) \u2014 AI generation from an offer + page type, run\n synchronously through `GenerateLandingPageJob::dispatchSync` (one LLM call);\n - manual \u2014 exact content (`page_type` + `html_content`) created directly.\n\nRaw-HTML page types (prelander/advertorial/custom) support both modes.\nItem-driven types (listicle/offer_wall, spec \u00a7B) are GENERATION-ONLY \u2014 the\ngenerator materializes their items via ListicleItemMaterializer, so they\nalways require an offer_id (+ optional additional_offer_ids) and never take\nmanual html_content. Authorization is the route's `ability:funnels:write`\nmiddleware, so authorize() is open.", "properties": { "generate": { "type": [ "boolean", "null" ] }, "offer_id": { "type": [ "integer", "null" ], "description": "offer_id is required to generate; optional (routing hint) when manual.\nItem-driven pages are generation-only, so offer_id is required for them." }, "page_type": { "type": "string", "enum": [ "prelander", "advertorial", "custom", "listicle", "offer_wall" ] }, "custom_instructions": { "type": [ "string", "null" ], "description": "Mode (a) generate \u2014 AI from an offer." }, "template_slug": { "type": [ "string", "null" ] }, "variant_label": { "type": [ "string", "null" ] }, "title": { "type": "string", "description": "Mode (b) manual \u2014 exact content (raw-HTML page types only)." }, "name": { "type": [ "string", "null" ], "description": "Optional internal name; defaults to the title when omitted (MCP parity)." }, "html_content": { "type": "string" }, "css_custom": { "type": [ "string", "null" ] }, "design": { "type": [ "array", "null" ], "items": { "type": "string" } }, "domain_id": { "type": [ "integer", "null" ] }, "additional_offer_ids": { "type": [ "array", "null" ], "description": "Item-driven pages curate over a set of offers (primary + slot 2..N).", "items": { "type": "integer" } } }, "required": [ "page_type", "title", "html_content" ], "title": "StoreLandingPageRequest" }, "StoreLeadBuyerEndpointRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/lead-buyers/{leadBuyer}/endpoints` \u2014\nthe same fields {@see CreateLeadBuyerEndpointTool}\nvalidates, so REST and MCP never drift. `lead_buyer_id` is NOT accepted\nhere (it comes from the route's `{leadBuyer}` binding). Authorization is\nenforced by the route's `ability:funnels:write` middleware, so\nauthorize() is open here.", "properties": { "name": { "type": "string", "maxLength": 255 }, "post_url": { "type": "string", "maxLength": 2048 }, "post_method": { "$ref": "#/components/schemas/PostMethod" }, "post_format": { "$ref": "#/components/schemas/PostFormat" }, "response_parser_config": { "type": [ "array", "null" ], "items": { "type": "string" } }, "strip_referrer": { "type": "boolean" }, "require_trustedform": { "type": "boolean" }, "cap_config": { "type": [ "array", "null" ], "items": { "type": "string" } }, "field_mapping": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "name", "post_url" ], "title": "StoreLeadBuyerEndpointRequest" }, "StoreLeadBuyerRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/lead-buyers` \u2014 the same fields\n{@see CreateLeadBuyerTool} validates, so REST and MCP\nnever drift. `auth_credentials` is accepted here and stored via the\nmodel's `encrypted:array` cast; it is NEVER echoed back in any response.\nAuthorization is enforced by the route's `ability:funnels:write`\nmiddleware, so authorize() is open here.", "properties": { "name": { "type": "string", "maxLength": 255 }, "is_active": { "type": "boolean" }, "endpoint_url": { "type": [ "string", "null" ], "maxLength": 2048 }, "auth_type": { "$ref": "#/components/schemas/AuthType" }, "auth_credentials": { "type": [ "array", "null" ], "items": { "type": "string" } }, "posting_format": { "$ref": "#/components/schemas/PostingFormat" }, "response_parsing": { "type": [ "array", "null" ], "items": { "type": "string" } }, "post_timeout_ms": { "type": [ "integer", "null" ], "minimum": 500, "maximum": 60000 }, "daily_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "priority": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "field_mapping": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "name" ], "title": "StoreLeadBuyerRequest" }, "StoreLeadFormRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/lead-forms` (spec\n2026-06-18-artifact-crud-api-design \u00a7C \u2014 create).\n\nTwo mutually-exclusive modes share one endpoint:\n - generate (`generate:true`) \u2014 AI generation for a `vertical`, run\n synchronously through AIService::generateFormConfig (one LLM call) +\n FormConfigBuilderService::fromAiResult;\n - manual \u2014 exact content (`name` + optional fields/consent/thank-you),\n seeded with the catch-all default 'submitted' outcome.\n\nAuthorization is the route's `ability:funnels:write` middleware, so\nauthorize() is open.", "properties": { "generate": { "type": [ "boolean", "null" ] }, "vertical": { "type": [ "string", "null" ], "description": "Mode (a) generate \u2014 AI for a vertical." }, "instructions": { "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Mode (b) manual \u2014 exact content (name required; rest optional)." }, "fields": { "type": [ "array", "null" ], "items": { "type": "string" } }, "consent_language": { "type": [ "string", "null" ] }, "thank_you_config": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "name" ], "title": "StoreLeadFormRequest" }, "StorePathFlowRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/path-flows` (spec\n2026-06-18-artifact-crud-api-design \u00a7D \u2014 create).\n\nTwo mutually-exclusive modes share one endpoint:\n - generate (`generate:true`) \u2014 AI generation for an `offer_id`, run\n synchronously through AIService::generatePathFlow (one LLM call) +\n PathFlowBuilderService::fromAiResult (which provisions the served quiz\n LandingPage + rebuilds);\n - manual \u2014 exact content (`name` + optional vertical/steps/outcomes), which\n provisions the LandingPage + rebuilds too.\n\nAuthorization is the route's `ability:funnels:write` middleware, so\nauthorize() is open.", "properties": { "generate": { "type": [ "boolean", "null" ] }, "offer_id": { "type": [ "integer", "null" ], "description": "Mode (a) generate \u2014 AI for an offer." }, "instruction": { "type": [ "string", "null" ] }, "name": { "type": "string", "description": "Mode (b) manual \u2014 exact content (name required; rest optional)." }, "vertical": { "type": [ "string", "null" ] }, "steps": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "help_text": { "type": [ "string", "null" ] }, "answer_type": { "type": [ "string", "null" ], "enum": [ "single_choice", "zip_input" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_required": { "type": [ "boolean", "null" ] } } } }, "outcomes": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "rules": { "type": [ "array", "null" ], "items": { "type": "string" } }, "is_fallback": { "type": [ "boolean", "null" ] } } } } }, "required": [ "name" ], "title": "StorePathFlowRequest" }, "SubmitAnalyticsExportRequest": { "type": "object", "description": "POST /api/v1/analytics/exports body validation (agent-platform REST-parity\nplan \u00a73 Phase 5), mirroring the `SubmitExportTool` MCP tool.\nExtends {@see BuildsReportQuery} for the SAME query-body rules (incl. the\nfrom<=to / id-backed-filter cross-field guards, which fire for real here \u2014\nthis class is container-resolved, unlike the MCP tool's manual re-check),\nadding only the export-specific `format`/`columns`/`hideZeroSpend` fields.", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "tz": { "type": "string", "maxLength": 64 }, "granularity": { "type": [ "string", "null" ], "enum": [ "hour", "day", "week", "month", "day_of_week", "hour_of_day" ] }, "conversionTimeMode": { "type": "string", "enum": [ "visit", "postback" ] }, "sortBy": { "type": [ "string", "null" ], "enum": [ "date", "hour", "week", "month", "funnel", "flight", "traffic_source", "offer", "destination", "lander", "page_type", "country", "region", "city", "zip", "device", "browser", "os", "browser_version", "os_version", "isp", "connection_type", "referrer_domain", "sub1", "sub2", "sub3", "sub4", "sub5", "c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8", "c9", "c10", "event_type", "outcome_key", "keyword", "campaign", "adset", "ad", "buyer", "publisher", "hosted_offer", "variation", "traffic_type", "bot_kind", "user_gesture" ] }, "sortDir": { "type": "string", "enum": [ "asc", "desc" ] }, "page": { "type": "integer", "minimum": 1 }, "perPage": { "type": "integer", "minimum": 1, "maximum": 50000 }, "includeBots": { "type": "boolean" }, "hourStart": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 }, "hourEnd": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 23 }, "cursor": { "type": [ "string", "null" ], "description": "Event-log only:" }, "sinceId": { "type": [ "string", "null" ], "description": "Live-feed cursor mode (D3) \u2014 walks newer than this opaque id instead of\n`cursor`'s older-walk. See LogQuery::$sinceId." }, "clickId": { "type": [ "string", "null" ] }, "buyerScope": { "type": [ "string", "null" ], "description": "\u00a74 additive per-buyer scope (designed-for, off by default; landed in P3/P5)." }, "format": { "type": [ "string", "null" ], "enum": [ "csv", "xlsx" ] }, "hideZeroSpend": { "type": "boolean" }, "groupBy": { "type": "array", "items": { "type": "string", "enum": [ "date", "hour", "week", "month", "funnel", "flight", "traffic_source", "offer", "destination", "lander", "page_type", "country", "region", "city", "zip", "device", "browser", "os", "browser_version", "os_version", "isp", "connection_type", "referrer_domain", "sub1", "sub2", "sub3", "sub4", "sub5", "c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8", "c9", "c10", "event_type", "outcome_key", "keyword", "campaign", "adset", "ad", "buyer", "publisher", "hosted_offer", "variation", "traffic_type", "bot_kind", "user_gesture" ] }, "maxItems": 4 }, "metrics": { "type": "array", "items": { "type": "string", "enum": [ "visits", "clicks", "lp_clicks", "leads", "conversions", "revenue", "cost", "profit", "ctr", "cr", "cv", "roi", "epv", "epc", "cpv", "cpc", "cpa", "aov" ] } }, "eventTypes": { "type": "array", "items": { "type": "string" } }, "columns": { "type": "array", "items": { "type": "string" } }, "filters": { "type": "array", "items": { "type": "object", "properties": { "dimension": { "type": "string", "enum": [ "date", "hour", "week", "month", "funnel", "flight", "traffic_source", "offer", "destination", "lander", "page_type", "country", "region", "city", "zip", "device", "browser", "os", "browser_version", "os_version", "isp", "connection_type", "referrer_domain", "sub1", "sub2", "sub3", "sub4", "sub5", "c1", "c2", "c3", "c4", "c5", "c6", "c7", "c8", "c9", "c10", "event_type", "outcome_key", "keyword", "campaign", "adset", "ad", "buyer", "publisher", "hosted_offer", "variation", "traffic_type", "bot_kind", "user_gesture" ] }, "op": { "type": "string", "enum": [ "eq", "in", "neq", "like" ] }, "values": { "type": "array", "items": { "type": "string" } } } } } }, "required": [ "from", "to" ], "title": "SubmitAnalyticsExportRequest" }, "UpdateFunnelPlanRequest": { "type": "object", "description": "Validates the body for `PUT /api/v1/funnel-builds/{build}/plan`.\n\n`plan` must be an array; the controller additionally hydrates it through the\nFunnelBuildPlan DTO (422 on a malformed shape) before persisting. Authorization\nis enforced by the route's `ability:funnels:write` middleware.", "properties": { "plan": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "plan" ], "title": "UpdateFunnelPlanRequest" }, "UpdateLandingPageRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/landing-pages/{landingPage}` (spec\n2026-06-18-artifact-crud-api-design \u00a7A \u2014 edit manual).\n\nRaw-HTML pages: title/html/css/design/status (partial update). Item-driven\npages (listicle/offer_wall, spec \u00a7B) take only `additional_offer_ids` here \u2014\na PATCH re-runs ListicleItemMaterializer over the new offer set (offer-slot\nrouting stays graph-owned); the controller routes each page type to the right\nbranch. Every field is optional. Authorization is the route's\n`ability:funnels:write` middleware, so authorize() is open.", "properties": { "title": { "type": "string" }, "html_content": { "type": "string" }, "css_custom": { "type": [ "string", "null" ] }, "design": { "type": [ "array", "null" ], "items": { "type": "string" } }, "status": { "type": "string" }, "additional_offer_ids": { "type": "array", "description": "Item-driven re-materialize (\u00a7B): replace the curated offer set.", "items": { "type": "integer" } } }, "title": "UpdateLandingPageRequest" }, "UpdateLeadBuyerEndpointRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/lead-buyer-endpoints/{endpoint}` \u2014\nthe same fields {@see UpdateLeadBuyerEndpointTool}\nvalidates, so REST and MCP never drift. Unlike the MCP tool, the endpoint\nis resolved from the route's `{endpoint}` binding, not an\n`endpoint_id`/`destination_id` body param. `post_url` and `field_mapping`\nback NOT NULL columns: `sometimes` (not `nullable`) so an explicit null is\nrejected with a clean validation error instead of reaching the DB as a\nNOT NULL constraint violation. Authorization is enforced by the route's\n`ability:funnels:write` middleware, so authorize() is open here.", "properties": { "lead_buyer_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ], "maxLength": 255 }, "post_url": { "type": "string", "maxLength": 2048 }, "post_method": { "$ref": "#/components/schemas/PostMethod" }, "post_format": { "$ref": "#/components/schemas/PostFormat" }, "response_parser_config": { "type": [ "array", "null" ], "items": { "type": "string" } }, "strip_referrer": { "type": "boolean" }, "require_trustedform": { "type": "boolean" }, "cap_config": { "type": [ "array", "null" ], "items": { "type": "string" } }, "field_mapping": { "type": "array", "items": { "type": "string" } } }, "title": "UpdateLeadBuyerEndpointRequest" }, "UpdateLeadFormOutcomesRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/lead-forms/{form}/outcomes` (spec\n2026-06-18-artifact-crud-api-design \u00a7C \u2014 manual outcome ops).\n\nA list of discrete outcome operations applied in order, mirroring the AI\neditor's outcome vocabulary but supplied directly (no LLM):\n - add_outcome {key, label?, rules?, post_submit_mode?}\n - edit_outcome_rules {key, rules}\n - remove_outcome {key}\n - set_outcome_post_submit {key, mode, confirm_heading?, confirm_message?, confirm_seconds?}\n\nThe controller enforces rule validity (PII/in_list/domain) itself \u2014 the same\nchecks FormAiEditor::sanitizeOutcomeRules applies \u2014 so an invalid rule is a\n422 here rather than a silent drop. Authorization is the route's\n`ability:funnels:write` middleware, so authorize() is open.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "add_outcome", "edit_outcome_rules", "remove_outcome", "set_outcome_post_submit" ] }, "key": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "rules": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string", "enum": [ "equals", "in", "in_list" ] }, "value": { "type": "string" } } } }, "mode": { "$ref": "#/components/schemas/PostSubmitMode" }, "confirm_heading": { "type": [ "string", "null" ] }, "confirm_message": { "type": [ "string", "null" ] }, "confirm_seconds": { "type": [ "integer", "null" ] } }, "required": [ "op", "key" ] }, "minItems": 1 } }, "required": [ "operations" ], "title": "UpdateLeadFormOutcomesRequest" }, "UpdateLeadFormRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/lead-forms/{form}` (spec\n2026-06-18-artifact-crud-api-design \u00a7C \u2014 manual edit).\n\nPartial edit of the form surface (name/fields/consent/thank-you/validation/\nactive). The controller increments `version` on every successful PATCH.\nOutcome editing is a separate endpoint. Authorization is the route's\n`ability:funnels:write` middleware, so authorize() is open.", "properties": { "name": { "type": "string" }, "fields": { "type": "array", "items": { "type": "string" } }, "consent_language": { "type": [ "string", "null" ] }, "thank_you_config": { "type": "array", "items": { "type": "string" } }, "validation_rules": { "type": "array", "items": { "type": "string" } }, "is_active": { "type": "boolean" }, "page": { "type": "array", "description": "Served-page chrome + design (re-baked onto the bound lead-form LP).", "items": { "type": "string" } }, "design": { "type": "array", "items": { "type": "string" } } }, "title": "UpdateLeadFormRequest" }, "UpdateLeadFormStepsRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/lead-forms/{form}/steps` (mirrors\n{@see EditLeadFormStepsTool} so REST and MCP never drift).\n\nA list of discrete step operations applied in order, matching the\nfirst-class lead-form step vocabulary {@see FormStepOps}\nimplements:\n - add_step {key?, title?, subtitle?, position?}\n - edit_step {key, title?, subtitle?}\n - remove_step {key, reassign_to?}\n - reorder_steps {ordered_keys[]}\n - move_field {field_name, step_key}\n - set_branch_rules {step_key, rules[{field,operator(equals|in),value,goto}]}\n\nThe controller runs the batch through {@see LeadFormService::applyStepOps},\nwhich normalizes the repaired step document (FormStepNormalizer owns branch\n-rule/orphan-field invariants \u2014 this request does not re-implement them)\nand re-bakes every bound lead-form page. Authorization is enforced by the\nroute's `ability:funnels:write` middleware, so authorize() is open here.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "add_step", "edit_step", "remove_step", "reorder_steps", "move_field", "set_branch_rules" ] }, "key": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "subtitle": { "type": [ "string", "null" ] }, "position": { "type": [ "integer", "null" ] }, "reassign_to": { "type": [ "string", "null" ] }, "ordered_keys": { "type": [ "array", "null" ], "items": { "type": "string" } }, "field_name": { "type": [ "string", "null" ] }, "step_key": { "type": [ "string", "null" ] }, "rules": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string", "enum": [ "equals", "in" ] }, "value": { "type": "string" }, "goto": { "type": "string" } } } } }, "required": [ "op" ] }, "minItems": 1 } }, "required": [ "operations" ], "title": "UpdateLeadFormStepsRequest" }, "UpdateListicleItemsRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/landing-pages/{landingPage}/items` (spec\n2026-06-18-artifact-crud-api-design \u00a7B \u2014 edit manual / discrete ops).\n\nAn ordered list of `operations`, each a discrete, routing-locked item op the\ncontroller applies in one transaction before `ListicleRebuilder::rebuild`. The\nfive op shapes mirror the AI editor's vocabulary (the LLM path uses\ninstructions; precise clients use ops):\n - edit_item_copy {item_id, heading?, body?, cta?}\n - reorder_items {order:[item_id...]}\n - add_editorial_item {heading, body, position?}\n - remove_item {item_id}\n - edit_headline {headline?, subheadline?}\n\nOffer-slot / destination routing is never expressible here \u2014 it stays\ngraph-owned (layer 1 `sync_listicle_slots`). Authorization is the route's\n`ability:funnels:write` middleware, so authorize() is open.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "edit_item_copy", "reorder_items", "add_editorial_item", "remove_item", "edit_headline" ] }, "item_id": { "type": "integer", "description": "edit_item_copy / remove_item" }, "heading": { "type": [ "string", "null" ] }, "body": { "type": [ "string", "null" ] }, "cta": { "type": [ "string", "null" ] }, "order": { "type": "array", "description": "reorder_items", "items": { "type": "integer" } }, "position": { "type": "integer", "description": "add_editorial_item" }, "headline": { "type": [ "string", "null" ], "description": "edit_headline (headline shares the key used by add_editorial_item)" }, "subheadline": { "type": [ "string", "null" ] } }, "required": [ "op" ] }, "minItems": 1 } }, "required": [ "operations" ], "title": "UpdateListicleItemsRequest" }, "UpdatePathFlowOutcomesRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/path-flows/{pathFlow}/outcomes` (spec\n2026-06-18-artifact-crud-api-design \u00a7D \u2014 manual outcome ops).\n\nA list of discrete outcome operations applied in order. The path-flow AI\neditor INTENTIONALLY excludes outcome key rename + delete (routing is\nimmutable from there); the manual API restores them and cascades the change\nonto the funnel path_flow nodes via FunnelGraphWriter rename/deleteOutcomeEdges\n(mirror PathFlowEditor::cascadeOutcomeChanges):\n - add_outcome {key, label?, rules?, is_fallback?}\n - edit_outcome_rules {key, rules}\n - remove_outcome {key} \u2014 cascades edge deletion\n - rename_outcome {key, new_key} \u2014 cascades edge handle rename\n\nThe controller enforces rule validity (the same checks\nPathFlowAiEditor::sanitizeOutcomeRules applies) \u2014 an invalid rule is a 422\nhere rather than a silent drop. Authorization is the route's\n`ability:funnels:write` middleware, so authorize() is open.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "add_outcome", "edit_outcome_rules", "remove_outcome", "rename_outcome" ] }, "key": { "type": "string" }, "new_key": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] }, "is_fallback": { "type": [ "boolean", "null" ] }, "rules": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "field": { "type": "string" }, "operator": { "type": "string", "enum": [ "equals", "in", "in_list" ] }, "value": { "type": "string" } } } } }, "required": [ "op", "key" ] }, "minItems": 1 } }, "required": [ "operations" ], "title": "UpdatePathFlowOutcomesRequest" }, "UpdatePathFlowRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/path-flows/{pathFlow}` (spec\n2026-06-18-artifact-crud-api-design \u00a7D \u2014 partial edit of the flow surface).\n\nOnly name/status/config are editable here; steps + outcomes are edited via\ntheir dedicated sub-resource endpoints (so they rebuild + cascade). Every\ncall bumps the version. Authorization is the route's `ability:funnels:write`\nmiddleware, so authorize() is open.", "properties": { "name": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "ready" ] }, "config": { "type": "array", "items": { "type": "string" } } }, "title": "UpdatePathFlowRequest" }, "UpdatePathFlowStepsRequest": { "type": "object", "description": "Validates the body for `PATCH /api/v1/path-flows/{pathFlow}/steps` (spec\n2026-06-18-artifact-crud-api-design \u00a7D \u2014 manual step ops).\n\nA list of discrete step operations applied in order, mirroring the\nPathFlowAiEditor step vocabulary but supplied directly (no LLM):\n - add_step {new_step_key?, after_step_key?, question?, help_text?, answer_type?, options?}\n - edit_step {step_key, question?, help_text?, answer_type?, options?}\n - remove_step {step_key}\n - reorder_steps {ordered_step_keys[]}\n - edit_option {step_key, option_value, option_label?, option_icon?}\n - set_goto {step_key, option_value, goto_step_key?}\n\nThe controller mirrors PathFlowAiEditor's op handlers (goto-merge guard,\ndangling-goto/outcome-reference guards) then PathFlowRebuilder::rebuild.\nAuthorization is the route's `ability:funnels:write` middleware, so\nauthorize() is open.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "add_step", "edit_step", "remove_step", "reorder_steps", "edit_option", "set_goto" ] }, "step_key": { "type": [ "string", "null" ] }, "new_step_key": { "type": [ "string", "null" ] }, "after_step_key": { "type": [ "string", "null" ] }, "question": { "type": [ "string", "null" ] }, "help_text": { "type": [ "string", "null" ] }, "answer_type": { "type": [ "string", "null" ], "enum": [ "single_choice", "zip_input" ] }, "options": { "type": [ "array", "null" ], "items": { "type": "string" } }, "ordered_step_keys": { "type": [ "array", "null" ], "items": { "type": "string" } }, "option_value": { "type": [ "string", "null" ] }, "option_label": { "type": [ "string", "null" ] }, "option_icon": { "type": [ "string", "null" ] }, "goto_step_key": { "type": [ "string", "null" ] } }, "required": [ "op" ] }, "minItems": 1 } }, "required": [ "operations" ], "title": "UpdatePathFlowStepsRequest" }, "UpsertAutopilotRuleRequest": { "type": "object", "description": "Validates the body for `PUT /api/v1/flights/{flight}/autopilot-rules` \u2014\nthe same fields {@see UpsertAutopilotRuleTool}\nvalidates. Authorization is enforced by the route's `ability:flights:write`\nmiddleware, so authorize() is open here; traffic-source capability checks\n(budget/ad-set management) happen in the controller, mirroring the tool.", "properties": { "metric": { "type": "string", "enum": [ "cpa", "spend", "roas", "drought", "roi", "epc", "epv", "cr", "ctr", "cpc_effective", "cpm", "revenue", "profit", "conversion_count", "clicks", "impressions" ] }, "threshold": { "type": [ "number", "null" ] }, "window_hours": { "type": "integer", "minimum": 1 }, "action": { "type": "string", "enum": [ "pause", "resume", "set_budget", "adjust_budget", "alert" ] }, "cooldown_minutes": { "type": [ "integer", "null" ], "minimum": 1 }, "budget_amount_minor": { "type": [ "integer", "null" ], "minimum": 0 }, "budget_factor": { "type": [ "number", "null" ], "minimum": 0 }, "scope": { "type": [ "string", "null" ], "enum": [ "campaign", "ad_set" ] }, "ad_set_external_id": { "type": [ "string", "null" ] } }, "required": [ "metric", "window_hours", "action" ], "title": "UpsertAutopilotRuleRequest" }, "WorkflowGraphResource": { "type": "object", "properties": { "workflow_id": { "type": "integer" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "event": { "type": [ "string", "null" ] }, "event_label": { "type": [ "string", "null" ] } }, "required": [ "type", "event", "event_label" ] }, "input_form": { "type": "object", "additionalProperties": [] }, "nodes": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string" }, "type": { "type": "string" }, "label": { "type": "string" }, "config": { "type": "object", "additionalProperties": [] }, "output_handles": { "anyOf": [ { "type": "array", "items": [] }, { "type": "array", "prefixItems": [ { "type": "string", "const": "out" } ], "minItems": 1, "maxItems": 1, "additionalItems": false } ] } }, "required": [ "ref", "type", "label", "config", "output_handles" ] } }, "edges": { "type": "array", "items": { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "handle": { "type": "string" } }, "required": [ "from", "to", "handle" ] } } }, "required": [ "workflow_id", "trigger", "input_form", "nodes", "edges" ], "title": "WorkflowGraphResource" }, "WorkflowResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "status": { "type": "string" }, "trigger": { "type": "object", "properties": { "type": { "type": "string" }, "event": { "type": [ "string", "null" ] }, "event_label": { "type": [ "string", "null" ] } }, "required": [ "type", "event", "event_label" ] }, "nodes_count": { "type": "string" }, "runs_count": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "name", "slug", "status", "trigger", "nodes_count", "runs_count", "updated_at" ], "title": "WorkflowResource" }, "WorkflowRunResource": { "type": "object", "properties": { "id": { "type": "integer" }, "workflow_id": { "type": "integer" }, "status": { "type": "string" }, "triggered_by": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "context_keys": { "type": "array", "items": [] }, "started_at": { "type": "string" }, "finished_at": { "type": "string" }, "steps": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "node_ref": { "type": "string" }, "node_type": { "type": "string" }, "node_label": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "taken_handles": { "type": "array", "items": [] }, "output_keys": { "type": "array", "items": [] }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": "string" }, "finished_at": { "type": "string" } }, "required": [ "id", "node_ref", "node_type", "node_label", "status", "taken_handles", "output_keys", "error", "started_at", "finished_at" ] } } }, "required": [ "id", "workflow_id", "status", "triggered_by", "error", "context_keys", "started_at", "finished_at", "steps" ], "title": "WorkflowRunResource" }, "WorkflowRunSummaryResource": { "type": "object", "properties": { "id": { "type": "integer" }, "workflow_id": { "type": "integer" }, "status": { "type": "string" }, "triggered_by": { "type": [ "string", "null" ] }, "error": { "type": [ "string", "null" ] }, "started_at": { "type": "string" }, "finished_at": { "type": "string" } }, "required": [ "id", "workflow_id", "status", "triggered_by", "error", "started_at", "finished_at" ], "title": "WorkflowRunSummaryResource" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }