API-Dokumentation

Schnellstart

1. Melde dich in der Konsole an und erstelle im Tab API-Schlüssel einen API-Schlüssel. Kopiere ihn: Er wird nur einmal angezeigt.
2. Halte einen Sticky-Proxy bereit, Residential oder ISP (eine Exit-IP, die mindestens 10 Minuten bleibt).
3. Ruf POST /v1/fetch mit der URL und dem Proxy auf.

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);

Stell in deinem Client ein Timeout von etwa 70 Sekunden ein: Das Lösen einer Challenge kann ein paar Sekunden dauern, manchmal länger.

Authentifizierung

Jeder Request trägt deinen API-Schlüssel im Header Authorization:

Authorization: Bearer lpa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Schlüssel werden in der Konsole erstellt und widerrufen. Behandle sie wie Passwörter: Bewahre sie serverseitig auf, nie in einem Browser oder einem öffentlichen Repository. Ein widerrufener Schlüssel oder ein gesperrtes Konto bekommt sofort 401 invalid_key.

Eine Seite abrufen

Request-Body (JSON)

Antwort

Die API antwortet mit 200, sobald die Zielseite geantwortet hat — egal, welchen Status die Seite selbst liefert. Diesen Status liest du in 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

Anti-Bot-Cookies sind an die Browser-Identität gebunden, die sie erhalten hat: IP, Fingerprint, Cookie-Jar. Eine Session hält diese Identität für dich fest — eine einmal gelöste Challenge bleibt gelöst.

• Der erste Aufruf (mit proxy, ohne session_id) erstellt eine Session und gibt ihre session_id zurück.
• Schick diese session_id bei den nächsten Aufrufen mit: derselbe Proxy, derselbe Fingerprint, dieselben Cookies. Weitere Seiten kommen meist in wenigen hundert Millisekunden zurück, mit solved: [].
• Eine Session läuft nach 30 Minuten ohne Requests ab. Jeder Request verlängert sie.
• Eine Session behält ihren Proxy, solange sie lebt. Ein anderer proxy zusammen mit einer session_id ergibt 409 proxy_mismatch: Starte stattdessen eine neue Session.
• Ein Request gleichzeitig pro Session. Ein zweiter, paralleler Request wartet bis zu 10 Sekunden und bekommt dann 409 session_busy. Für mehr Tempo lässt du mehrere Sessions parallel laufen, jede mit eigenem 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. Zuerst die Startseite: erstellt die Session und löst die Challenge
home = fetch(url="https://www.shop.example/", proxy="http://user:pass@proxy.example:8080")

# 2. Dann die Produktseite, mit derselben Identität
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. Startseite: merk dir die session_id aus der Antwort
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. Produktseite in derselben 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

Starte eine Session mit Cookies, die du schon hast (ein Login, ein Warenkorb, eine Consent-Auswahl), oder füge später welche hinzu. Sie werden in der Session gespeichert und bei jedem folgenden Request mitgeschickt, bis die Seite sie ersetzt.

Einfache Form

Ein Objekt {"name": "value"}. Die Cookies werden für den Host der url gesetzt.

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

Ausführliche Form

Eine Liste von Objekten, um die domain (z. B. .shop.example für alle Subdomains) oder den path (Standard /) festzulegen.

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

• Bis zu 50 Cookies pro Request, 4.096 Zeichen pro Wert, kein ; und keine Zeilenumbrüche in Werten.
• Ein Cookie mit gleichem Namen, gleicher Domain und gleichem Pfad ersetzt das vorherige.
• Jede Antwort liefert die Cookies der Session in cookies zurück, damit du sie anderswo wiederverwenden kannst.
• Cookie-Werte werden nie in deine Request-Logs geschrieben.

Fehler

Fehler haben einen Status ungleich 200 und immer dieselbe Form. Wenn eine Session existiert, ist ihre session_id enthalten.

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

Limits

Verbrauch, gelöste Challenges und deine letzten Requests findest du in der Konsole.

Weitere Endpoints

Die in diesem Monat verbrauchten Requests, dein Kontingent und die tägliche Aufschlüsselung der letzten 30 Tage (Requests, Erfolge, Fehler, Bytes, Lösungen pro Schutzmechanismus).

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

Schließt eine Session sofort (sonst läuft sie von selbst ab). Gibt {"deleted": true} zurück, oder 404, wenn sie nicht mehr existiert.

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

Best Practices

• Nur Sticky-Proxys. Ein rotierender Proxy wechselt die IP zwischen Requests und macht die gerade erhaltenen Cookies ungültig. Plane Sessions von 10 Minuten oder mehr ein.
• Eine Session pro Identität. Nutze sie für alle Seiten eines Ablaufs; öffne zum Skalieren mehr Sessions (mit mehr Proxys).
• Surf natürlich. Lade zuerst die Start- oder Kategorieseite, dann die Produktseite mit einem Referer-Header. Direkte Aufrufe tiefer Seiten werden häufiger markiert.
• Hämmer nicht auf eine Session ein. Löse die Challenge mit einem Request und mach dann weiter; vermeide Bursts von derselben IP.
• Bei proxy_blocked leg die Session und ihren Proxy eine Weile beiseite; eine verbrannte IP bleibt verbrannt.
• Respektiere die Seiten, die du aufrufst. Du bist dafür verantwortlich, ihre Nutzungsbedingungen und die für dich geltenden Gesetze einzuhalten.