API Crawlers

1. Vue d'ensemble

L'API Crawlers expose chaque fonctionnalité de la plateforme en endpoint individuel, via un dispatcher unique. Vous postez { feature, input } sur /v1/jobs, vous récupérez un job_id, puis vous interrogez /v1/jobs/{id} jusqu'à status = "succeeded".

Pour le pipeline éditorial complet (publication CMS), voir l'API Périclès. Pour la génération de rapports B2B en marque blanche, voir l'API Marina.

2. Authentification

Toutes les requêtes (sauf /v1/features et /health) requièrent une clé API personnelle au format crw_live_…. La clé est stockée côté Crawlers sous forme de hash SHA-256 ; elle n'est affichée qu'une seule fois à sa création.

Deux modes équivalents :

Authorization: Bearer crw_live_xxxxxxxxxxxxxxxxxxxxxxxx
# ou
x-crawlers-key: crw_live_xxxxxxxxxxxxxxxxxxxxxxxx

Création depuis votre compte → onglet API. La clé peut être révoquée à tout moment.

3. Cycle de vie d'un job

1. POST /v1/jobs → 202 Accepted, statut queued.
2. Le worker passe le job en running dans la seconde qui suit.
3. Vous polliez GET /v1/jobs/{id} toutes les 2–10 s (selon module).
4. Statut final : succeeded (champ result rempli) ou failed (champ error).
5. Un job peut être annulé avec POST /v1/jobs/{id}/cancel tant qu'il n'est pas terminé.

4. Endpoints

curl https://tutlimtasnjabdfhpewu.functions.supabase.co/crawlers-api/v1/features

curl -X POST https://tutlimtasnjabdfhpewu.functions.supabase.co/crawlers-api/v1/jobs \
  -H "Authorization: Bearer crw_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "feature": "geo_score",
    "input": { "url": "https://example.com/blog/article" }
  }'

{
  "id": "5d6e7f12-...-9a0b",
  "feature": "geo_score",
  "status": "queued",
  "created_at": "2026-05-26T10:00:00Z",
  "cost_cents": 10,
  "poll_url": "/v1/jobs/5d6e7f12-...-9a0b"
}

// JSON malformé
{ "error": "invalid_json" }

// feature absent
{ "error": "missing_field", "field": "feature" }

// feature inconnue
{ "error": "unknown_feature", "feature": "foo", "see": "/v1/features" }

// input n'est pas un objet
{ "error": "invalid_input", "expected": "object" }

// Aucune clé fournie
{ "error": "missing_api_key", "docs": "/docs/api/crawlers#authentication" }

// Clé inconnue, révoquée ou mal formée
{ "error": "invalid_api_key", "docs": "/docs/api/crawlers#authentication" }

{
  "error": "insufficient_balance",
  "message": "Recharge ton wallet sur /developers/profil?tab=facturation",
  "job_id": "5d6e7f12-...-9a0b"
}

// Erreur base de données (insert job)
{ "error": "db_error", "detail": "<message Postgres>" }

// Exception non gérée dans le router
{ "error": "internal_error", "message": "<message>" }

{
  "id": "5d6e7f12-...-9a0b",
  "feature": "geo_score",
  "status": "succeeded",
  "input": { "url": "https://example.com/blog/article" },
  "result": {
    "score": 78,
    "breakdown": { "machine_readability": 82, "fan_out": 71, "citation": 80 }
  },
  "error": null,
  "created_at": "2026-05-26T10:00:00Z",
  "started_at": "2026-05-26T10:00:01Z",
  "completed_at": "2026-05-26T10:00:42Z"
}

5. Catalogue des 18 modules

Chaque module est appelé via { "feature": "<id>", "input": { … } }.

6. Codes d'erreur

7. Exemples

Node.js (fetch natif)

const KEY = process.env.CRAWLERS_API_KEY;
const BASE = "https://tutlimtasnjabdfhpewu.functions.supabase.co/crawlers-api/v1";

async function run(feature, input) {
  // 1. créer le job
  const r = await fetch(`${BASE}/jobs`, {
    method: "POST",
    headers: { "Authorization": `Bearer ${KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ feature, input }),
  });
  const { id } = await r.json();

  // 2. polling
  while (true) {
    await new Promise(r => setTimeout(r, 3000));
    const s = await fetch(`${BASE}/jobs/${id}`, { headers: { "Authorization": `Bearer ${KEY}` } });
    const job = await s.json();
    if (job.status === "succeeded") return job.result;
    if (job.status === "failed")    throw new Error(JSON.stringify(job.error));
  }
}

const score = await run("geo_score", { url: "https://example.com/blog/article" });
console.log(score);

PHP (cURL)

<?php
$KEY = getenv('CRAWLERS_API_KEY');
$BASE = 'https://tutlimtasnjabdfhpewu.functions.supabase.co/crawlers-api/v1';

function crawlers_run($feature, $input) {
  global $KEY, $BASE;
  $ch = curl_init("$BASE/jobs");
  curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer $KEY", "Content-Type: application/json"],
    CURLOPT_POSTFIELDS => json_encode(["feature" => $feature, "input" => $input]),
  ]);
  $job = json_decode(curl_exec($ch), true); curl_close($ch);

  while (true) {
    sleep(3);
    $ch = curl_init("$BASE/jobs/{$job['id']}");
    curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ["Authorization: Bearer $KEY"]]);
    $r = json_decode(curl_exec($ch), true); curl_close($ch);
    if ($r['status'] === 'succeeded') return $r['result'];
    if ($r['status'] === 'failed')    throw new RuntimeException(json_encode($r['error']));
  }
}

Python (requests)

import os, time, requests

KEY = os.environ["CRAWLERS_API_KEY"]
BASE = "https://tutlimtasnjabdfhpewu.functions.supabase.co/crawlers-api/v1"
H = {"Authorization": f"Bearer {KEY}"}

def run(feature, input):
    r = requests.post(f"{BASE}/jobs", headers={**H, "Content-Type": "application/json"},
                      json={"feature": feature, "input": input})
    job_id = r.json()["id"]
    while True:
        time.sleep(3)
        job = requests.get(f"{BASE}/jobs/{job_id}", headers=H).json()
        if job["status"] == "succeeded": return job["result"]
        if job["status"] == "failed":    raise RuntimeError(job["error"])

print(run("geo_score", {"url": "https://example.com/blog/article"}))

8. Quotas & limites

• Free : 20 jobs / jour, 1 job concurrent.
• Premium : 500 jobs / jour, 3 jobs concurrents.
• Pro Agency : 5 000 jobs / jour, 10 jobs concurrents.
• Pro Agency Premium : 25 000 jobs / jour, 30 jobs concurrents.

Les dépassements renvoient 429 avec un en-tête Retry-After (secondes).