{
  "openapi": "3.1.0",
  "info": {
    "title": "CreatorFinder API",
    "version": "0.1.0",
    "description": "Public creator discovery and source verification with verified email provenance.",
    "x-guidance": "Use POST /v1/creator-discovery/jobs to find creators by niche/platform. The job discovers public candidate pages and verifies each accepted result against the current live source page. Use POST /v1/creator-discovery/verify when you already have a public source_url."
  },
  "servers": [
    {
      "url": "https://api.creatorfinder.dev"
    }
  ],
  "paths": {
    "/v1/creator-discovery/jobs/quote": {
      "post": {
        "operationId": "quoteCreatorDiscoveryJob",
        "summary": "Quote a creator discovery job.",
        "description": "Returns estimated maximum cost, provider plan, discovery limits, and pricing semantics for a niche/platform creator discovery job.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "niche": {
                    "type": "string",
                    "description": "Creator niche, topic, or audience segment to find."
                  },
                  "segment": {
                    "type": "string",
                    "description": "Natural-language creator segment. Treated as additional niche/query context."
                  },
                  "query": {
                    "type": "string",
                    "description": "Natural-language discovery query. Treated as additional niche/query context."
                  },
                  "keywords": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ],
                    "description": "Optional extra terms used to rank and filter verified profiles."
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Required public social/profile platforms, such as youtube, instagram, tiktok, twitch, x, or substack."
                  },
                  "source_providers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional provider allow-list. Defaults to sitemap, common_crawl, and customer_seed."
                  },
                  "seed_urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": "Optional public seed/source URLs to verify first."
                  },
                  "max_results": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 25,
                    "description": "Maximum verified creator records to return."
                  },
                  "budget_cap_usd": {
                    "type": "string",
                    "description": "Advisory budget cap for agents. Current launch price is applied per verified creator."
                  }
                }
              },
              "examples": {
                "ai_youtube": {
                  "value": {
                    "niche": "AI tools",
                    "platforms": [
                      "youtube",
                      "instagram"
                    ],
                    "max_results": 10,
                    "seed_urls": [
                      "https://bio.site/examplecreator"
                    ],
                    "budget_cap_usd": "0.10"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Discovery job quote."
          },
          "400": {
            "description": "Bad request"
          }
        }
      }
    },
    "/v1/creator-discovery/jobs": {
      "post": {
        "operationId": "createCreatorDiscoveryJob",
        "summary": "Find verified public creator contacts by niche and platform.",
        "description": "Creates a discovery job. The Worker finds candidate public creator pages from configured seed providers, then live-verifies each accepted result before storing it. State-changing calls require Idempotency-Key.",
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 12
            },
            "description": "Replay-safe key for creating the discovery job."
          }
        ],
        "extensions": {
          "bazaar": {
            "info": {
              "input": {
                "type": "http",
                "bodyType": "json",
                "body": {
                  "niche": "AI tools",
                  "platforms": [
                    "youtube",
                    "instagram"
                  ],
                  "max_results": 10,
                  "seed_urls": [
                    "https://bio.site/examplecreator"
                  ],
                  "budget_cap_usd": "0.10"
                }
              },
              "output": {
                "type": "json",
                "example": {
                  "job_id": "cj_example",
                  "status": "queued",
                  "query": "AI tools",
                  "platforms": [
                    "youtube",
                    "instagram"
                  ],
                  "requested_max_results": 10,
                  "verified_count": 0,
                  "results": []
                }
              }
            },
            "schema": {
              "$schema": "https://json-schema.org/draft/2020-12/schema",
              "type": "object",
              "properties": {
                "input": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "http"
                    },
                    "method": {
                      "type": "string",
                      "enum": [
                        "POST",
                        "PUT",
                        "PATCH"
                      ]
                    },
                    "bodyType": {
                      "type": "string",
                      "enum": [
                        "json",
                        "form-data",
                        "text"
                      ]
                    },
                    "body": {
                      "type": "object",
                      "additionalProperties": false,
                      "properties": {
                        "niche": {
                          "type": "string",
                          "description": "Creator niche, topic, or audience segment to find."
                        },
                        "segment": {
                          "type": "string",
                          "description": "Natural-language creator segment. Treated as additional niche/query context."
                        },
                        "query": {
                          "type": "string",
                          "description": "Natural-language discovery query. Treated as additional niche/query context."
                        },
                        "keywords": {
                          "oneOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "array",
                              "items": {
                                "type": "string"
                              }
                            }
                          ],
                          "description": "Optional extra terms used to rank and filter verified profiles."
                        },
                        "platforms": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Required public social/profile platforms, such as youtube, instagram, tiktok, twitch, x, or substack."
                        },
                        "source_providers": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Optional provider allow-list. Defaults to sitemap, common_crawl, and customer_seed."
                        },
                        "seed_urls": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "format": "uri"
                          },
                          "description": "Optional public seed/source URLs to verify first."
                        },
                        "max_results": {
                          "type": "integer",
                          "minimum": 1,
                          "default": 25,
                          "description": "Maximum verified creator records to return."
                        },
                        "budget_cap_usd": {
                          "type": "string",
                          "description": "Advisory budget cap for agents. Current launch price is applied per verified creator."
                        }
                      }
                    }
                  },
                  "required": [
                    "type",
                    "method",
                    "bodyType",
                    "body"
                  ],
                  "additionalProperties": false
                },
                "output": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "example": {
                      "type": "object",
                      "required": [
                        "job_id",
                        "status",
                        "requested_max_results",
                        "verified_count",
                        "results"
                      ],
                      "additionalProperties": true,
                      "properties": {
                        "job_id": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string",
                          "enum": [
                            "queued",
                            "running",
                            "completed",
                            "failed",
                            "cancelled"
                          ]
                        },
                        "query": {
                          "type": "string"
                        },
                        "niche_terms": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "platforms": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        },
                        "requested_max_results": {
                          "type": "integer"
                        },
                        "candidate_count": {
                          "type": "integer"
                        },
                        "checked_source_count": {
                          "type": "integer"
                        },
                        "verified_count": {
                          "type": "integer"
                        },
                        "charged_count": {
                          "type": "integer"
                        },
                        "unit_price": {
                          "type": "string"
                        },
                        "settled_total": {
                          "type": "string"
                        },
                        "results": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "rejections": {
                          "type": "array",
                          "items": {
                            "type": "object"
                          }
                        },
                        "message": {
                          "type": "string"
                        }
                      }
                    }
                  },
                  "required": [
                    "type"
                  ]
                }
              },
              "required": [
                "input"
              ]
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "niche": {
                    "type": "string",
                    "description": "Creator niche, topic, or audience segment to find."
                  },
                  "segment": {
                    "type": "string",
                    "description": "Natural-language creator segment. Treated as additional niche/query context."
                  },
                  "query": {
                    "type": "string",
                    "description": "Natural-language discovery query. Treated as additional niche/query context."
                  },
                  "keywords": {
                    "oneOf": [
                      {
                        "type": "string"
                      },
                      {
                        "type": "array",
                        "items": {
                          "type": "string"
                        }
                      }
                    ],
                    "description": "Optional extra terms used to rank and filter verified profiles."
                  },
                  "platforms": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Required public social/profile platforms, such as youtube, instagram, tiktok, twitch, x, or substack."
                  },
                  "source_providers": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Optional provider allow-list. Defaults to sitemap, common_crawl, and customer_seed."
                  },
                  "seed_urls": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uri"
                    },
                    "description": "Optional public seed/source URLs to verify first."
                  },
                  "max_results": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 25,
                    "description": "Maximum verified creator records to return."
                  },
                  "budget_cap_usd": {
                    "type": "string",
                    "description": "Advisory budget cap for agents. Current launch price is applied per verified creator."
                  }
                }
              },
              "examples": {
                "ai_youtube": {
                  "value": {
                    "niche": "AI tools",
                    "platforms": [
                      "youtube",
                      "instagram"
                    ],
                    "max_results": 10,
                    "seed_urls": [
                      "https://bio.site/examplecreator"
                    ],
                    "budget_cap_usd": "0.10"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Discovery job accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "job_id",
                    "status",
                    "requested_max_results",
                    "verified_count",
                    "results"
                  ],
                  "additionalProperties": true,
                  "properties": {
                    "job_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running",
                        "completed",
                        "failed",
                        "cancelled"
                      ]
                    },
                    "query": {
                      "type": "string"
                    },
                    "niche_terms": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "platforms": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "requested_max_results": {
                      "type": "integer"
                    },
                    "candidate_count": {
                      "type": "integer"
                    },
                    "checked_source_count": {
                      "type": "integer"
                    },
                    "verified_count": {
                      "type": "integer"
                    },
                    "charged_count": {
                      "type": "integer"
                    },
                    "unit_price": {
                      "type": "string"
                    },
                    "settled_total": {
                      "type": "string"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "rejections": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "409": {
            "description": "Idempotency conflict"
          }
        }
      }
    },
    "/v1/creator-discovery/jobs/{job_id}": {
      "get": {
        "operationId": "getCreatorDiscoveryJob",
        "summary": "Get discovery job status.",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery job.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "job_id",
                    "status",
                    "requested_max_results",
                    "verified_count",
                    "results"
                  ],
                  "additionalProperties": true,
                  "properties": {
                    "job_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running",
                        "completed",
                        "failed",
                        "cancelled"
                      ]
                    },
                    "query": {
                      "type": "string"
                    },
                    "niche_terms": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "platforms": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "requested_max_results": {
                      "type": "integer"
                    },
                    "candidate_count": {
                      "type": "integer"
                    },
                    "checked_source_count": {
                      "type": "integer"
                    },
                    "verified_count": {
                      "type": "integer"
                    },
                    "charged_count": {
                      "type": "integer"
                    },
                    "unit_price": {
                      "type": "string"
                    },
                    "settled_total": {
                      "type": "string"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "rejections": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Job not found"
          }
        }
      }
    },
    "/v1/creator-discovery/jobs/{job_id}/results": {
      "get": {
        "operationId": "getCreatorDiscoveryJobResults",
        "summary": "Get verified creator discovery results.",
        "parameters": [
          {
            "name": "job_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Discovery job results.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "job_id",
                    "status",
                    "requested_max_results",
                    "verified_count",
                    "results"
                  ],
                  "additionalProperties": true,
                  "properties": {
                    "job_id": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "queued",
                        "running",
                        "completed",
                        "failed",
                        "cancelled"
                      ]
                    },
                    "query": {
                      "type": "string"
                    },
                    "niche_terms": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "platforms": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "requested_max_results": {
                      "type": "integer"
                    },
                    "candidate_count": {
                      "type": "integer"
                    },
                    "checked_source_count": {
                      "type": "integer"
                    },
                    "verified_count": {
                      "type": "integer"
                    },
                    "charged_count": {
                      "type": "integer"
                    },
                    "unit_price": {
                      "type": "string"
                    },
                    "settled_total": {
                      "type": "string"
                    },
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "rejections": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Job not found"
          }
        }
      }
    },
    "/v1/creator-discovery/verify": {
      "post": {
        "operationId": "verifyCreatorSource",
        "summary": "Verify one public creator source URL.",
        "description": "Fetches a public creator source URL and returns an accepted profile only when a usable email and supported social URL appear on the current live page. Rejections are typed and not billable.",
        "x-payment-info": {
          "price": {
            "mode": "fixed",
            "currency": "USD",
            "amount": "0.010000"
          },
          "protocols": [
            {
              "x402": {}
            }
          ]
        },
        "extensions": {
          "bazaar": {
            "info": {
              "input": {
                "type": "http",
                "bodyType": "json",
                "body": {
                  "source_url": "https://creator.example/profile",
                  "min_social_count": 1,
                  "require_business_email_context": true
                }
              },
              "output": {
                "type": "json",
                "example": {
                  "accepted": false,
                  "rejection": {
                    "source_url": "https://creator.example/profile",
                    "code": "missing_email",
                    "reason": "no usable public email found",
                    "retryable": false
                  }
                }
              }
            },
            "schema": {
              "$schema": "https://json-schema.org/draft/2020-12/schema",
              "type": "object",
              "properties": {
                "input": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "const": "http"
                    },
                    "method": {
                      "type": "string",
                      "enum": [
                        "POST",
                        "PUT",
                        "PATCH"
                      ]
                    },
                    "bodyType": {
                      "type": "string",
                      "enum": [
                        "json",
                        "form-data",
                        "text"
                      ]
                    },
                    "body": {
                      "type": "object",
                      "required": [
                        "source_url"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "source_url": {
                          "type": "string",
                          "format": "uri",
                          "description": "Public creator source, link-in-bio, profile, or contact page URL to verify."
                        },
                        "min_social_count": {
                          "type": "integer",
                          "minimum": 1,
                          "default": 1,
                          "description": "Minimum supported social/profile URLs required for acceptance."
                        },
                        "require_business_email_context": {
                          "type": "boolean",
                          "default": true,
                          "description": "Require creator/contact/business context near the email when possible."
                        }
                      }
                    }
                  },
                  "required": [
                    "type",
                    "method",
                    "bodyType",
                    "body"
                  ],
                  "additionalProperties": false
                },
                "output": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "example": {
                      "type": "object",
                      "required": [
                        "accepted"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "accepted": {
                          "type": "boolean"
                        },
                        "profile": {
                          "type": "object"
                        },
                        "rejection": {
                          "type": "object"
                        }
                      }
                    }
                  },
                  "required": [
                    "type"
                  ]
                }
              },
              "required": [
                "input"
              ]
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "source_url"
                ],
                "additionalProperties": false,
                "properties": {
                  "source_url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Public creator source, link-in-bio, profile, or contact page URL to verify."
                  },
                  "min_social_count": {
                    "type": "integer",
                    "minimum": 1,
                    "default": 1,
                    "description": "Minimum supported social/profile URLs required for acceptance."
                  },
                  "require_business_email_context": {
                    "type": "boolean",
                    "default": true,
                    "description": "Require creator/contact/business context near the email when possible."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Verification result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "accepted"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "accepted": {
                      "type": "boolean"
                    },
                    "profile": {
                      "type": "object"
                    },
                    "rejection": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request"
          },
          "402": {
            "description": "Payment Required"
          },
          "422": {
            "description": "Source did not verify"
          }
        }
      }
    }
  }
}