API documentation

Quick start

1. Sign in to the console and create an API key in the API keys tab. Copy it: it is shown only once.
2. Have a sticky residential or ISP proxy ready (one exit IP kept for at least 10 minutes).
3. Call POST /v1/fetch with the URL and the 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);

Set a client timeout of about 70 seconds: clearing a challenge can take a few seconds, sometimes more.

Authentication

Every request carries your API key in the Authorization header:

Authorization: Bearer lpa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are created and revoked in the console. Treat them like passwords: keep them server-side, never in a browser or a public repository. A revoked key, or a suspended account, gets 401 invalid_key immediately.

Fetch a page

Request body (JSON)

Response

The API answers 200 as soon as the target site answered — whatever the site's own status. Read the site's status 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 are bound to the browser identity that obtained them: IP, fingerprint, cookie jar. A session keeps that identity for you, so a challenge cleared once stays cleared.

• The first call (with a proxy, without session_id) creates a session and returns its session_id.
• Send that session_id on the next calls: same proxy, same fingerprint, same cookies. Later pages usually come back in a few hundred milliseconds, with solved: [].
• A session expires after 30 minutes without requests. Each request extends it.
• A session keeps its proxy for life. Sending a different proxy with a session_id returns 409 proxy_mismatch: start a new session instead.
• One request at a time per session. A second concurrent request waits up to 10 seconds, then gets 409 session_busy. To go faster, run several sessions in parallel, each with its own 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. Home page first: creates the session and clears the challenge
home = fetch(url="https://www.shop.example/", proxy="http://user:pass@proxy.example:8080")

# 2. Then the product page, on the same identity
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. Home page: note the session_id in the response
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. Product page on the same 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

Start a session with cookies you already have (a login, a cart, a consent choice), or add some later. They are stored in the session and sent on every following request until the site replaces them.

Simple form

An object {"name": "value"}. Cookies are set on the host of the url.

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

Detailed form

A list of objects, to choose the domain (e.g. .shop.example for every subdomain) or the path (default /).

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

• Up to 50 cookies per request, 4,096 characters per value, no ; or line breaks in values.
• A cookie with the same name, domain and path replaces the previous one.
• Every response returns the session's cookies in cookies, so you can reuse them elsewhere.
• Cookie values are never written to your request logs.

Errors

Errors use a non-200 status and the same shape. When a session exists, its session_id is included.

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

Limits

Usage, solved challenges and your last requests are in the console.

Other endpoints

Requests used this month, your quota, and the daily breakdown for the last 30 days (requests, successes, errors, bytes, solves by protection).

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

Closes a session right away (otherwise it expires on its own). Returns {"deleted": true}, or 404 if it no longer exists.

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

Best practices

• Sticky proxies only. A rotating proxy changes IP between requests and invalidates the cookies you just obtained. Aim for sessions of 10 minutes or more.
• One session per identity. Reuse it for every page of a flow; open more sessions (with more proxies) to scale.
• Browse naturally. Load the home or category page first, then the product page with a Referer header. Direct hits on deep pages get flagged more often.
• Don't hammer one session. Clear the challenge with one request, then go on; avoid bursts from the same IP.
• On proxy_blocked, drop the session and its proxy for a while; a burned IP stays burned.
• Respect the sites you access. You are responsible for following their terms and the laws that apply to you.