# BlueWave Public API

Machine-readable catalog: [/.well-known/api-catalog](https://bluewave-agency.com/.well-known/api-catalog)  
OpenAPI: [openapi.json](https://bluewave-agency.com/openapi.json)  
Auth for agents: [auth.md](https://bluewave-agency.com/auth.md)  
GEO brief: [llms.txt](https://bluewave-agency.com/llms.txt)  
Developer hub: [developers](https://bluewave-agency.com/developers/)  
Deprecation policy: [api/deprecation.md](https://bluewave-agency.com/api/deprecation.md)  
ARD: [/.well-known/ard.json](https://bluewave-agency.com/.well-known/ard.json)  
A2A agent card: [/.well-known/agent-card.json](https://bluewave-agency.com/.well-known/agent-card.json)

## What this API is

BlueWave issues agency ad accounts on Meta, TikTok, Google, Bing Ads, X and Telegram Ads. Commercial onboarding is **human-mediated** in Telegram (`https://t.me/bluewave_mngr`). This public API is for discovery, health checks and agent-facing facts — not for automated account purchase.

## Endpoints

### `GET /api/v1/health`

Returns service liveness JSON. Includes `RateLimit-*` headers.

### `GET /api/v1/info`

Returns public BlueWave facts: name, site URL, Telegram contact, platforms, fee tiers, links to pricing, `llms.txt`, `auth.md`, OpenAPI and developers.

### `GET|POST /agent/register`

Anonymous agent registration discovery. No account or bearer token is created. Optional `Idempotency-Key` request header is echoed when present. Commercial provisioning stays in Telegram.

### `POST /a2a/v1`

A2A HTTP+JSON skills: `public-info`, `health`. See the agent card for capability metadata.

## Errors

Unknown `/api/*`, `/a2a/*` and `/agent/*` paths return JSON:

```json
{ "error": "not_found", "message": "...", "docs": "https://bluewave-agency.com/developers/" }
```

Typed error model is documented in OpenAPI (`components.schemas.ErrorResponse`).

## Rate limits

Responses include `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset` (and `X-RateLimit-*` aliases). Soft public discovery limit: 120 requests / minute / client.

## Auth

Public endpoints need no credentials. See [auth.md](https://bluewave-agency.com/auth.md).

## Versioning

URL versioning (`/api/v1`). See [deprecation policy](https://bluewave-agency.com/api/deprecation.md).