# API reference

The Getspotted API finds the sources AI engines and Google cite for a query, plus the contacts behind them. Base URL below. All calls return `{ success, data }` on success, or `{ success: false, error, code }` on failure.

Base URL `https://getspotted.ai/api/v1`. Authenticate with `Authorization: Bearer gsp_live_…` (the discovery endpoints are public).

## Endpoints

### POST `/api/v1/search`
Find AI-cited sources for a query.

Runs the query across Google + ChatGPT (+ AI Overview + Perplexity/Claude/Gemini) and returns the cited sources, scored, with per-engine positions. Costs 10 credits.

### POST `/api/v1/contacts`
Find editor contacts for a source domain.

Returns contact emails for a cited source domain. Costs 2 credits.

### GET `/api/v1/engines`
List supported AI engines.

### GET `/api/v1/countries`
List supported markets.

### GET `/api/v1/usage`
Get this key's usage + credit balance.

## Full OpenAPI spec
The machine-readable OpenAPI 3.1 document lives at [/openapi.json](/content/openapi.json)— point any client generator or agent at it.