{ "openapi": "3.1.0", "info": { "title": "AFFMAX Network Operator API", "version": "v1", "description": "AFFMAX Network Operator API \u2014 team-scoped REST surface for teams operating their own network (hosted offers, advertisers, publishers, held conversions, network reports). Authenticate with a Sanctum bearer token whose tokenable is a team User (never a Publisher); every endpoint is gated by a netops:read / netops:write / netops:money ability, the same abilities the netops MCP mount uses. Payloads may include revenue, margin, and other operator-only fields never exposed to publishers." }, "servers": [ { "url": "https://affmax.com/api/v1/network" } ], "security": [ { "http": [] }, { "http": [] } ], "paths": { "/advertisers": { "get": { "operationId": "network-operator.advertisers.index", "tags": [ "Advertiser" ], "parameters": [ { "name": "is_active", "in": "query", "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "contact_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "is_active": { "type": "boolean" }, "credit_limit_cents": { "type": [ "integer", "null" ] }, "prepaid_balance_cents": { "type": "integer" }, "credit_breaker_tripped": { "type": "boolean" }, "hosted_offers_count": { "type": "integer" }, "notes": { "type": [ "string", "null" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "contact_name", "contact_email", "is_active", "credit_limit_cents", "prepaid_balance_cents", "credit_breaker_tripped", "hosted_offers_count", "notes", "created_at" ] } } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "network-operator.advertisers.store", "summary": "Create one advertiser. Returns its id, its `postback_token` (shown\nONCE, mirroring `CreateAdvertiserTool`) and the absolute\n`/api/npb/{slug}` postback URL", "tags": [ "Advertiser" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAdvertiserRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "postback_token": { "type": "string" }, "postback_url": { "type": "string" } }, "required": [ "id", "postback_token", "postback_url" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/advertisers/{id}/handout": { "get": { "operationId": "network-operator.advertisers.handout", "tags": [ "AdvertiserHandout" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string" } }, "required": [ "markdown" ] } } } }, "500": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "Handout article not found." } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/publishers/{id}": { "get": { "operationId": "network-operator.publishers.show", "tags": [ "GetPublisher" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "postback_url": { "type": [ "string", "null" ] }, "payout_method": { "type": "string" }, "tax_doc_status": { "type": "string" }, "is_system": { "type": "boolean" }, "notes": { "type": [ "string", "null" ] }, "quality": { "type": "object", "properties": { "recent": { "type": "array", "items": { "type": "object", "properties": { "period_date": { "type": "string" }, "clicks": { "type": "integer" }, "ua_bot_clicks": { "type": "integer" }, "datacenter_clicks": { "type": "integer" }, "missing_language_clicks": { "type": "integer" }, "missing_referrer_clicks": { "type": "integer" }, "spoofed_ua_clicks": { "type": "integer" }, "legacy_protocol_clicks": { "type": "integer" }, "slow_rtt_clicks": { "type": "integer" }, "gesture_clicks": { "type": "integer" }, "quality_score": { "type": [ "number", "null" ] } }, "required": [ "period_date", "clicks", "ua_bot_clicks", "datacenter_clicks", "missing_language_clicks", "missing_referrer_clicks", "spoofed_ua_clicks", "legacy_protocol_clicks", "slow_rtt_clicks", "gesture_clicks", "quality_score" ] } }, "summary": { "type": "object", "properties": { "days": { "type": "integer", "minimum": 0 }, "total_clicks": { "type": "string" }, "average_quality_score": { "type": [ "number", "null" ] } }, "required": [ "days", "total_clicks", "average_quality_score" ] } }, "required": [ "recent", "summary" ] }, "created_at": { "type": "string" } }, "required": [ "id", "name", "company", "contact_email", "status", "postback_url", "payout_method", "tax_doc_status", "is_system", "notes", "quality", "created_at" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/guideline-generations": { "post": { "operationId": "network-operator.guideline-generations.store", "tags": [ "GuidelineGeneration" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenerateOfferGuidelinesRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object" } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/conversions/held": { "get": { "operationId": "network-operator.conversions.held", "summary": "Paginated, capped at 500 per page", "tags": [ "HeldConversion" ], "parameters": [ { "name": "publisher_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "hosted_offer_id", "in": "query", "schema": { "type": [ "integer", "null" ] } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LengthAwarePaginator" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/conversions/{id}/release": { "post": { "operationId": "network-operator.conversions.release", "summary": "POST /conversions/{id}/release \u2014 Held -> Approved", "tags": [ "HeldConversion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "released": { "type": "boolean" }, "conversion_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "released", "conversion_id", "status" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "You are not authorized to release this conversion." } }, "required": [ "message" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/conversions/{id}/reject": { "post": { "operationId": "network-operator.conversions.reject", "summary": "POST /conversions/{id}/reject \u2014 Held -> Rejected (terminal)", "tags": [ "HeldConversion" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RejectHeldConversionRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "rejected": { "type": "boolean" }, "conversion_id": { "type": "string" }, "status": { "type": "string" } }, "required": [ "rejected", "conversion_id", "status" ] } } } }, "403": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "You are not authorized to reject this conversion." } }, "required": [ "message" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/hosted-offers": { "get": { "operationId": "network-operator.hosted-offers.index", "summary": "GET /hosted-offers \u2014 paginated list of the team's hosted offers, capped at 100 per page", "tags": [ "HostedOffer" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "draft", "active", "paused", "archived" ] } }, { "name": "vertical", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "per_page", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LengthAwarePaginator" } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "post": { "operationId": "network-operator.hosted-offers.store", "summary": "POST /hosted-offers \u2014 create a hosted offer, defaulting to Draft\nstatus unless `status` is explicitly given", "tags": [ "HostedOffer" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateHostedOfferRequest" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "network_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] }, "geo_allowed": { "type": [ "array", "null" ], "items": [] }, "status": { "type": "string" }, "requires_approval": { "type": "boolean" }, "is_listed": { "type": "boolean" }, "share_user_data": { "type": "boolean" }, "auto_approve_conversions": { "type": "boolean" }, "demand_type": { "type": "string" }, "funnel_id": { "type": [ "integer", "null" ] }, "source_offer_id": { "type": [ "integer", "null" ] }, "advertiser_id": { "type": [ "integer", "null" ] }, "destination_url": { "type": [ "string", "null" ] }, "payout_type": { "type": "string" }, "payout_amount": { "type": [ "number", "null" ] }, "payout_percent": { "type": [ "number", "null" ] }, "daily_conversion_cap": { "type": [ "integer", "null" ] }, "weekly_conversion_cap": { "type": [ "integer", "null" ] }, "monthly_conversion_cap": { "type": [ "integer", "null" ] }, "daily_click_cap": { "type": [ "integer", "null" ] }, "monthly_click_cap": { "type": [ "integer", "null" ] }, "schedule_mode": { "type": "string" }, "schedule": { "type": [ "array", "null" ], "items": [] }, "guidelines": { "type": [ "array", "null" ], "items": [] }, "targeting": { "type": [ "array", "null" ], "items": [] }, "is_live": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "network_id", "name", "description", "vertical", "geo_allowed", "status", "requires_approval", "is_listed", "share_user_data", "auto_approve_conversions", "demand_type", "funnel_id", "source_offer_id", "advertiser_id", "destination_url", "payout_type", "payout_amount", "payout_percent", "daily_conversion_cap", "weekly_conversion_cap", "monthly_conversion_cap", "daily_click_cap", "monthly_click_cap", "schedule_mode", "schedule", "guidelines", "targeting", "is_live", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/hosted-offers/{id}": { "get": { "operationId": "network-operator.hosted-offers.show", "summary": "GET /hosted-offers/{id} \u2014 full operator-side detail", "tags": [ "HostedOffer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "network_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] }, "geo_allowed": { "type": [ "array", "null" ], "items": [] }, "status": { "type": "string" }, "requires_approval": { "type": "boolean" }, "is_listed": { "type": "boolean" }, "share_user_data": { "type": "boolean" }, "auto_approve_conversions": { "type": "boolean" }, "demand_type": { "type": "string" }, "funnel_id": { "type": [ "integer", "null" ] }, "source_offer_id": { "type": [ "integer", "null" ] }, "advertiser_id": { "type": [ "integer", "null" ] }, "destination_url": { "type": [ "string", "null" ] }, "payout_type": { "type": "string" }, "payout_amount": { "type": [ "number", "null" ] }, "payout_percent": { "type": [ "number", "null" ] }, "daily_conversion_cap": { "type": [ "integer", "null" ] }, "weekly_conversion_cap": { "type": [ "integer", "null" ] }, "monthly_conversion_cap": { "type": [ "integer", "null" ] }, "daily_click_cap": { "type": [ "integer", "null" ] }, "monthly_click_cap": { "type": [ "integer", "null" ] }, "schedule_mode": { "type": "string" }, "schedule": { "type": [ "array", "null" ], "items": [] }, "guidelines": { "type": [ "array", "null" ], "items": [] }, "targeting": { "type": [ "array", "null" ], "items": [] }, "is_live": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "network_id", "name", "description", "vertical", "geo_allowed", "status", "requires_approval", "is_listed", "share_user_data", "auto_approve_conversions", "demand_type", "funnel_id", "source_offer_id", "advertiser_id", "destination_url", "payout_type", "payout_amount", "payout_percent", "daily_conversion_cap", "weekly_conversion_cap", "monthly_conversion_cap", "daily_click_cap", "monthly_click_cap", "schedule_mode", "schedule", "guidelines", "targeting", "is_live", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "patch": { "operationId": "network-operator.hosted-offers.update", "summary": "PATCH /hosted-offers/{id} \u2014 partial patch, only the fields sent are\nchanged", "tags": [ "HostedOffer" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateHostedOfferRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "network_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] }, "geo_allowed": { "type": [ "array", "null" ], "items": [] }, "status": { "type": "string" }, "requires_approval": { "type": "boolean" }, "is_listed": { "type": "boolean" }, "share_user_data": { "type": "boolean" }, "auto_approve_conversions": { "type": "boolean" }, "demand_type": { "type": "string" }, "funnel_id": { "type": [ "integer", "null" ] }, "source_offer_id": { "type": [ "integer", "null" ] }, "advertiser_id": { "type": [ "integer", "null" ] }, "destination_url": { "type": [ "string", "null" ] }, "payout_type": { "type": "string" }, "payout_amount": { "type": [ "number", "null" ] }, "payout_percent": { "type": [ "number", "null" ] }, "daily_conversion_cap": { "type": [ "integer", "null" ] }, "weekly_conversion_cap": { "type": [ "integer", "null" ] }, "monthly_conversion_cap": { "type": [ "integer", "null" ] }, "daily_click_cap": { "type": [ "integer", "null" ] }, "monthly_click_cap": { "type": [ "integer", "null" ] }, "schedule_mode": { "type": "string" }, "schedule": { "type": [ "array", "null" ], "items": [] }, "guidelines": { "type": [ "array", "null" ], "items": [] }, "targeting": { "type": [ "array", "null" ], "items": [] }, "is_live": { "type": "boolean" }, "created_at": { "type": "string" }, "updated_at": { "type": "string" } }, "required": [ "id", "network_id", "name", "description", "vertical", "geo_allowed", "status", "requires_approval", "is_listed", "share_user_data", "auto_approve_conversions", "demand_type", "funnel_id", "source_offer_id", "advertiser_id", "destination_url", "payout_type", "payout_amount", "payout_percent", "daily_conversion_cap", "weekly_conversion_cap", "monthly_conversion_cap", "daily_click_cap", "monthly_click_cap", "schedule_mode", "schedule", "guidelines", "targeting", "is_live", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/hosted-offers/{id}/access/{publisherId}": { "put": { "operationId": "network-operator.hosted-offers.access", "tags": [ "HostedOfferAccess" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "publisherId", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpsertHostedOfferAccessRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "hosted_offer_id": { "type": "integer" }, "publisher_id": { "type": "integer" }, "status": { "type": "string" }, "payout_amount_override": { "type": [ "number", "null" ] }, "payout_percent_override": { "type": [ "number", "null" ] }, "daily_conversion_cap_override": { "type": [ "integer", "null" ] }, "monthly_conversion_cap_override": { "type": [ "integer", "null" ] }, "daily_click_cap_override": { "type": [ "integer", "null" ] }, "decided_at": { "type": "string" } }, "required": [ "id", "hosted_offer_id", "publisher_id", "status", "payout_amount_override", "payout_percent_override", "daily_conversion_cap_override", "monthly_conversion_cap_override", "daily_click_cap_override", "decided_at" ] } }, "required": [ "data" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/hosted-offers/{id}/availability": { "put": { "operationId": "network-operator.hosted-offers.availability", "tags": [ "HostedOfferAvailability" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetOfferAvailabilityRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "hosted_offer_id": { "type": "string" }, "previous_status": { "type": "string" }, "status": { "type": "string" } }, "required": [ "hosted_offer_id", "previous_status", "status" ] } } } }, "409": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Cannot change availability of an archived offer." } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/hosted-offers/{id}/creatives": { "post": { "operationId": "network-operator.hosted-offers.creatives", "tags": [ "HostedOfferCreatives" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AttachCreativesRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "hosted_offer_id": { "type": "integer" }, "attached": { "type": "string" } }, "required": [ "hosted_offer_id", "attached" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/publishers": { "get": { "operationId": "network-operator.publishers.index", "tags": [ "ListPublishers" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "invited", "active", "paused" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "company": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "payout_method": { "type": "string" }, "tax_doc_status": { "type": "string" }, "is_system": { "type": "boolean" }, "created_at": { "type": "string" } }, "required": [ "id", "name", "company", "contact_email", "status", "payout_method", "tax_doc_status", "is_system", "created_at" ] } } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/operations": { "post": { "operationId": "network-operator.operations.store", "tags": [ "NetworkOperation" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplyNetworkOperationsRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "op": { "type": "string", "const": "create_advertiser" }, "status": { "type": "string", "const": "applied" }, "id": { "type": "integer" }, "ref": { "type": [ "string", "null" ] }, "postback_token": { "type": "string" } }, "required": [ "op", "status", "id", "ref", "postback_token" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "create_hosted_offer" }, "status": { "type": "string", "const": "applied" }, "id": { "type": "integer" }, "ref": { "type": [ "string", "null" ] } }, "required": [ "op", "status", "id", "ref" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "update_hosted_offer" }, "status": { "type": "string", "const": "applied" }, "id": { "type": "integer" } }, "required": [ "op", "status", "id" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "set_guidelines" }, "status": { "type": "string", "const": "applied" }, "id": { "type": "integer" } }, "required": [ "op", "status", "id" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "attach_creatives" }, "status": { "type": "string", "const": "applied" }, "id": { "type": "integer" }, "attached": { "type": "integer" } }, "required": [ "op", "status", "id", "attached" ] }, { "type": "object", "properties": { "op": { "type": "string", "const": "grant_access" }, "status": { "type": "string", "const": "applied" }, "id": { "type": "integer" } }, "required": [ "op", "status", "id" ] } ] } } }, "required": [ "results" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/reports": { "post": { "operationId": "network-operator.reports.store", "tags": [ "NetworkReport" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunNetworkReportRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "dimension": { "type": "string" }, "from": { "type": "string" }, "to": { "type": "string" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "clicks": { "anyOf": [ { "type": "null" }, { "type": "string" }, { "type": "integer", "enum": [ 0 ] } ] }, "bots": { "description": "is_bot subset of clicks; real = clicks - bots (derived in the view).", "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "integer", "enum": [ 0 ] } ] }, "real": { "type": [ "object", "null" ] }, "bot_rate": { "type": [ "number", "null" ], "description": "Traffic-quality metrics (Phase 6): bot rate is click-side only\n(N/A wherever clicks is N/A); held/rejected rate over ALL\nconversion statuses in this row, not just Approved; avg fraud\nscore comes straight off the money aggregate (null = no scored\nconversions in this row, never a fabricated 0)." }, "conversions_pending": { "type": "integer" }, "conversions_approved": { "type": "integer" }, "conversions_held": { "type": "integer" }, "conversions_rejected": { "type": "integer" }, "conversions_reversed": { "type": "integer" }, "conversions_total": { "type": "string" }, "held_rate": { "type": [ "number", "null" ] }, "rejected_rate": { "type": [ "number", "null" ] }, "reversal_rate": { "type": [ "number", "null" ], "description": "Reversal % = reversed / (approved + reversed) \u2014 the affiliate\nclawback rate: of the conversions that EARNED (approved now, or\nwere approved before being clawed back), what share got taken\nback. Deliberately NOT over conversions_total like held/rejected\nrate: pending/held haven't resolved and rejected never earned,\nso folding them in would understate the money-risk signal this\nmetric exists to surface. Null when nothing has earned yet." }, "avg_fraud_score": { "type": [ "number", "null" ] }, "cvr": { "type": [ "number", "null" ] }, "epc": { "type": [ "number", "null" ] }, "epa": { "type": [ "number", "null" ], "description": "Derived money metrics (six new fields, 2026-07-22): every one\nis null on a zero/N-A denominator rather than a fabricated 0 \u2014\nsame discipline as cvr/epc above. epa/rpa are per-APPROVED-\nconversion (not per click); roi/margin_pct are ratios of\nmoney-only fields (payout/revenue/margin), so they stay\ndefined even on a clicks-N/A dimension (e.g. Advertiser);\nrpm/rpc need clicks like epc does, so they inherit epc's\nnull-when-N/A-or-zero guard." }, "rpa": { "type": [ "number", "null" ] }, "rpc": { "type": [ "number", "null" ] }, "rpm": { "type": [ "number", "null" ] }, "roi": { "type": [ "number", "null" ] }, "margin_pct": { "type": [ "number", "null" ] }, "payout": { "type": "number" }, "revenue": { "type": "number" }, "margin": { "type": "number" } }, "required": [ "key", "label", "clicks", "bots", "real", "bot_rate", "conversions_pending", "conversions_approved", "conversions_held", "conversions_rejected", "conversions_reversed", "conversions_total", "held_rate", "rejected_rate", "reversal_rate", "avg_fraud_score", "cvr", "epc", "epa", "rpa", "rpc", "rpm", "roi", "margin_pct", "payout", "revenue", "margin" ] } }, "totals": { "type": "object", "properties": { "key": { "type": "null" }, "label": { "type": "string", "const": "(none)" }, "clicks": { "type": [ "integer", "null" ] }, "bots": { "description": "is_bot subset of clicks; real = clicks - bots (derived in the view).", "anyOf": [ { "type": "null" }, { "type": "object" }, { "type": "integer", "enum": [ 0 ] } ] }, "real": { "type": [ "object", "null" ] }, "bot_rate": { "type": [ "number", "null" ], "description": "Traffic-quality metrics (Phase 6): bot rate is click-side only\n(N/A wherever clicks is N/A); held/rejected rate over ALL\nconversion statuses in this row, not just Approved; avg fraud\nscore comes straight off the money aggregate (null = no scored\nconversions in this row, never a fabricated 0)." }, "conversions_pending": { "type": "integer" }, "conversions_approved": { "type": "integer" }, "conversions_held": { "type": "integer" }, "conversions_rejected": { "type": "integer" }, "conversions_reversed": { "type": "integer" }, "conversions_total": { "type": "string" }, "held_rate": { "type": [ "number", "null" ] }, "rejected_rate": { "type": [ "number", "null" ] }, "reversal_rate": { "type": [ "number", "null" ], "description": "Reversal % = reversed / (approved + reversed) \u2014 the affiliate\nclawback rate: of the conversions that EARNED (approved now, or\nwere approved before being clawed back), what share got taken\nback. Deliberately NOT over conversions_total like held/rejected\nrate: pending/held haven't resolved and rejected never earned,\nso folding them in would understate the money-risk signal this\nmetric exists to surface. Null when nothing has earned yet." }, "avg_fraud_score": { "type": [ "number", "null" ] }, "cvr": { "type": [ "number", "null" ] }, "epc": { "type": [ "number", "null" ] }, "epa": { "type": [ "number", "null" ], "description": "Derived money metrics (six new fields, 2026-07-22): every one\nis null on a zero/N-A denominator rather than a fabricated 0 \u2014\nsame discipline as cvr/epc above. epa/rpa are per-APPROVED-\nconversion (not per click); roi/margin_pct are ratios of\nmoney-only fields (payout/revenue/margin), so they stay\ndefined even on a clicks-N/A dimension (e.g. Advertiser);\nrpm/rpc need clicks like epc does, so they inherit epc's\nnull-when-N/A-or-zero guard." }, "rpa": { "type": [ "number", "null" ] }, "rpc": { "type": [ "number", "null" ] }, "rpm": { "type": [ "number", "null" ] }, "roi": { "type": [ "number", "null" ] }, "margin_pct": { "type": [ "number", "null" ] }, "payout": { "type": "number" }, "revenue": { "type": "number" }, "margin": { "type": "number" } }, "required": [ "key", "label", "clicks", "bots", "real", "bot_rate", "conversions_pending", "conversions_approved", "conversions_held", "conversions_rejected", "conversions_reversed", "conversions_total", "held_rate", "rejected_rate", "reversal_rate", "avg_fraud_score", "cvr", "epc", "epa", "rpa", "rpc", "rpm", "roi", "margin_pct", "payout", "revenue", "margin" ] } }, "required": [ "dimension", "from", "to", "rows", "totals" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/offer-imports": { "post": { "operationId": "network-operator.offer-imports.store", "tags": [ "OfferImport" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportOfferFromUrlRequest" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": [] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "ApplyNetworkOperationsRequest": { "type": "object", "description": "Validates the body for `POST /api/v1/network/operations` (gap-matrix\nPhase 8). Shallow shape only \u2014 each op must carry an `op` string. The\ndetailed per-op shape (refs, demand config, ...) is enforced by\n{@see NetworkOperationDispatcher}, which fails the whole atomic batch with\nthe offending op's index (422 {op_index, error}). Authorization is the\nroute's `ability:netops:write` middleware.", "properties": { "operations": { "type": "array", "items": { "type": "object", "properties": { "op": { "type": "string" } }, "required": [ "op" ] }, "minItems": 1 } }, "required": [ "operations" ], "title": "ApplyNetworkOperationsRequest" }, "AttachCreativesRequest": { "type": "object", "description": "Validates `POST /api/v1/network/hosted-offers/{id}/creatives` (gap-matrix\nPhase 8), mirroring `App\\Mcp\\Tools\\Network\\AttachCreativesTool`. The\nhosted offer id comes from the route, not the body. Authorization is the\nroute's `ability:netops:write` middleware.", "properties": { "creative_ids": { "type": "array", "items": { "type": "integer" }, "minItems": 1 } }, "required": [ "creative_ids" ], "title": "AttachCreativesRequest" }, "CreateAdvertiserRequest": { "type": "object", "description": "Validates `POST /api/v1/network/advertisers` (gap-matrix Phase 8). Mirrors\n{@see CreateAdvertiserTool}'s validate() rules exactly so REST and MCP\nnever drift. Authorization is the route's `ability:netops:write` middleware.", "properties": { "name": { "type": "string" }, "contact_name": { "type": [ "string", "null" ] }, "contact_email": { "type": [ "string", "null" ], "format": "email" }, "credit_limit_cents": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "name" ], "title": "CreateAdvertiserRequest" }, "CreateHostedOfferRequest": { "type": "object", "description": "Validates `POST /api/v1/network/hosted-offers` (gap-matrix Phase 8).\nMirrors {@see CreateHostedOfferTool}'s validate() rules exactly so REST\nand MCP never drift. Authorization is the route's `ability:netops:write`\nmiddleware.", "properties": { "name": { "type": "string" }, "demand_type": { "type": "string", "enum": [ "lead_buyers", "upstream", "advertiser_postback" ] }, "template_hosted_offer_id": { "type": "integer" }, "description": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] }, "geo_allowed": { "type": "array", "items": { "type": "string" } }, "funnel_id": { "type": "integer" }, "source_offer_id": { "type": "integer" }, "advertiser_id": { "type": "integer" }, "advertiser_ref": { "type": "string" }, "destination_url": { "type": [ "string", "null" ] }, "payout_type": { "type": "string", "enum": [ "cpl", "cpa", "cpc", "revshare_percent" ] }, "payout_amount": { "type": [ "number", "null" ], "minimum": 0 }, "payout_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "event_payouts": { "type": [ "array", "null" ], "items": { "type": "string" } }, "guidelines": { "type": [ "array", "null" ], "items": { "type": "string" } }, "daily_conversion_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "weekly_conversion_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "monthly_conversion_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "daily_click_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "monthly_click_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "schedule_mode": { "type": "string", "enum": [ "off", "hard", "soft" ] }, "schedule": { "type": [ "array", "null" ], "items": { "type": "string" } }, "requires_approval": { "type": "boolean" }, "is_listed": { "type": "boolean" }, "auto_approve_conversions": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "fail_traffic_url": { "type": [ "string", "null" ], "format": "uri" } }, "required": [ "name" ], "title": "CreateHostedOfferRequest" }, "GenerateOfferGuidelinesRequest": { "type": "object", "description": "Validates `POST /api/v1/network/guideline-generations` (gap-matrix\nPhase 8). Mirrors {@see GenerateOfferGuidelinesTool}'s validate() rules\n(the tool's `write` flag is this endpoint's `apply`). Authorization is the\nroute's `ability:netops:write` middleware (plus the `throttle:api-ai` rate\nlimit \u2014 this endpoint performs an LLM spend even when not applying).", "properties": { "hosted_offer_id": { "type": "integer" }, "url": { "type": "string", "format": "uri" }, "content": { "type": "string" }, "apply": { "type": "boolean" }, "style_hosted_offer_id": { "type": [ "integer", "null" ] } }, "title": "GenerateOfferGuidelinesRequest" }, "ImportOfferFromUrlRequest": { "type": "object", "description": "Validates `POST /api/v1/network/offer-imports` (gap-matrix Phase 8).\nMirrors {@see ImportOfferFromUrlTool}'s validate() rules exactly so REST\nand MCP never drift. Authorization is the route's `ability:netops:write`\nmiddleware (plus the `throttle:api-ai` rate limit \u2014 this endpoint performs\na fetch and an LLM spend).", "properties": { "url": { "type": "string", "format": "uri" }, "create_consumer_offer": { "type": "boolean" }, "network_account_id": { "type": "integer" } }, "required": [ "url" ], "title": "ImportOfferFromUrlRequest" }, "LengthAwarePaginator": { "type": "array", "items": [], "title": "LengthAwarePaginator" }, "RejectHeldConversionRequest": { "type": "object", "description": "Validates `POST /api/v1/network/conversions/{id}/reject` (gap-matrix\nPhase 8). Mirrors {@see RejectHeldConversionTool}'s validate() rules.\nAuthorization is the route's `ability:netops:money` middleware.", "properties": { "reason": { "type": "string", "maxLength": 120 } }, "required": [ "reason" ], "title": "RejectHeldConversionRequest" }, "RunNetworkReportRequest": { "type": "object", "description": "POST /api/v1/network/reports body validation (gap-matrix Phase 7). Mirrors\n{@see NetworkReportTool}'s validate() rules exactly\nso the REST and MCP surfaces never drift.", "properties": { "from": { "type": "string", "format": "date-time" }, "to": { "type": "string", "format": "date-time" }, "dimension": { "type": [ "string", "null" ], "enum": [ "publisher", "hosted_offer", "advertiser", "sub1", "geo" ] }, "publisher_id": { "type": [ "integer", "null" ] }, "hosted_offer_id": { "type": [ "integer", "null" ] }, "advertiser_id": { "type": [ "integer", "null" ] }, "sub1": { "type": [ "string", "null" ] }, "geo": { "type": [ "string", "null" ] }, "status": { "type": [ "array", "null" ], "items": { "type": "string", "enum": [ "pending", "approved", "held", "rejected", "reversed" ] } } }, "required": [ "from", "to" ], "title": "RunNetworkReportRequest" }, "SetOfferAvailabilityRequest": { "type": "object", "description": "Validates `PUT /api/v1/network/hosted-offers/{id}/availability`\n(gap-matrix Phase 8) \u2014 a plain runtime toggle, mirroring\n`App\\Mcp\\Tools\\Network\\SetOfferAvailabilityTool`. Authorization is the\nroute's `ability:netops:write` middleware.", "properties": { "status": { "type": "string", "enum": [ "active", "paused" ] } }, "required": [ "status" ], "title": "SetOfferAvailabilityRequest" }, "UpdateHostedOfferRequest": { "type": "object", "description": "Validates `PATCH /api/v1/network/hosted-offers/{id}` (gap-matrix Phase 8).\nMirrors {@see UpdateHostedOfferTool}'s validate() rules exactly (partial\npatch \u2014 only fields present are changed) so REST and MCP never drift. The\nid comes from the route, not the body. Authorization is the route's\n`ability:netops:write` middleware.", "properties": { "name": { "type": "string" }, "demand_type": { "type": "string", "enum": [ "lead_buyers", "upstream", "advertiser_postback" ] }, "description": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] }, "geo_allowed": { "type": "array", "items": { "type": "string" } }, "funnel_id": { "type": "integer" }, "source_offer_id": { "type": "integer" }, "advertiser_id": { "type": "integer" }, "advertiser_ref": { "type": "string" }, "destination_url": { "type": [ "string", "null" ] }, "payout_type": { "type": "string", "enum": [ "cpl", "cpa", "cpc", "revshare_percent" ] }, "payout_amount": { "type": [ "number", "null" ], "minimum": 0 }, "payout_percent": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "event_payouts": { "type": [ "array", "null" ], "items": { "type": "string" } }, "guidelines": { "type": [ "array", "null" ], "items": { "type": "string" } }, "daily_conversion_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "weekly_conversion_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "monthly_conversion_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "daily_click_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "monthly_click_cap": { "type": [ "integer", "null" ], "minimum": 0 }, "schedule_mode": { "type": "string", "enum": [ "off", "hard", "soft" ] }, "schedule": { "type": [ "array", "null" ], "items": { "type": "string" } }, "requires_approval": { "type": "boolean" }, "is_listed": { "type": "boolean" }, "auto_approve_conversions": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "active", "paused", "archived" ] }, "fail_traffic_url": { "type": [ "string", "null" ], "format": "uri" } }, "title": "UpdateHostedOfferRequest" }, "UpsertHostedOfferAccessRequest": { "type": "object", "description": "Validates `PUT /api/v1/network/hosted-offers/{id}/access/{publisherId}`\n(gap-matrix Phase 8). Mirrors {@see UpsertHostedOfferAccessTool}'s\nvalidate() rules exactly so REST and MCP never drift. The hosted offer and\npublisher ids come from the route, not the body. Only the fields present\nare changed (`sometimes`) \u2014 passing an override as `null` clears it.\nAuthorization is the route's `ability:netops:write` middleware.", "properties": { "status": { "type": [ "string", "null" ], "enum": [ "approved", "rejected", "revoked" ] }, "payout_amount_override": { "type": [ "number", "null" ], "minimum": 0 }, "payout_percent_override": { "type": [ "number", "null" ], "minimum": 0, "maximum": 100 }, "daily_conversion_cap_override": { "type": [ "integer", "null" ], "minimum": 0 }, "monthly_conversion_cap_override": { "type": [ "integer", "null" ], "minimum": 0 }, "daily_click_cap_override": { "type": [ "integer", "null" ], "minimum": 0 } }, "title": "UpsertHostedOfferAccessRequest" } }, "responses": { "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" ] } } } }, "AuthenticationException": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }