Circl API documentation
The Circl API is a read-only REST API. Public offers need no authentication; a Brand's own data needs an OAuth 2.1 access token. Nothing in the API creates, changes or deletes data. The full machine-readable description is the OpenAPI 3.1 specification. The same data is available through an MCP server.
Base URL
https://joincircl.co/v1. Responses are JSON. Errors are JSON too:
{"code": "not_found", "message": "...", "retryable": false, "correlation_id": "..."}.
Public offers (no authentication)
curl https://joincircl.co/v1/offers
curl https://joincircl.co/v1/offers/{offerId}Limit: 600 requests a minute per address (429 rate_limited, then wait and retry).
Brand data (OAuth, read-only)
An agent connects with OAuth 2.1 authorization code and PKCE; dynamic client registration is
open and the Brand user approves on a consent screen. There is no API key. Steps:
auth.md; discovery:
/.well-known/oauth-protected-resource.
Every grant is read-only. A request without a valid token answers
401 with WWW-Authenticate: Bearer resource_metadata="...".
curl https://joincircl.co/v1/brands -H "Authorization: Bearer $TOKEN"
curl "https://joincircl.co/v1/brands/{brandId}/directory?q=beaute&country=FR" -H "Authorization: Bearer $TOKEN"| Endpoint | Returns |
|---|---|
GET /v1/offers | Public offers |
GET /v1/offers/{offerId} | One public offer, as published |
GET /v1/brands | Your Brand spaces (call first) |
GET /v1/brands/{brandId}/directory | Creator directory search (q, niche, language, country, page) |
GET /v1/brands/{brandId}/directory/{profileId} | One creator profile |
GET /v1/brands/{brandId}/offers | The Brand's offers |
GET /v1/brands/{brandId}/offers/{offerId} | An offer with its frozen terms |
GET /v1/brands/{brandId}/collaborations | Collaborations with status and next action |
GET /v1/brands/{brandId}/collaborations/{collaborationId} | One collaboration |
Limit: 60 requests a minute per user.
Versioning
The version is in the path (/v1). Changes inside v1 only add fields or endpoints. A breaking change ships as /v2; v1 then answers with Deprecation and Sunset headers at least 6 months before removal. Every response carries RateLimit-Limit and RateLimit-Policy; a 429 carries Retry-After.
More for agents
llms.txt, AI catalog, skills, pricing. Browser agents can use the WebMCP tools registered on the homepage.