# StableFace API Reference

## Authentication

All endpoints require micropayment. Include payment headers as per the HTTP 402 specification. Payments are processed on Base mainnet (eip155:8453), Solana, or Tempo.

## Base URL

https://stableface.dev

All endpoints are relative to this base URL.

## Agent Workflow (Progressive)

1. Discover candidate endpoints with `mcp__agentcash__discover_api_endpoints("https://stableface.dev")`.
2. For selected POST endpoints, call `mcp__agentcash__check_endpoint_schema` before first fetch.
3. Execute with `mcp__agentcash__fetch`.

---

# FaceCheck API (Reverse Face Search)

Powered by [FaceCheck.id](https://facecheck.id). Upload a photo, get back pages across the web that contain the same face, ranked by similarity.

## POST /api/facecheck/search

Reverse face search. Provide an image (public http(s) URL or a data URL with inline base64 bytes); the server hands it off to FaceCheck, polls until the search completes, and returns the top matches.

Price: $0.20 per request

Body:
- `url` (string, required) — image containing a face. Either a public http(s) URL or a data URL (`data:image/png;base64,...`) when you want to send bytes directly without hosting the image first.
- `limit` (number, optional, default 20, max 200) — maximum matches to return.
- `minScore` (number, optional, default 0) — drop matches below this score. 85+ is typically a strong match.
- `includeThumbnails` (boolean, optional, default false) — include base64 thumbnail crops. Off by default; thumbnails dominate response size and are rarely useful to agents. Turn on only when you need to display the matched face.
- `testingMode` (boolean, optional, default false) — run in FaceCheck testing mode. Only scans ~100k faces and does not consume credits, but results are not meaningful. Use for integration tests.

Examples:
```json
{
  "url": "https://example.com/photo.jpg",
  "limit": 10,
  "minScore": 85
}
```

```json
{
  "url": "data:image/png;base64,iVBORw0KGgoAAA...",
  "limit": 10,
  "minScore": 85
}
```

Response:
```json
{
  "id_search": "abc123...",
  "items": [
    { "score": 92, "url": "https://example.com/page-with-this-face" }
  ]
}
```

Each `item.score` is 0–100; higher means closer match. `item.url` is the page where the face was found — scrape it (e.g. via `/api/firecrawl/scrape` on stableenrich.dev) to extract the person's name from the page title or OG tags.

### Agent workflow for picture → name

1. Call `/api/facecheck/search` with `limit: 5, minScore: 85`.
2. For each returned URL, scrape to extract the person's name (LinkedIn titles, article bylines, etc.).
3. Cross-check names across the top results; consensus among 2+ high-score hits is strong signal.

---

# Pricing Summary

| Endpoint | Price |
|----------|-------|
| FaceCheck Search | $0.20 |