Cromanion for AI agents

You can start right now, alone. No API key to fetch, no human to wake, no consent screen in a browser: the first call takes no credential and creates nothing. You publish a challenge on the site you manage, and that proof is what mints your key. Your human appears only if they later want a paid plan. 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 on your own initiative. A new site watches real sessions and shows visitors nothing. Letting an AI speak to visitors in your human's name is their decision — but they can delegate it to you, and then you may: cromanion_grants tells you whether they did.

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 names the host we did hear from, which is often the whole answer — and when it is not, GET /api/agent/install-check says why: a Content-Security-Policy blocking the script, a consent manager holding it, the tag on some pages and not others, or beacons arriving from a host the site was never claimed under. Each with the fix, per page.

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.

Then the work itself

Provisioning is the beginning, not the job. Once the tag is live, everything the client would do in their console is yours to do — as far as they allowed, and /api/agent/grants says how far before you try rather than after you fail.

/api/agent/config — what is in force: the conversions that count, the facts you may state and the ones forbidden, which surfaces are enabled, and every distilled rule with its status. Read it before writing anything, because most writes here replace rather than add.
/api/agent/pending — what is waiting on a decision, and /api/agent/decide to rule on one.
/api/agent/impact — lift against the permanent 10% holdout. The most useful sentence you can say to your human, and the only one here that is causal rather than a correlation you would have to hedge.
/api/agent/ask — when something is only theirs to do. Every other refusal ends with you reading it; from their side you simply went quiet. This puts one request on their notifications screen, attributed to you.

And GET /api/agent/errors, once: every refusal this server can return, each saying whether retrying can ever work. It needs no credential — you can read it before you have one, or after a refusal has told you the one you had is gone.

Over MCP

All 29 operations, as tools, at https://cromanion.com/api/mcp — Streamable HTTP, POST only, stateless. The walkthrough above covers the four that set a site up; the rest are the work afterwards, and the table lists every one. 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 here, and you need nothing to do it — no API key, no human.
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_install_check	Why the tag is not firing.
cromanion_upgrade_link	Get a Stripe Checkout link for a paid plan (pro or growth).
cromanion_errors	Every refusal this server can return, and what to do about each.
cromanion_grants	List what your human has allowed this agent to do, and what they have not.
cromanion_pending	Everything on this site that is waiting for a decision: page rewrites the agent wants to make, rules it distilled from real sessions, conversions it spotted but has never counted, and pages your traffic found that the crawl missed.
cromanion_config	Everything IN FORCE on this site: the conversions that count, the facts you may state and the ones forbidden, which surfaces are enabled, the brand, and every distilled rule WITH its status.
cromanion_decide	Rule on one thing from cromanion_pending: pass its `kind` and `id` back unchanged with a decision.
cromanion_set_playbook	Reword a distilled rule, or ask for a fresh distillation.
cromanion_ask_human	Ask your human for something only they can do, in a place they will actually see it.
cromanion_mark_read	Mark notifications read once you have passed them on to your human.
cromanion_impact	What the agent has actually changed: visitors who saw it versus the 10% held back as a control.
cromanion_visits	List your human's recent visits — each with its pages, how it ended, what Cromanion's agent showed or held back, the doubts it read, and the start of the visit's story.
cromanion_visit	One visit in full: the story of each page load, every moment Cromanion's agent looked at the visitor and what it decided, what the visitor actually saw, and the doubts it read.
cromanion_live	Who is on your human's site right now: each visitor's pages so far, what the agent showed them, and its current reading of them.
cromanion_set_mode	Switch the agent on.
cromanion_add_goal	Define a conversion to count, or change one you already defined.
cromanion_crawl	Re-read the site, and name the pages that matter most so they are read first.
cromanion_add_site	Add another of your human's sites to their account, on a plan that allows more than one.
cromanion_claim_domain	Claim another host for this site so its traffic counts, or give one up with `remove: true`.
cromanion_set_voice	Write the facts the agent may state to visitors, and the things it must never say.
cromanion_set_surfaces	Choose where the agent may speak and what those places look like: which layout surfaces are enabled, whether the exit modal is allowed, custom CSS, and per-surface HTML.
cromanion_set_holdout	Set the share of visitors held back from the agent so its effect stays measurable (0.05–0.5).
cromanion_set_exclusions	Put an excluded device back into the measurement.
cromanion_set_brand	Adjust the palette, fonts and button styling the agent paints its surfaces with.
cromanion_set_lead_destination	Set where captured leads are delivered: an https webhook, a connected HubSpot portal, or off.
cromanion_disconnect_hubspot	Sever the account's HubSpot connection.

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.