{
  "openapi": "3.0.0",
  "info": {
    "title": "WaveInflu API",
    "version": "2.0.0",
    "description": "WaveInflu creator-discovery APIs for Instagram, TikTok, and YouTube: Similar Creators (from a seed account), AI Search (from a natural-language brief), and Email Lookup (contact email for one creator)."
  },
  "servers": [
    {
      "url": "https://api.aisa.one/apis/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "EmailResult": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "Lookup outcome: `found` when an address was resolved, otherwise a not-found status. A not-found result is normal and is still billed as one valid lookup.",
            "example": "found"
          },
          "value": {
            "type": "string",
            "nullable": true,
            "description": "Primary contact email, or null when none was found.",
            "example": "onkimia.mexico@gmail.com"
          }
        }
      },
      "EmailLookupData": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "description": "Platform parsed from the profile URL: instagram, tiktok, or youtube.",
            "example": "instagram"
          },
          "profile_url": {
            "type": "string",
            "description": "Normalized creator profile URL used for this lookup.",
            "example": "https://www.instagram.com/onkimia/"
          },
          "email": {
            "$ref": "#/components/schemas/EmailResult"
          }
        }
      },
      "CreatorFilters": {
        "type": "object",
        "description": "Optional filters applied before matching. All fields are optional.",
        "properties": {
          "regions": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Creator regions (ISO country codes), e.g. [\"US\", \"GB\", \"JP\"]."
          },
          "languages": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Creator languages, e.g. [\"en\", \"ja\", \"zh-cn\"]."
          },
          "minFollowers": {
            "type": "number",
            "description": "Minimum follower / subscriber count."
          },
          "maxFollowers": {
            "type": "number",
            "description": "Maximum follower / subscriber count."
          },
          "minPlayCount": {
            "type": "number",
            "description": "Minimum play / view count, measured by `playCountMetric`."
          },
          "maxPlayCount": {
            "type": "number",
            "description": "Maximum play / view count, measured by `playCountMetric`."
          },
          "playCountMetric": {
            "type": "string",
            "enum": ["median", "average"],
            "description": "Whether `minPlayCount` / `maxPlayCount` are compared against the median or the average play count."
          },
          "genders": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Inferred creator genders, e.g. [\"female\", \"male\"]."
          },
          "ethnicities": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Inferred creator ethnicities."
          },
          "creatorTypes": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Creator account types, e.g. [\"individual\", \"brand\"]."
          },
          "faceVisibilities": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Face-visibility classifications, e.g. [\"clear_face\", \"mixed\", \"no_face\"]."
          },
          "workspaceDeduplicationEnabled": {
            "type": "boolean",
            "description": "When true, creators already saved in your workspace are excluded from the results."
          }
        }
      },
      "Creator": {
        "type": "object",
        "description": "A matched creator. Fields are consistent across Similar Creators and AI Search.",
        "properties": {
          "id": { "type": "string", "description": "Platform-side creator ID." },
          "username": { "type": "string", "description": "Creator handle (without the leading @)." },
          "fullName": { "type": "string", "description": "Creator display name." },
          "biography": { "type": "string", "description": "Profile bio text." },
          "email": { "type": "string", "nullable": true, "description": "Contact email extracted from the profile, when available." },
          "followerCount": { "type": "number", "description": "Follower / subscriber count." },
          "region": { "type": "string", "description": "Creator region (ISO country code)." },
          "language": { "type": "string", "description": "Primary content language." },
          "averagePlayCount": { "type": "number", "description": "Average play / view count across recent posts." },
          "medianPlayCount": { "type": "number", "description": "Median play / view count across recent posts." },
          "averageEngagementRate": { "type": "number", "description": "Average engagement rate (0–1)." },
          "medianEngagementRate": { "type": "number", "description": "Median engagement rate (0–1)." },
          "gender": { "type": "string", "description": "Inferred gender, or `unknown`." },
          "ageRange": { "type": "string", "description": "Inferred age range (e.g. `25_34`), or `unknown`." },
          "ethnicity": { "type": "string", "description": "Inferred ethnicity, or `unknown`." },
          "faceVisibility": { "type": "string", "description": "Face-visibility classification, e.g. `clear_face`, `mixed`, `no_face`." },
          "accountPositioning": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Short AI-generated tags summarizing the creator's niche / positioning."
          },
          "aiDescription": { "type": "string", "description": "AI-generated summary of the creator's content, style, and typical visuals." },
          "platform": { "type": "string", "description": "Platform this creator belongs to: instagram, tiktok, or youtube." },
          "profileUrl": { "type": "string", "description": "Creator profile URL." },
          "score": { "type": "number", "description": "Match relevance score (0–1), sorted descending." }
        }
      },
      "CreatorSearchData": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Creator" },
            "description": "Matched creators, sorted by `score` descending."
          },
          "count": {
            "type": "number",
            "description": "Number of creators delivered. Billing is based on this delivered count.",
            "example": 2
          }
        }
      }
    }
  },
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/waveinflu/similar": {
      "post": {
        "x-aisa-pricing": {
          "model": "dynamic",
          "currency": "USD",
          "basis": "provider_cost x 1.45",
          "nominal_usd": 0.00722,
          "unit": "per delivered creator",
          "cost_drivers": [
            {
              "param": "count (delivered creators)",
              "effect": "total charge = number of creators returned x per-creator rate; use `limit` to cap it"
            }
          ],
          "cost_tier": "variable",
          "note": "nominal_usd is the per-delivered-creator reference rate; total charge = data.count x rate x your account multiplier and scales with how many creators are returned."
        },
        "summary": "Similar Creators",
        "description": "Finds creators similar to a seed account on Instagram, TikTok, or YouTube. `platform` and `target_account` are required; add `limit` (1–100, default 40) and optional `filters` (regions, languages, follower and play-count ranges, gender, ethnicity, creator type, face visibility, workspace dedup). Each match returns a rich profile: `biography`, `email`, `followerCount`, `averagePlayCount` / `medianPlayCount`, `averageEngagementRate` / `medianEngagementRate`, plus AI-inferred `gender`, `ageRange`, `ethnicity`, `faceVisibility`, `accountPositioning` tags, and an `aiDescription`, with a relevance `score`. Results are sorted by `score` descending. Billing is per delivered creator (`data.count`).",
        "operationId": "post_waveinflu_similar_creators",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["platform", "target_account"],
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": ["instagram", "tiktok", "youtube"],
                    "description": "Target platform.",
                    "example": "instagram"
                  },
                  "target_account": {
                    "type": "string",
                    "description": "Seed account: a creator handle (with or without @) or profile URL to find similar creators for.",
                    "example": "@onkimia"
                  },
                  "limit": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 40,
                    "description": "Maximum number of creators to return. Default 40, range 1–100. Caps the billed count.",
                    "example": 10
                  },
                  "filters": {
                    "$ref": "#/components/schemas/CreatorFilters"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Similar creators returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestId": { "type": "string", "description": "Request ID for support and monitoring.", "example": "req-b33" },
                    "billingRequestId": { "type": "string", "description": "Billing reference for this call, linked to your usage log.", "example": "a328145e-3cc9-45c7-89f9-a5f15b236d4f" },
                    "data": { "$ref": "#/components/schemas/CreatorSearchData" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/waveinflu/ai-search": {
      "post": {
        "x-aisa-pricing": {
          "model": "dynamic",
          "currency": "USD",
          "basis": "provider_cost x 1.45",
          "nominal_usd": 0.00722,
          "unit": "per delivered creator",
          "cost_drivers": [
            {
              "param": "count (delivered creators)",
              "effect": "total charge = number of creators returned x per-creator rate; use `limit` to cap it"
            }
          ],
          "cost_tier": "variable",
          "note": "nominal_usd is the per-delivered-creator reference rate; total charge = data.count x rate x your account multiplier and scales with how many creators are returned."
        },
        "summary": "AI Search",
        "description": "Finds creators from a natural-language brief instead of a seed account. `platform` and `query` are required; add `limit` (1–100, default 40) and the same optional `filters` as Similar Creators. Describe the creators you want in plain language (for example, \"beauty creators in the US\") and the response returns matching creators in the same rich shape as Similar Creators — full profile metrics plus AI-inferred `gender`, `ageRange`, `ethnicity`, `faceVisibility`, `accountPositioning`, `aiDescription`, and a relevance `score`. Billing is per delivered creator (`data.count`).",
        "operationId": "post_waveinflu_ai_search",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["platform", "query"],
                "properties": {
                  "platform": {
                    "type": "string",
                    "enum": ["instagram", "tiktok", "youtube"],
                    "description": "Target platform.",
                    "example": "instagram"
                  },
                  "query": {
                    "type": "string",
                    "description": "Natural-language description of the creators you are looking for.",
                    "example": "beauty creators in the US"
                  },
                  "limit": {
                    "type": "number",
                    "minimum": 1,
                    "maximum": 100,
                    "default": 40,
                    "description": "Maximum number of creators to return. Default 40, range 1–100. Caps the billed count.",
                    "example": 10
                  },
                  "filters": {
                    "$ref": "#/components/schemas/CreatorFilters"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Creators returned",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestId": { "type": "string", "description": "Request ID for support and monitoring.", "example": "req-b6l" },
                    "billingRequestId": { "type": "string", "description": "Billing reference for this call, linked to your usage log.", "example": "3f522b56-2bb4-426c-9b76-5c04c91a9cb3" },
                    "data": { "$ref": "#/components/schemas/CreatorSearchData" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/waveinflu/email-lookup": {
      "post": {
        "x-aisa-pricing": {
          "model": "dynamic",
          "currency": "USD",
          "basis": "provider_cost x 1.45",
          "nominal_usd": 0.00289,
          "unit": "per valid lookup",
          "cost_drivers": [
            {
              "param": "one lookup per call",
              "effect": "flat charge per valid lookup, whether or not an email is found"
            }
          ],
          "cost_tier": "flat",
          "note": "Charged once per valid lookup (a not-found result is still a valid lookup). Total = rate x your account multiplier."
        },
        "summary": "Email Lookup",
        "description": "Looks up the contact email for one Instagram, TikTok, or YouTube creator from a profile URL. Pass `profile_url`; the response returns the parsed `platform`, the normalized `profile_url`, and an `email` object `{status, value}`. A `not_found` status (with `value` null) is a normal result, not an error, and is still billed as one valid lookup. Handles one creator per call. To assemble a creator list first, use Similar Creators or AI Search — each match already includes an `email` for most creators; use this endpoint for the ones that come back null.",
        "operationId": "post_waveinflu_email_lookup",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["profile_url"],
                "properties": {
                  "profile_url": {
                    "type": "string",
                    "description": "Instagram, TikTok, or YouTube creator profile URL.",
                    "example": "https://www.instagram.com/onkimia/"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Email lookup completed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "requestId": { "type": "string", "description": "Request ID for support and monitoring.", "example": "req-b6a" },
                    "billingRequestId": { "type": "string", "description": "Billing reference for this call, linked to your usage log.", "example": "7c12fbeb-1f42-4ca0-88f0-353b72ee03f2" },
                    "data": { "$ref": "#/components/schemas/EmailLookupData" }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request. For example, sending the legacy `url` field instead of `profile_url` returns code 10001 and is not billed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "object",
                      "properties": {
                        "code": { "type": "string", "example": "10001" },
                        "message": { "type": "string", "example": "The request is invalid." },
                        "requestId": { "type": "string" },
                        "details": { "type": "array", "items": { "type": "object" } }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}