{
  "openapi": "3.1.0",
  "info": {
    "title": "Adflex API V2",
    "version": "2.0.0",
    "description": "Public integration description for Adflex API V2. Always inspect the JSON status and meta.code fields because application failures can be returned with HTTP 200.",
    "license": { "name": "Proprietary" }
  },
  "servers": [
    { "url": "https://api.adflex.io/api", "description": "Production" }
  ],
  "security": [
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/v2/ads/{platform}/filters": {
      "get": {
        "summary": "List the current filter definitions for a search source",
        "description": "Free endpoint. Treat the returned filter metadata as the source of truth for accepted keys, values, defaults, and component types.",
        "operationId": "getAdFilters",
        "parameters": [
          { "$ref": "#/components/parameters/SearchPlatform" }
        ],
        "responses": {
          "200": {
            "description": "Application response envelope",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiEnvelope" } } }
          }
        }
      }
    },
    "/v2/ads/{platform}/filters/{filter}": {
      "get": {
        "summary": "Get dynamic options for one filter",
        "description": "Free endpoint. The filter definition can provide the relevant dynamic route.",
        "operationId": "getAdFilterItems",
        "parameters": [
          { "$ref": "#/components/parameters/SearchPlatform" },
          { "name": "filter", "in": "path", "required": true, "schema": { "type": "string" } },
          { "name": "search", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Application response envelope",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiEnvelope" } } }
          }
        }
      }
    },
    "/v2/ads/{platform}/search": {
      "post": {
        "summary": "Search ads on one platform or with Mega Search",
        "description": "A page returns up to 18 ads. Page 1 omits last_hit. Later pages must reuse the exact data.last_hit returned by page 1 with unchanged filters and sorting. Search requests currently cost 100 credits.",
        "operationId": "searchAds",
        "parameters": [
          { "$ref": "#/components/parameters/SearchPlatform" }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SearchRequest" },
              "examples": {
                "pageOneNewest": {
                  "value": {
                    "page": 1,
                    "advanced_order": { "orderby": "newest", "order": "desc" },
                    "search_field": [ { "type": "text", "text": "smart ring" } ]
                  }
                },
                "pageTwoSameSnapshot": {
                  "value": {
                    "page": 2,
                    "last_hit": 1786180640,
                    "advanced_order": { "orderby": "newest", "order": "desc" },
                    "search_field": [ { "type": "text", "text": "smart ring" } ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success or failure application envelope. Require status=ok and meta.code=1000 before using data.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchEnvelope" } } }
          }
        }
      }
    },
    "/v2/ads/{platform}/{ad}": {
      "get": {
        "summary": "Get details for one ad from its source platform",
        "description": "Mega does not support an ad-detail endpoint. For a Mega result, use the returned source platform and ad ID. Detail requests currently cost 100 credits.",
        "operationId": "getAdDetails",
        "parameters": [
          { "$ref": "#/components/parameters/DetailPlatform" },
          { "name": "ad", "in": "path", "required": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "integer" } ] } }
        ],
        "responses": {
          "200": {
            "description": "Success or failure application envelope",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailEnvelope" } } }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Keep the API key server-side and out of URLs, request bodies, logs, analytics, and public repositories."
      }
    },
    "parameters": {
      "SearchPlatform": {
        "name": "platform",
        "in": "path",
        "required": true,
        "schema": { "$ref": "#/components/schemas/SearchPlatform" }
      },
      "DetailPlatform": {
        "name": "platform",
        "in": "path",
        "required": true,
        "schema": { "$ref": "#/components/schemas/DetailPlatform" }
      }
    },
    "schemas": {
      "SearchPlatform": {
        "type": "string",
        "enum": [ "facebook", "meta", "native", "display", "pinterest", "reddit", "x", "youtube", "tiktok", "mega" ]
      },
      "DetailPlatform": {
        "type": "string",
        "enum": [ "facebook", "meta", "native", "display", "pinterest", "reddit", "x", "youtube", "tiktok" ]
      },
      "ApplicationMeta": {
        "type": "object",
        "required": [ "code" ],
        "properties": {
          "code": { "type": "integer", "description": "1000 indicates application success." },
          "message": { "type": [ "string", "null" ] }
        },
        "additionalProperties": true
      },
      "ApiEnvelope": {
        "type": "object",
        "required": [ "status", "meta", "data" ],
        "properties": {
          "status": { "type": "string", "enum": [ "ok", "failed" ] },
          "meta": { "$ref": "#/components/schemas/ApplicationMeta" },
          "data": {}
        },
        "additionalProperties": true
      },
      "AdvancedOrder": {
        "type": "object",
        "properties": {
          "orderby": { "type": "string", "examples": [ "newest", "engagement", "relevancy", "ad_impressions", "days_running", "web_traffic" ] },
          "order": { "type": "string", "enum": [ "asc", "desc" ] }
        },
        "additionalProperties": false
      },
      "SearchFieldItem": {
        "type": "object",
        "required": [ "type", "text" ],
        "properties": {
          "type": { "type": "string", "examples": [ "text", "without_owner" ] },
          "text": { "type": "string" }
        },
        "additionalProperties": false
      },
      "SearchRequest": {
        "type": "object",
        "required": [ "page" ],
        "properties": {
          "page": { "type": "integer", "minimum": 1, "default": 1 },
          "last_hit": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Omit on page 1. Reuse the exact page-one data.last_hit value for later pages." },
          "advanced_order": { "$ref": "#/components/schemas/AdvancedOrder" },
          "search_field": { "type": "array", "items": { "$ref": "#/components/schemas/SearchFieldItem" } }
        },
        "additionalProperties": true,
        "description": "Search filters are dynamic and platform-specific. Retrieve /filters first and use the current filter keys and sub_keys."
      },
      "SearchAd": {
        "type": "object",
        "required": [ "id", "platform" ],
        "properties": {
          "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] },
          "platform": { "$ref": "#/components/schemas/DetailPlatform" },
          "display_url": { "type": "string" },
          "last_seen": { "type": "string", "description": "Display-oriented relative value; use ad details for an exact timestamp." },
          "active": { "type": "boolean" },
          "stats": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "metadata": { "type": "array", "items": { "type": "object", "additionalProperties": true } },
          "owner": { "type": "object", "additionalProperties": true },
          "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": true } }
        },
        "additionalProperties": true
      },
      "SearchData": {
        "type": "object",
        "properties": {
          "ads": { "type": "array", "maxItems": 18, "items": { "$ref": "#/components/schemas/SearchAd" } },
          "current_page": { "type": "integer" },
          "has_next_page": { "type": "boolean" },
          "last_hit": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] }
        },
        "additionalProperties": true
      },
      "SearchEnvelope": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiEnvelope" },
          { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/SearchData" } } }
        ]
      },
      "DetailData": {
        "type": "object",
        "properties": {
          "id": { "oneOf": [ { "type": "integer" }, { "type": "string" } ] },
          "post_url": { "type": "string" },
          "card": { "type": "object", "additionalProperties": true },
          "impression": { "type": "object", "additionalProperties": true },
          "targeting_detail": { "type": "object", "additionalProperties": true },
          "engagement_data": { "type": "object", "additionalProperties": true },
          "url_chain": { "type": "array", "items": {} },
          "domain": { "type": "object", "additionalProperties": true }
        },
        "additionalProperties": true
      },
      "DetailEnvelope": {
        "allOf": [
          { "$ref": "#/components/schemas/ApiEnvelope" },
          { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DetailData" } } }
        ]
      }
    }
  }
}