{ "openapi": "3.1.0", "info": { "title": "AFFMAX Network Publisher API", "version": "v1", "description": "Publisher-facing REST API for network offers, conversions, statements, reports, and request forms. Authenticate with a Sanctum bearer token whose tokenable is a network Publisher (never a team); the network:read ability gates reads and network:submit gates form submissions. Payloads are strictly payout-only for the publisher's own earnings \u2014 internal accounting, fraud or review bookkeeping, and demand-routing details are never included." }, "servers": [ { "url": "https://affmax.com/api/network/v1" } ], "security": [ { "http": [] }, { "http": [] } ], "paths": { "/ping": { "get": { "operationId": "network.ping", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "publisher_id": { "type": "integer" }, "publisher_name": { "type": "string" }, "network": { "type": "string" } }, "required": [ "ok", "publisher_id", "publisher_name", "network" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/conversions": { "get": { "operationId": "network.conversions.index", "tags": [ "PublisherConversion" ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "status", "in": "query", "description": "Held is deliberately excluded from the accepted values: it is\ninternal fraud/cap-review bookkeeping that must never be a\npublisher-filterable status (moat spec Component 1 invariant,\nmirrored in NetworkApiPayloads::conversion()'s status mapping).", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected", "reversed" ] } }, { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "offer_id": { "type": "integer" }, "click_id": { "type": [ "string", "null" ] }, "variation_key": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "payout": { "type": "string" }, "currency": { "type": "string" }, "txn_id": { "type": [ "string", "null" ] }, "occurred_at": { "type": [ "string", "null" ] }, "sub1": { "type": [ "string", "null" ] }, "sub2": { "type": [ "string", "null" ] }, "sub3": { "type": [ "string", "null" ] }, "sub4": { "type": [ "string", "null" ] }, "sub5": { "type": [ "string", "null" ] }, "sub6": { "type": [ "string", "null" ] }, "sub7": { "type": [ "string", "null" ] }, "sub8": { "type": [ "string", "null" ] }, "sub9": { "type": [ "string", "null" ] }, "sub10": { "type": [ "string", "null" ] }, "user_data": { "type": "object", "additionalProperties": { "type": "string" } } }, "required": [ "id", "offer_id", "click_id", "variation_key", "status", "payout", "currency", "txn_id", "occurred_at", "sub1", "sub2", "sub3", "sub4", "sub5", "sub6", "sub7", "sub8", "sub9", "sub10" ] } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "total_payout": { "type": "string" }, "has_more": { "type": "boolean" } }, "required": [ "page", "page_size", "total", "total_payout", "has_more" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/forms": { "get": { "operationId": "network.forms.index", "tags": [ "PublisherForm" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "documentation": { "type": [ "string", "null" ] }, "submit_label": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": [] } }, "steps": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "field_keys": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "title", "field_keys" ] } } }, "required": [ "id", "title", "description", "documentation", "submit_label", "fields", "steps" ] } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/forms/{workflow}": { "get": { "operationId": "network.forms.show", "tags": [ "PublisherForm" ], "parameters": [ { "name": "workflow", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "documentation": { "type": [ "string", "null" ] }, "submit_label": { "type": "string" }, "fields": { "type": "array", "items": { "type": "object", "additionalProperties": [] } }, "steps": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "key": { "type": "string" }, "title": { "type": "string" }, "field_keys": { "type": "array", "items": { "type": "string" } } }, "required": [ "key", "title", "field_keys" ] } } }, "required": [ "id", "title", "description", "documentation", "submit_label", "fields", "steps" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/forms/openapi.json": { "get": { "operationId": "network.forms.openapi", "tags": [ "PublisherFormOpenApi" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "openapi": { "type": "string", "const": "3.1.0" }, "info": { "type": "object", "properties": { "title": { "type": "string", "const": "AFFMAX Publisher Forms API" }, "version": { "type": "string" }, "description": { "type": "string", "const": "Generated for your token at request time: one submission operation per form currently published to you. Forms with file-upload fields are omitted (portal-only). Retries are safe when you send an Idempotency-Key header on every POST." } }, "required": [ "title", "version", "description" ] }, "servers": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "url": { "type": "string" } }, "required": [ "url" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "security": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "bearerToken": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } }, "required": [ "bearerToken" ] } ], "minItems": 1, "maxItems": 1, "additionalItems": false }, "components": { "type": "object", "properties": { "securitySchemes": { "type": "object", "properties": { "bearerToken": { "type": "object", "properties": { "type": { "type": "string", "const": "http" }, "scheme": { "type": "string", "const": "bearer" } }, "required": [ "type", "scheme" ] } }, "required": [ "bearerToken" ] } }, "required": [ "securitySchemes" ] }, "paths": { "type": "string" } }, "required": [ "openapi", "info", "servers", "security", "components", "paths" ] } } }, "headers": { "Cache-Control": { "schema": { "type": "string", "const": "private, max-age=60" } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/forms/submissions/{run}": { "get": { "operationId": "network.forms.submissions.show", "tags": [ "PublisherFormSubmission" ], "parameters": [ { "name": "run", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "submission_id": { "type": "integer" }, "state": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "inputs": { "type": "object", "additionalProperties": [] }, "submitted_at": { "type": [ "string", "null" ] }, "finished_at": { "type": [ "string", "null" ] } }, "required": [ "submission_id", "state", "message", "inputs", "submitted_at", "finished_at" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/forms/{workflow}/submissions": { "post": { "operationId": "network.forms.submissions.store", "tags": [ "PublisherFormSubmission" ], "parameters": [ { "name": "workflow", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "submission_id": { "type": "integer" }, "state": { "type": "string" }, "replayed": { "type": "boolean" }, "submitted_at": { "type": [ "string", "null" ] } }, "required": [ "submission_id", "state", "replayed", "submitted_at" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "429": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/offers": { "get": { "operationId": "network.offers.index", "tags": [ "PublisherOffer" ], "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "page_size", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] }, "geo_allowed": { "type": [ "array", "null" ], "items": { "type": "string" } }, "status": { "type": "string" }, "requires_approval": { "type": "boolean" }, "currency": { "type": "string" }, "payout": { "type": "object", "properties": { "type": { "type": "string" }, "amount": { "type": [ "string", "null" ] } }, "required": [ "type", "amount" ] }, "tracking_url": { "type": "string" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "tracking_url": { "type": "string" } }, "required": [ "key", "label", "tracking_url" ] } }, "guidelines": { "type": [ "object", "null" ], "additionalProperties": [] }, "creatives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "format": { "type": [ "string", "null" ] }, "preview_url": { "type": [ "string", "null" ] }, "download_url": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "format", "preview_url", "download_url" ] } }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "vertical", "geo_allowed", "status", "requires_approval", "currency", "payout", "tracking_url", "variations", "guidelines", "creatives", "created_at", "updated_at" ] } }, "meta": { "type": "object", "properties": { "page": { "type": "integer" }, "page_size": { "type": "integer" }, "total": { "type": "integer" }, "has_more": { "type": "boolean" } }, "required": [ "page", "page_size", "total", "has_more" ] } }, "required": [ "data", "meta" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/offers/{hostedOffer}": { "get": { "operationId": "network.offers.show", "tags": [ "PublisherOffer" ], "parameters": [ { "name": "hostedOffer", "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" }, "description": { "type": [ "string", "null" ] }, "vertical": { "type": [ "string", "null" ] }, "geo_allowed": { "type": [ "array", "null" ], "items": { "type": "string" } }, "status": { "type": "string" }, "requires_approval": { "type": "boolean" }, "currency": { "type": "string" }, "payout": { "type": "object", "properties": { "type": { "type": "string" }, "amount": { "type": [ "string", "null" ] } }, "required": [ "type", "amount" ] }, "tracking_url": { "type": "string" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "tracking_url": { "type": "string" } }, "required": [ "key", "label", "tracking_url" ] } }, "guidelines": { "type": [ "object", "null" ], "additionalProperties": [] }, "creatives": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "format": { "type": [ "string", "null" ] }, "preview_url": { "type": [ "string", "null" ] }, "download_url": { "type": [ "string", "null" ] } }, "required": [ "id", "type", "format", "preview_url", "download_url" ] } }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "description", "vertical", "geo_allowed", "status", "requires_approval", "currency", "payout", "tracking_url", "variations", "guidelines", "creatives", "created_at", "updated_at" ] } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/reports": { "get": { "operationId": "network.reports.index", "tags": [ "PublisherReport" ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "group_by", "in": "query", "schema": { "type": "string" } }, { "name": "offer_id", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "tz", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "tz": { "type": "string" } }, "required": [ "from", "to", "tz" ] }, "group_by": { "type": "string" }, "totals": { "type": "object", "properties": { "clicks": { "type": "integer" }, "conversions": { "type": "integer" }, "payout": { "type": "string" }, "cvr": { "type": [ "number", "null" ] }, "epc": { "type": [ "number", "null" ] }, "pending": { "type": "object", "properties": { "conversions": { "type": "integer" }, "payout": { "type": "string" } }, "required": [ "conversions", "payout" ] } }, "required": [ "clicks", "conversions", "payout", "cvr", "epc", "pending" ] }, "rows": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "date": { "type": "string" }, "hour": { "type": "string" }, "sub1": { "type": "string" }, "sub2": { "type": "string" }, "sub3": { "type": "string" }, "keyword": { "type": "string" }, "campaign": { "type": "string" }, "adset": { "type": "string" }, "ad": { "type": "string" }, "placement": { "type": "string" }, "site": { "type": "string" }, "clicks": { "type": [ "integer", "null" ] }, "conversions": { "type": "integer" }, "payout": { "type": "string" }, "cvr": { "type": [ "number", "null" ] }, "epc": { "type": [ "number", "null" ] } }, "required": [ "clicks", "conversions", "payout", "cvr", "epc" ] } } }, "required": [ "range", "group_by", "totals", "rows" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/statements": { "get": { "operationId": "network.statements.index", "tags": [ "PublisherStatement" ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "integer" }, "period_start": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "total_cents": { "type": "integer" }, "currency": { "type": "string" }, "finalized_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] } }, "required": [ "id", "period_start", "period_end", "status", "total_cents", "currency", "finalized_at", "paid_at" ] } }, "meta": { "type": "object", "properties": { "total": { "type": "integer" } }, "required": [ "total" ] } }, "required": [ "data", "meta" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/statements/{statement}": { "get": { "operationId": "network.statements.show", "tags": [ "PublisherStatement" ], "parameters": [ { "name": "statement", "in": "path", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "integer" }, "period_start": { "type": [ "string", "null" ] }, "period_end": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "total_cents": { "type": "integer" }, "currency": { "type": "string" }, "finalized_at": { "type": [ "string", "null" ] }, "paid_at": { "type": [ "string", "null" ] }, "lines": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "type": { "type": "string" }, "description": { "type": "string" }, "reference": { "type": "string" }, "amount": { "type": "number" } }, "required": [ "date", "type", "description", "reference", "amount" ] } } }, "required": [ "id", "period_start", "period_end", "status", "total_cents", "currency", "finalized_at", "paid_at" ] } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/stats": { "get": { "operationId": "network.stats.index", "tags": [ "PublisherStats" ], "parameters": [ { "name": "from", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "to", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "tz", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "range": { "type": "object", "properties": { "from": { "type": "string" }, "to": { "type": "string" }, "tz": { "type": "string" } }, "required": [ "from", "to", "tz" ] }, "clicks": { "type": "integer" }, "approved_conversions": { "type": "integer" }, "approved_payout_cents": { "type": "integer" }, "month_to_date_earnings_cents": { "type": "integer" } }, "required": [ "range", "clicks", "approved_conversions", "approved_payout_cents", "month_to_date_earnings_cents" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/offers/{hostedOffer}/tracking-link": { "get": { "operationId": "network.offers.tracking-link", "tags": [ "PublisherTrackingLink" ], "parameters": [ { "name": "hostedOffer", "in": "path", "required": true, "schema": { "type": "integer" } }, { "name": "variation_key", "in": "query", "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "hosted_offer_id": { "type": "integer" }, "tracking_url": { "type": [ "string", "null" ] }, "variation_key": { "type": "string" }, "variations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "tracking_url": { "type": [ "string", "null" ] } }, "required": [ "key", "label", "tracking_url" ] } } }, "required": [ "hosted_offer_id", "tracking_url" ] } }, "required": [ "data" ] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "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" ] } } } } } } }