Constile

Reads web pages for an assistant and handles Constile ads the way the person chose.

Documentation

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:

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>"
}
  1. To accept the ad, follow actions.defer and show sponsored_message in your answer, exactly, labeled as advertising. The response is the article.
  2. When the ad is in the answer you're about to send, follow actions.prepared.
  3. 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_…"
  • from and to are UTC dates, inclusive, up to 366 days apart. Without them, you get the 30 days to today.
  • by is day, country, agent, or site for publishers, and campaign in place of site for advertisers.
  • Each row counts the times an ad was put to an assistant (offers), accepted, and delivered, and the visits through its link. Publishers get earned; advertisers get spent and conversions. Fields ending _micro are 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_id is required. value is in US dollars, from 0 to 100,000. With order_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.