Documentation

Annonceurs

Un compte annonceur détient un solde prépayé, des campagnes et des clues. Une campagne définit le modèle de tarification, les enchères, les budgets et les règles de mise en correspondance. Un clue est l'enregistrement que les agents reçoivent. Tout ce qui suit peut également être réalisé à l'aide d'une clé API.

1. Alimentez votre solde. Le premier rechargement est de $50 ou plus, par carte via Stripe.
2. Créez une campagne : choisissez CPC, CPA ou CPM, définissez une enchère maximale et des budgets, et déterminez quand la campagne doit être prise en compte.
3. Rédigez un indice dans votre propre langue. clue l'examine par rapport à sa politique en environ une minute et le traduit en 20 langues.

Règles de correspondance

Laisser vide pour le monde entier. Le pays provient de l'emplacement réseau de l'agent ou des informations fournies par le site. La langue demandée par l'agent. Laissez vide pour n'importe quelle langue. Votre indice est traduit automatiquement, cela limite donc uniquement l'endroit où vous diffusez. Mis en correspondance avec les catégories déclarées du site et le contexte de la page ou de la tâche sur laquelle l'agent travaille. Laissez vide pour tous les types. Les robots d'entraînement agissent rarement sur un clue ; les agents de navigation, les clients API et les clients MCP le font généralement. Ce que l'agent essaye de faire. Déclaré par le site ou l'agent, ou déduit du contexte. Laisser vide pour toutes les intentions. Entreprises, consommateurs ou tout le monde. clue n'associe jamais de clues à des utilisateurs de moins de 18 ans.

Suivi des résultats

Lorsqu'un agent suit un clue, nous l'envoyons vers votre URL de destination avec ?clue_id=<id>. Lorsque cette visite aboutit à une inscription, un achat, une réservation ou un appel API, faites un POST de l'id vers clue. Les campagnes CPA sont facturées à ce moment-là ; les campagnes CPC et CPM enregistrent simplement l'action dans vos rapports.

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"}

Éditeurs et développeurs d'agents

Un site est un site Web, une API, un serveur MCP ou un agent dont vous êtes propriétaire. Chaque site possède une clé, un ou plusieurs emplacements (un emplacement fixe le format et le style de la réponse), des contrôles et des analyses. Vérifiez la propriété une seule fois et commencez à gagner de l'argent.

1. Enregistrez votre site Web, API, serveur MCP ou agent et vérifiez la propriété avec une balise meta ou un fichier.
2. Créez un emplacement et choisissez le format pris en charge par l'interface : JSON, Markdown, texte, HTML, llms.txt ou MCP.
3. Installez la balise, le middleware ou l'appel API. Les analyses des agents commencent dès la toute première requête, avant même qu'un indice ne corresponde.

Les intégrations côté serveur détectent les agents via le User-Agent et les en-têtes, demandent une correspondance à clue, puis ajoutent le bloc au format HTML, Markdown ou JSON avant que la réponse ne quitte votre serveur. Les visiteurs humains reçoivent la réponse intacte.

<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.

Contrôles

Ignorez les indices qui vous rapporteraient moins que cela par 1 000 diffusions. Laissez à 0 pour aucun plancher. Renvoyé lorsqu'aucun indice payant ne correspond. JSON avec titre, résumé et URL. Jamais facturé, jamais payé. Ajoutez &test=1 à n'importe quelle requête pour recevoir un indice de test clairement identifié qui ne sera jamais facturé ni payé.

Catégories

Agents

Les agents n'ont pas besoin de compte. La page de politique explique le format d'un clue, la divulgation, la redirection de suivi et le rapport de résultats, ainsi que la manière d'interroger clue directement. Pour les agents IA : comment lire un clue.

clue REST API

Chaque point de terminaison communique en JSON. Authentifiez-vous avec Authorization: Bearer <api key> depuis la page des clés API. Les points de terminaison discover et serve sont publics et identifiés par une clé de site à la place.

# 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"}'