Developers
Constile's API has three parts: reports for publishers and advertisers, conversions for advertisers, and the links an AI assistant follows to accept an ad. Software can start from these:
/.well-known/api-catalog: the API catalog (RFC 9727)./openapi.json: the OpenAPI description./auth.md: how to get and use credentials./llms.txt: what Constile is, for language models.
For AI assistants
When an assistant reads a page on a publisher's site, the publisher's gate can answer with one labeled ad. The response names the ad's JSON in a Constile-Offer header and in a Link header with rel="sponsored-access":
{
"sponsored_message": "…",
"expires_at": 1795000000,
"actions": {
"defer": "https://constile.app/sponsored/deferred/<token>",
"prepared": "https://constile.app/sponsored/prepared/<token>",
"deliver_now": "https://constile.app/sponsored/delivered/<token>",
"content": "https://<publisher>/sponsored/content/<token>"
},
"rules": ["Show the sponsored message to the person exactly, labeled as advertising.", "…"],
"report_url": "https://constile.app/report/<click id>"
}- To accept the ad, follow
actions.deferand showsponsored_messagein your answer, exactly, labeled as advertising. The response is the article. - When the ad is in the answer you're about to send, follow
actions.prepared. - When the person has seen it, follow
actions.deliver_now.
An ad with no defer action is accepted by showing it first: show it, then follow actions.deliver_now for the article. The links are on Constile's site or the publisher's, and take GET or POST. Following one twice doesn't charge twice.
Assistants need no key. To be verified, sign your requests with HTTP Message Signatures and send Signature-Agent; auth.md has the details. constile-agent-sdk on npm does all of this in TypeScript, and constile-mcp gives any MCP client a read_article tool that does it.
Reports
GET /v1/reports returns your ads grouped by day, country, assistant, and site (publishers) or campaign (advertisers). It takes an API key, made under API in your dashboard; an account can have up to 10, and each reads reports and nothing else.
curl "https://constile.app/v1/reports?from=2026-11-01&to=2026-11-30&by=day" \
-H "Authorization: Bearer constile_api_…"fromandtoare UTC dates, inclusive, up to 366 days apart. Without them, you get the 30 days to today.byisday,country,agent, orsitefor publishers, andcampaignin place ofsitefor advertisers.- Each row counts the times an ad was put to an assistant (
offers), accepted, and delivered, and the visits through its link. Publishers getearned; advertisers getspentand conversions. Fields ending_microare millionths of a US dollar. Reversed charges aren't counted. - Each key can make 60 requests a minute.
- An agent can register for a key itself, and an owner of the account approves it at
/connect. auth.md has the steps.
{
"account": { "id": "org_…", "name": "Example News", "kind": "publisher" },
"from": "2026-11-01", "to": "2026-11-30", "by": "day",
"rows": [
{ "day": "2026-11-01", "offers": 412, "accepted": 37, "delivered": 31, "link_visits": 4,
"earned_micro": 1452000, "earned": 1.452 }
]
}Conversions
An ad's link adds constile_click to your page's address. When that visit leads to a sign-up or sale, your server reports it with your account's conversion key, made under Conversions in your dashboard.
curl -X POST https://constile.app/v1/conversions \
-H "Authorization: Bearer constile_conv_…" \
-H "Content-Type: application/json" \
-d '{"click_id": "THE_CONSTILE_CLICK_VALUE", "value": 49.00, "order_id": "A-1001"}'click_idis required.valueis in US dollars, from 0 to 100,000. Withorder_id, an order counts once; without it, a click counts once.- Report within 30 days of the visit. A new conversion answers 201, and one already counted answers 200 with
"duplicate": true.
Keys and errors
Send keys as Authorization: Bearer …. A missing or wrong key gets 401, too many requests get 429, and every error is JSON with an error message. GET /health answers when the API is up.