Documentation de l'API

Démarrage rapide

1. Connectez-vous à la console et créez une clé d'API dans l'onglet Clés d'API. Copiez-la : elle n'est affichée qu'une seule fois.
2. Prévoyez un proxy résidentiel ou ISP sticky (une même IP de sortie conservée au moins 10 minutes).
3. Appelez POST /v1/fetch avec l'URL et le proxy.

curl -X POST https://orpheus-api.lapetiteagora.fr/v1/fetch \
  -H "Authorization: Bearer $LPA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.example.com/",
    "proxy": "http://user:pass@proxy.example:8080"
  }'

import os, requests

resp = requests.post(
    "https://orpheus-api.lapetiteagora.fr/v1/fetch",
    headers={"Authorization": f"Bearer {os.environ['LPA_KEY']}"},
    json={
        "url": "https://www.example.com/",
        "proxy": "http://user:pass@proxy.example:8080",
    },
    timeout=70,
)
page = resp.json()
print(page["status"], page["solved"], page["session_id"])

const resp = await fetch("https://orpheus-api.lapetiteagora.fr/v1/fetch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LPA_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://www.example.com/",
    proxy: "http://user:pass@proxy.example:8080",
  }),
});
const page = await resp.json();
console.log(page.status, page.solved, page.session_id);

Réglez le timeout de votre client à 70 secondes environ : franchir un challenge peut prendre quelques secondes, parfois plus.

Authentification

Chaque requête porte votre clé d'API dans le header Authorization :

Authorization: Bearer lpa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Les clés se créent et se révoquent dans la console. Traitez-les comme des mots de passe : gardez-les côté serveur, jamais dans un navigateur ni dans un dépôt public. Une clé révoquée, ou un compte suspendu, reçoit immédiatement 401 invalid_key.

Récupérer une page

Corps de la requête (JSON)

Réponse

L'API répond 200 dès que le site cible a répondu — quel que soit le statut renvoyé par le site. Lisez ce statut dans status.

{
  "status": 200,
  "headers": { "content-type": ["text/html; charset=utf-8"] },
  "body": "<!doctype html>…",
  "encoding": "text",
  "url": "https://www.example.com/",
  "session_id": "s_Ij4oudr1bYPzUA8U3sdlACAf",
  "solved": ["datadome"],
  "cookies": [{ "name": "datadome", "value": "…", "domain": ".example.com", "path": "/" }],
  "elapsed_ms": 2343
}

Sessions

Les cookies anti-bot sont liés à l'identité de navigateur qui les a obtenus : IP, empreinte, jar de cookies. Une session conserve cette identité pour vous : un challenge franchi une fois le reste.

• Le premier appel (avec un proxy, sans session_id) crée une session et renvoie son session_id.
• Renvoyez ce session_id aux appels suivants : même proxy, même empreinte, mêmes cookies. Les pages suivantes reviennent généralement en quelques centaines de millisecondes, avec solved: [].
• Une session expire après 30 minutes sans requête. Chaque requête la prolonge.
• Une session garde son proxy jusqu'au bout. Envoyer un autre proxy avec un session_id renvoie 409 proxy_mismatch : démarrez plutôt une nouvelle session.
• Une requête à la fois par session. Une deuxième requête simultanée attend jusqu'à 10 secondes, puis reçoit 409 session_busy. Pour aller plus vite, lancez plusieurs sessions en parallèle, chacune avec son propre proxy.

import os, requests

API = "https://orpheus-api.lapetiteagora.fr/v1/fetch"
HEADERS = {"Authorization": f"Bearer {os.environ['LPA_KEY']}"}

def fetch(**payload):
    r = requests.post(API, headers=HEADERS, json=payload, timeout=70)
    data = r.json()
    if r.status_code != 200:
        raise RuntimeError(data["error"])
    return data

# 1. D'abord la page d'accueil : crée la session et franchit le challenge
home = fetch(url="https://www.shop.example/", proxy="http://user:pass@proxy.example:8080")

# 2. Puis la page produit, avec la même identité
product = fetch(
    url="https://www.shop.example/product/42",
    session_id=home["session_id"],
    headers={"Referer": "https://www.shop.example/"},
)
print(product["status"], product["solved"])

# 1. Page d'accueil : notez le session_id de la réponse
curl -s -X POST https://orpheus-api.lapetiteagora.fr/v1/fetch \
  -H "Authorization: Bearer $LPA_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.shop.example/","proxy":"http://user:pass@proxy.example:8080"}'

# 2. Page produit sur la même session
curl -s -X POST https://orpheus-api.lapetiteagora.fr/v1/fetch \
  -H "Authorization: Bearer $LPA_KEY" -H "Content-Type: application/json" \
  -d '{"url":"https://www.shop.example/product/42","session_id":"s_…",
       "headers":{"Referer":"https://www.shop.example/"}}'

Cookies

Démarrez une session avec des cookies que vous avez déjà (une connexion, un panier, un choix de consentement), ou ajoutez-en plus tard. Ils sont stockés dans la session et envoyés à chaque requête suivante, jusqu'à ce que le site les remplace.

Forme simple

Un objet {"name": "value"}. Les cookies sont posés sur l'hôte de l'url.

{
  "url": "https://www.shop.example/cart",
  "proxy": "http://user:pass@proxy.example:8080",
  "cookies": { "cart_id": "42", "lang": "fr" }
}

Forme détaillée

Une liste d'objets, pour choisir le domain (par ex. .shop.example pour tous les sous-domaines) ou le path (par défaut /).

{
  "url": "https://www.shop.example/",
  "session_id": "s_…",
  "cookies": [
    { "name": "auth", "value": "eyJ…", "domain": ".shop.example", "path": "/" }
  ]
}

• Jusqu'à 50 cookies par requête, 4 096 caractères par valeur, sans ; ni retour à la ligne dans les valeurs.
• Un cookie de même nom, domaine et chemin remplace le précédent.
• Chaque réponse renvoie les cookies de la session dans cookies, pour que vous puissiez les réutiliser ailleurs.
• Les valeurs des cookies ne sont jamais écrites dans votre journal des requêtes.

Erreurs

Les erreurs ont un statut différent de 200 et toutes la même forme. Quand une session existe, son session_id est inclus.

{
  "error": { "code": "proxy_blocked", "message": "…" },
  "session_id": "s_…"
}

Limites

Consommation, challenges franchis et dernières requêtes sont dans la console.

Autres endpoints

Requêtes consommées ce mois-ci, votre quota et le détail jour par jour des 30 derniers jours (requêtes, succès, erreurs, octets, franchissements par protection).

curl -s https://orpheus-api.lapetiteagora.fr/v1/usage -H "Authorization: Bearer $LPA_KEY"

Ferme une session immédiatement (sinon elle expire d'elle-même). Renvoie {"deleted": true}, ou 404 si elle n'existe plus.

curl -s -X DELETE https://orpheus-api.lapetiteagora.fr/v1/sessions/s_… -H "Authorization: Bearer $LPA_KEY"

Bonnes pratiques

• Uniquement des proxies sticky. Un proxy rotatif change d'IP entre deux requêtes et invalide les cookies que vous venez d'obtenir. Visez des sessions de 10 minutes ou plus.
• Une session par identité. Réutilisez-la pour toutes les pages d'un même parcours ; ouvrez plus de sessions (avec plus de proxies) pour monter en charge.
• Naviguez naturellement. Chargez d'abord la page d'accueil ou de catégorie, puis la page produit avec un header Referer. Les accès directs à des pages profondes sont plus souvent signalés.
• Ne martelez pas une session. Franchissez le challenge avec une requête, puis continuez ; évitez les rafales depuis la même IP.
• Sur proxy_blocked, abandonnez la session et son proxy pendant un moment ; une IP grillée reste grillée.
• Respectez les sites que vous consultez. Il vous revient de respecter leurs conditions d'utilisation et les lois qui s'appliquent à vous.