API reference

cn2.ai exposes two types of endpoints: proxy endpoints (for buyers making API calls) and platform endpoints (for sellers managing keys and configuration).

Proxy endpoints

Every supported provider has a subdomain that mirrors the upstream API. Send the same request you would send to the provider, but to the cn2.ai subdomain instead. Payment is handled via MPP.

# Instead of:
POST https://api.openai.com/v1/chat/completions

# Use:
POST https://openai.cn2.ai/v1/chat/completions

Request headers

Header	Required	Description
Authorization	On retry	`Payment <credential>` — MPP payment credential from the 402 challenge
X-CN2-Pool	Optional	Set to `premium` for premium pool routing (25% higher cost, higher reliability)
Content-Type	Yes	`application/json` for most endpoints

Response headers

Header	When	Description
WWW-Authenticate	402 response	Payment challenge with pricing and accepted methods
Payment-Receipt	Successful paid request	Proof of payment — save this for dispute submissions

Platform API

Sellers use the platform API to manage keys, view earnings, and configure webhooks. All platform endpoints require authentication via a bearer token from Supabase Auth.

Keys

POST	/api/keys	Create a new key listing
GET	/api/keys	List all your keys
GET	/api/keys/:id	Get key details
PATCH	/api/keys/:id	Update key configuration
DELETE	/api/keys/:id	Remove a key listing
POST	/api/keys/:id/rotate	Start key rotation
POST	/api/keys/import	Bulk CSV import

Marketplace (public)

GET

/api/marketplace/providers

List providers with pool stats

Webhooks

GET	/api/webhooks	List webhook endpoints
POST	/api/webhooks	Create webhook endpoint
PATCH	/api/webhooks/:id	Update endpoint
DELETE	/api/webhooks/:id	Delete endpoint

Disputes (buyer)

POST	/api/disputes	Submit a dispute
GET	/api/disputes	List your disputes

Discovery

GET	/openapi.json	OpenAPI 3.1 spec (per subdomain)
GET	/.well-known/mcp.json	MCP Server Card (per subdomain)
GET	/.well-known/agent-card.json	A2A Agent Card (per subdomain)
GET	/.well-known/api-catalog	RFC 9727 API catalog (root domain)

See error codes for the full list of error responses.