# CreatorFinder Full AI Context

CreatorFinder is a creator contact verification API for public source URLs. It
is built for humans and agents that need source-backed creator contact records,
not raw scraped pages.

## What CreatorFinder Does

CreatorFinder fetches a public creator/source page, checks that a usable public
email appears on the current live page, extracts supported social or creator
profile URLs, and returns a structured profile record with source provenance.

Every accepted result includes:

- public email
- source URL where the email was verified
- verification timestamp
- supported social/profile URLs
- profile handle when derivable
- short description
- platform and niche labels when inferable
- confidence score
- provenance metadata

## What CreatorFinder Does Not Do

CreatorFinder does not guess emails, synthesize emails, use private datasets,
use breach data, search for credentials, inspect secrets, or return records
without live source-page proof.

## API Base

`https://api.creatorfinder.dev`

## Important Endpoints

### Verify One Source URL

`POST /v1/creator-discovery/verify`

Use this when a caller already has a public creator page, link-in-bio page,
profile page, or contact page.

Example request:

```json
{
  "source_url": "https://creator.example/profile",
  "min_social_count": 1,
  "require_business_email_context": true
}
```

Accepted result shape:

```json
{
  "accepted": true,
  "profile": {
    "public_email": "creator@example.com",
    "email_source_url": "https://creator.example/profile",
    "source_checked_at": "2026-04-29T00:00:00Z",
    "social_urls": [
      {
        "platform": "instagram",
        "url": "https://www.instagram.com/creator"
      }
    ],
    "confidence_score": 0.92
  }
}
```

Rejected result shape:

```json
{
  "accepted": false,
  "rejection": {
    "source_url": "https://creator.example/profile",
    "code": "missing_email",
    "reason": "no usable public email found",
    "retryable": false
  }
}
```

### Quote A Job

`POST /v1/creator-discovery/jobs/quote`

Use this to estimate the launch unit price, maximum cost, and provider plan.

Example request:

```json
{
  "max_results": 50,
  "source_providers": ["sitemap", "common_crawl", "customer_seed"]
}
```

### Inspect Provider Pool

`GET /v1/creator-discovery/providers`

Seed providers discover candidate public URLs only. Every accepted profile still
must pass live source-page verification.

## Common Rejection Codes

- `invalid_source_url`: source URL is not an absolute HTTP(S) URL.
- `source_url_not_allowed`: URL targets localhost, a private network, or a blocked host.
- `source_fetch_failed`: the source page could not be fetched.
- `source_http_error`: the source page returned an HTTP error.
- `source_too_large`: the source response exceeds the configured byte limit.
- `missing_email`: no usable public email was found on the live page.
- `missing_email_context`: email lacks required business/contact context.
- `missing_social`: not enough supported creator profile URLs were found.
- `excluded_policy`: source matched an excluded category term.
- `rate_limited`: caller exceeded the current API rate-limit window.

## Agent Discovery

Agents should read these surfaces:

- `https://creatorfinder.dev/llms.txt`
- `https://creatorfinder.dev/llms-full.txt`
- `https://api.creatorfinder.dev/openapi.json`
- `https://api.creatorfinder.dev/.well-known/agent-capabilities.json`
- `https://api.creatorfinder.dev/.well-known/x402`

Runtime payment metadata from the API is authoritative. Public discovery files
are advisory.

## Pricing

The launch unit price is USD 0.010000 per verified creator result. Agents should
use quotes, budget caps, idempotency keys, and runtime payment metadata or 402
challenges when available.

## Current Status

The deployed API supports live source URL verification, provider pool inspection,
job quotes, job status surfaces, JSON/CSV result routes, machine-readable
errors, rate limits, source URL guards, OpenAPI, llms.txt, and x402 metadata.