Cromanion for AI agents

If you manage a website for someone, you can set Cromanion up for them yourself — create the account, install the tag, confirm it is live — without your human opening a screen. Two doors onto the same flow: plain JSON over HTTP, or MCP.

Two things you cannot do

You cannot pay. The upgrade call returns a Stripe link and nothing else. Your human opens it and enters their own card. Everything below works on the free plan meanwhile, so there is no reason to wait for them.
You cannot switch the site from learn to act. A new site watches real sessions and shows visitors nothing. Letting an AI speak to visitors in your human's name is your human's decision, taken in their console.

How we know the site is theirs

We cannot take your word for the email address — anybody can type any address, and if a typed address were enough, an agent could be handed a live key inside a stranger's account. So we ask for the one thing you can actually prove and a stranger cannot: that you control the site.

You open a claim, we hand you a random challenge, and you publish it somewhere only the site's operator can write. Any one of these three is enough — they differ only in what your hosting lets you write:

a file at /.well-known/cromanion-challenge.txt containing the challenge;
<meta name="cromanion-site-verification" content="…"> in the page's <head>;
a DNS TXT record reading cromanion-site-verification=….

The claim is redeemable for 24 hours. Opening one creates nothing at all — no account, no key, no charge — so there is no cost to starting and no commitment for your human until the proof is read.

Over HTTP

1 · Open a claim. Keep the secret it returns; it is shown once, and it authenticates every later call.

curl -X POST https://cromanion.com/api/agent/claims \
  -H 'content-type: application/json' \
  -d '{
    "email": "your-humans@email.com",
    "siteUrl": "https://their-site.com",
    "agent": "your-agent-name/1.0"
  }'

2 · Publish one of the three proofs the response lists under proofs. Each comes with the exact URL and the exact string, so you never have to build one from this page.

3 · Redeem it. This creates the account and the site and returns the tracking snippet. Safe to retry — a repeat gives you the same account and site, never a second one.

curl -X POST https://cromanion.com/api/agent/claims/verify \
  -H "authorization: Bearer $SECRET"

4 · Install the returned install.snippet before </body> on every page. Do not build the snippet yourself from the install page — the one we return carries the real key and the right hosts.

5 · Confirm it landed. Poll until install.verified is true. That is not "we gave you a snippet"; it means a beacon reached us from your human's own domain. If it stays false, install.lastBeaconOrigin tells you which host we did hear from, which is usually the whole answer.

curl https://cromanion.com/api/agent/site \
  -H "authorization: Bearer $SECRET"

While the response carries crawl.advanceUrl, POST it between polls. That is what advances our reading of the site, and it is why an agent-provisioned site is understood in minutes rather than hours.

6 · Hand over the upgrade, if they want one. POST /api/agent/checkout with {"plan":"pro"} returns a link. Give it to your human.

Over MCP

The same four operations, as tools, at https://cromanion.com/api/mcp — Streamable HTTP, POST only, stateless. Your claim secret goes in the Authorization header, never in a tool argument.

{
  "mcpServers": {
    "cromanion": {
      "type": "http",
      "url": "https://cromanion.com/api/mcp",
      "headers": { "Authorization": "Bearer ${CROMANION_CLAIM_SECRET}" }
    }
  }
}

Tool	Does
cromanion_open_claim	Start signing your human up for Cromanion (the autonomous conversion agent) on a site you manage.
cromanion_verify_claim	Redeem a claim once you have published one of its three proofs (a /.well-known file, a <meta> tag, or a DNS TXT record).
cromanion_site_status	Check the site you provisioned: whether the tag is actually live (a beacon received from your own domain, not merely a snippet handed to you), how the crawl is going, and the plan.
cromanion_upgrade_link	Get a Stripe Checkout link for a paid plan (pro or growth).

When we refuse, and why

Every refusal carries a machine token in error and a sentence in message you can repeat to your human verbatim. Three are worth knowing before you meet them:

email_in_use — that address already has a Cromanion account. Proving you control a site proves nothing about who owns a mailbox, so we will not attach an install to an account on the strength of a typed address. Your human signs in and adds the site; the response carries the link.
domain_taken — another account already has a live tag on that domain. Two tags on one page means two control groups, and then neither side can prove what it changed. A human has to decide which account keeps it.
not_proven — we could not read any of the three proofs yet, and the response says what each lookup saw. mismatch means you published an older claim's challenge; a DNS record can take a few minutes.

What your human gets

An agent that watches every session on their site, predicts what each visitor will do next, and intervenes only when it helps — with a permanent 10% control group, so the effect is measured rather than claimed. It never invents a fact about their business: everything it shows a visitor traces to their own pages or to something they told us themselves. How it works · What it costs.

Something unclear, or a refusal you think is wrong? Tell us — say which call and paste the error token.