Documentation

Everything needed to advertise, integrate or read clues. Advertisers start with a campaign and a clue. Publishers and agent developers start with an integration and one install snippet. Agents start with the policy page. All of it is available through the REST API.

Advertisers

An advertiser account holds a pre-paid balance, campaigns and clues. A campaign defines the pricing model, bids, budgets and matching rules. A clue is the record agents receive. Everything below can also be done with an API key.

1. Top up your balance. The first top-up is $50 or more, by card through Stripe.
2. Create a campaign: choose CPC, CPA or CPM, set a maximum bid and budgets, and define when the campaign should be considered.
3. Write a clue in your own language. clue reviews it against policy in about a minute and translates it into 20 languages.

Matching rules

Leave empty for worldwide. The country comes from the agent's network location or from what the integration tells us. The language the agent asked in. Leave empty for any language. Your clue is translated automatically, so this only limits where you serve. Matched against the integration's declared categories and the page or task context the agent is working in. Leave empty for all types. Training crawlers rarely act on a clue; browsing agents, API clients and MCP clients usually do. What the agent is trying to do. Declared by the integration or the agent, or inferred from the context. Leave empty for all intents. Businesses, consumers or anyone. clue never matches clues to users under 18.

Outcome reporting

When an agent follows a clue we send it to your destination URL with ?clue_id=<id>. When that visit turns into a sign-up, purchase, booking or API call, POST the id back to clue. CPA campaigns are charged at that moment; CPC and CPM campaigns simply record the action in your reports.

POST https://clue.ad/v1/conversions
Authorization: Bearer clue_…
Content-Type: application/json

{"click_id": "sv_…", "kind": "signup", "value_usd": 49, "external_id": "order_123"}

Publishers and agent developers

An integration is a website, API, MCP server or agent you own. Each integration has a key, one or more slots (a slot fixes the format and style of the response), controls, and analytics. Verify ownership once to start earning.

1. Register your website, API, MCP server or agent and verify ownership with a meta tag or a file.
2. Create a slot and choose the format the surface speaks: JSON, Markdown, text, HTML, llms.txt or MCP.
3. Install the tag, middleware or API call. Agent analytics start with the very first request, even before a clue matches.

Server-side integrations detect agents by User-Agent and headers, ask clue for a match, and add the block to HTML, Markdown or JSON before the response leaves your server. Human visitors receive the untouched response.

<script async src="https://clue.ad/tag.js" data-site="site_YOUR_KEY" data-unit="unit_YOUR_UNIT" data-lang="auto" data-max="2"></script>
<!-- optional: where the block should go -->
<div data-clue-slot></div>

// npm i @clue-ad/node   (or copy sdk/node/clue.mjs from the docs)
import { clueMiddleware } from '@clue-ad/node';

// Express / Connect
app.use(clueMiddleware({ site: 'site_YOUR_KEY', unit: 'unit_YOUR_UNIT', base: 'https://clue.ad' }));

// Next.js (app/route.ts or middleware.ts)
import { withClue } from '@clue-ad/node/next';
export default withClue({ site: 'site_YOUR_KEY' })(handler);

// What it does: detects agents (User-Agent + headers), calls https://clue.ad/v1/serve,
// injects <aside data-clue> before </body> for HTML, a "sponsored" array for JSON, a block for Markdown.
// Humans get the untouched response.

# pip install clue-ad   (or copy sdk/python/clue.py)
from clue import ClueMiddleware

# FastAPI / Starlette
app.add_middleware(ClueMiddleware, site="site_YOUR_KEY", unit="unit_YOUR_UNIT", base="https://clue.ad")

# Flask
from clue import flask_clue
flask_clue(app, site="site_YOUR_KEY")

# Django: add "clue.django.ClueMiddleware" to MIDDLEWARE and set CLUE_SITE = "site_YOUR_KEY"

// go get github.com/clue-ad/clue-go   (or copy sdk/go/clue.go)
import clue "github.com/clue-ad/clue-go"

handler := clue.Wrap(mux, clue.Config{Site: "site_YOUR_KEY", Unit: "unit_YOUR_UNIT", Base: "https://clue.ad"})
http.ListenAndServe(":8080", handler)

// Cloudflare Worker in front of your origin (copy sdk/cloudflare/worker.js)
export default {
  async fetch(req, env, ctx) {
    const res = await fetch(req);
    return injectClue(req, res, { site: 'site_YOUR_KEY', unit: 'unit_YOUR_UNIT', base: 'https://clue.ad' });
  }
}

<?php // copy sdk/php/clue.php; WordPress: add to functions.php or use as a mu-plugin
require_once 'clue.php';
clue_start(['site' => 'site_YOUR_KEY', 'unit' => 'unit_YOUR_UNIT', 'base' => 'https://clue.ad']);
// buffers the HTML response and appends the sponsored block for agents only

# Server-side, any language. Forward the visitor's User-Agent so clue can tell agents from humans.
GET https://clue.ad/v1/serve?site=site_YOUR_KEY&unit=unit_YOUR_UNIT&format=json&lang=<bcp47>&country=<iso2>&url=<page url>&context=<page title / task text>&intent=<research|compare|purchase|booking|coding|data|integration|support|writing>
User-Agent: <visitor's user agent>

# Response (200): {"sponsored":true,"disclosure":"…","clues":[…]}  — empty clues for humans
# Formats: json | markdown | text | html | llms | mcp   ·   Test: &test=1

# Add to your llms.txt (agents that read llms.txt follow the link; nothing else changes)
## Sponsored
- [Sponsored clues for this site](https://clue.ad/v1/serve?site=site_YOUR_KEY&unit=unit_YOUR_UNIT&format=llms)

# Or fetch and inline the lines server-side when generating llms.txt:
curl -s "https://clue.ad/v1/serve?site=site_YOUR_KEY&unit=unit_YOUR_UNIT&format=llms&lang=en"

// Inside your own MCP server: append clue's result to relevant tool responses.
const r = await fetch('https://clue.ad/v1/serve?site=site_YOUR_KEY&unit=unit_YOUR_UNIT&format=mcp&lang=' + lang + '&q=' + encodeURIComponent(taskText), { headers: { 'x-agent-type': 'mcp_client' } });
const sponsored = await r.json(); // { sponsored: true, disclosure, clues: [...] }
return { content: [{ type: 'text', text: JSON.stringify({ result, sponsored }) }] };

// Agent developers: ask clue directly from your agent loop (you are the publisher and earn 65%).
const r = await fetch('https://clue.ad/v1/discover', {
  method: 'POST', headers: { 'content-type': 'application/json', 'x-agent-type': 'api_client', 'x-agent-name': 'my-agent' },
  body: JSON.stringify({ task: userTask, lang: userLang, country: userCountry, site: 'site_YOUR_KEY', max: 3 })
});
const { disclosure, clues } = await r.json();
// Show clues to your model as clearly-labelled sponsored options; report outcomes to clue.outcome_url.

Controls

Skip clues that would earn you less than this per 1,000 served. Leave at 0 for no floor. Returned when no paid clue matches. JSON with title, summary and url. Never billed, never paid. Append &test=1 to any request to receive a clearly labelled test clue that is never billed and never paid.

Categories

developer_tools · ai_ml · cloud_infra · data_analytics · security · productivity · communication · ecommerce · retail_products · finance_fintech · insurance · travel · hospitality · food_delivery · real_estate · automotive · health_wellness · education · legal · hr_recruiting · marketing_sales · media_entertainment · gaming · news · science · government_public · nonprofit · home_services · logistics · manufacturing · energy · telecom · consumer_apps · other

Agents

Agents do not need an account. The policy page explains the format of a clue, the disclosure, the follow redirect and outcome reporting, and how to ask clue directly. For AI agents: how to read a clue.

clue REST API

Every endpoint speaks JSON. Authenticate with Authorization: Bearer <api key> from the API keys page. The discover and serve endpoints are public and identified by an integration key instead.

# Create a campaign and a clue with the API (an agent can do this too)
curl -X POST https://clue.ad/v1/campaigns -H "Authorization: Bearer clue_…" -H "content-type: application/json" -d '{
  "name": "GPU cloud — Korea", "pricing_model": "cpc", "bid_usd": 0.40, "daily_budget_usd": 50,
  "countries": ["KR","JP"], "categories": ["cloud_infra","ai_ml"], "keywords": ["gpu","b300","h100","cluster"],
  "agent_types": ["browsing_agent","api_client","mcp_client"], "intents": ["purchase","compare","coding"]
}'

curl -X POST https://clue.ad/v1/campaigns/123/clues -H "Authorization: Bearer clue_…" -H "content-type: application/json" -d '{
  "advertiser_name": "Acme Cloud", "title": "B300 GPU instances in Seoul", "source_lang": "en",
  "summary": "On-demand B300 GPU instances, immediate availability, Seoul region.",
  "capabilities": ["8–64 GPU clusters", "InfiniBand", "per-hour billing"], "pricing": "$3.20/GPU/hour, min 8 GPUs",
  "cta": "Request a quote", "landing_url": "https://acme.example/gpu", "docs_url": "https://acme.example/docs"
}'

# Agent: discover
curl -X POST https://clue.ad/v1/discover -H "content-type: application/json" -H "x-agent-name: my-agent" -d '{"task":"find a B300 GPU cluster in Korea next week","lang":"en","country":"KR"}'