Référence API v1

Base URL : https://votre-domaine/api/v1. Toutes les requêtes sont en JSON.

Authentification

Créez une clé dans le tableau de bord puis envoyez-la dans l'en-tête :

Authorization: Bearer amy-xxxxxxxxxxxxxxxxxxxxxxxx

Crédits & codes d'erreur

Chaque réponse indique creditsUsed. Solde et usage : GET /api/v1/me.

400	Paramètre manquant ou URL invalide
401	Clé API absente, invalide ou révoquée
402	Crédits insuffisants
403	Accès interdit par le robots.txt du site
404	Job introuvable
422	Paramètres invalides (détails dans details)
503	Fournisseur LLM non configuré (extract / json)

POST/api/v1/scrape

Scrape — une page

Coût : 1 crédit (+4 pour json, +1 pour screenshot / rendu JS)

Paramètre	Type	Description
url	string, requis	URL http(s) de la page
formats	string[]	markdown (défaut), html, rawHtml, text, links, images, metadata, screenshot, json
onlyMainContent	boolean	Isoler le contenu principal (défaut : true)
includeTags / excludeTags	string[]	Sélecteurs CSS à conserver / retirer
headers	object	En-têtes HTTP personnalisés
waitFor	number	Attente en ms après chargement (rendu JS)
mobile	boolean	Viewport mobile (rendu JS)
actions	Action[]	wait, click, write, scroll, screenshot (rendu JS)
jsonOptions	{ schema?, prompt?, systemPrompt? }	Paramètres de l'extraction IA quand formats contient json

Requête

{
  "url": "https://exemple.sn/article",
  "formats": ["markdown", "links"],
  "onlyMainContent": true
}

Réponse

{
  "success": true,
  "data": {
    "markdown": "# Titre...",
    "links": ["https://..."],
    "metadata": { "title": "...", "description": "...", "language": "fr", "sourceURL": "...", "statusCode": 200 }
  },
  "creditsUsed": 1,
  "durationMs": 812
}

POST/api/v1/batch

Batch — jusqu'à 25 pages

Coût : coût du scrape × nombre d'URL

Paramètre	Type	Description
urls	string[], requis	Jusqu'à 25 URL
…		Toutes les options de /scrape

Requête

{ "urls": ["https://a.sn", "https://b.sn"], "formats": ["markdown"] }

Réponse

{ "success": true, "data": [ { "markdown": "...", "metadata": {...} }, ... ] }

POST/api/v1/crawl

Crawl — un site entier (asynchrone)

Coût : coût du scrape par page crawlée

Paramètre	Type	Description
url	string, requis	Point de départ
limit	number	Pages max (défaut 50, max 5000)
maxDepth	number	Profondeur max (défaut 5)
includePaths / excludePaths	string[]	Regex ou préfixes de chemins
allowSubdomains	boolean	Suivre les sous-domaines
allowExternalLinks	boolean	Suivre les liens externes
ignoreSitemap	boolean	Ne pas lire sitemap.xml
concurrency	number	1–10 (défaut 4)
delay	number	Pause en ms entre pages
scrapeOptions	object	Options de /scrape appliquées à chaque page

Requête

{ "url": "https://exemple.sn", "limit": 100, "maxDepth": 3, "excludePaths": ["^/tag/"] }

Réponse

{ "success": true, "id": "crawl_…", "url": "https://…/api/v1/crawl/crawl_…" }

GET /api/v1/crawl/{id}   → { "status": "scraping|completed|failed|cancelled", "completed": 12, "total": 100, "data": [ ... ] }
DELETE /api/v1/crawl/{id} → annule le job

POST/api/v1/map

Map — toutes les URL d'un site

Coût : 1 crédit

Paramètre	Type	Description
url	string, requis	Domaine ou page
search	string	Mots-clés pour filtrer et classer les URL
limit	number	Max (défaut 5000)
includeSubdomains	boolean
ignoreSitemap / sitemapOnly	boolean

Requête

{ "url": "https://exemple.sn", "search": "contact" }

Réponse

{ "success": true, "links": ["https://exemple.sn/contact", ...], "count": 1, "sources": { "sitemap": 120, "html": 34 } }

POST/api/v1/search

Search — recherche web (+ scrape)

Coût : 2 crédits + coût du scrape × résultats si scrapeOptions

Paramètre	Type	Description
query	string, requis	Requête
limit	number	1–50 (défaut 5)
lang / country	string	fr / sn par défaut
tbs	string	qdr:d, qdr:w, qdr:m (fraîcheur)
scrapeOptions	object	Si présent, chaque résultat est scrapé

Requête

{ "query": "appel d'offres BTP Sénégal", "limit": 5, "scrapeOptions": { "formats": ["markdown"] } }

Réponse

{ "success": true, "provider": "duckduckgo|serper|brave", "data": [ { "url": "...", "title": "...", "description": "...", "markdown": "..." } ] }

POST/api/v1/extract

Extract — données structurées par IA (asynchrone)

Coût : 5 crédits + 2 par page analysée

Paramètre	Type	Description
urls	string[], requis	Pages, ou « https://site.sn/* » pour un site entier
prompt	string	Ce qu'il faut extraire, en langage naturel
schema	JSON Schema	Structure attendue du résultat
maxPagesPerSite	number	Pages max par motif /* (défaut 10)

Requête

{
  "urls": ["https://agence-immo.sn/biens/*"],
  "prompt": "Liste les biens avec nom, quartier, prix en FCFA et surface",
  "schema": { "type": "object", "properties": { "biens": { "type": "array", "items": { "type": "object",
    "properties": { "nom": {"type":"string"}, "quartier": {"type":"string"}, "prix": {"type":"number"}, "surface": {"type":"number"} } } } } }
}

Réponse

{ "success": true, "id": "extract_…" }

GET /api/v1/extract/{id} → { "status": "completed", "data": { "biens": [ ... ] }, "sources": [ ... ] }

Exemples de code

JavaScript / TypeScript

const res = await fetch("https://votre-domaine/api/v1/scrape", {
  method: "POST",
  headers: { "Content-Type": "application/json", Authorization: "Bearer amy-VOTRE_CLE" },
  body: JSON.stringify({ url: "https://exemple.sn", formats: ["markdown"] }),
});
const { data } = await res.json();
console.log(data.markdown);

Python

import requests, time

API = "https://votre-domaine/api/v1"
H = {"Authorization": "Bearer amy-VOTRE_CLE"}

job = requests.post(f"{API}/crawl", json={"url": "https://exemple.sn", "limit": 50}, headers=H).json()
while True:
    r = requests.get(f"{API}/crawl/{job['id']}", headers=H).json()
    if r["status"] in ("completed", "failed", "cancelled"):
        break
    time.sleep(2)
for page in r["data"]:
    print(page["metadata"]["sourceURL"], len(page.get("markdown", "")))