API Overview¶

fetchly exposes a JSON HTTP API. It is the same API the web UI uses — there is no separate surface and no second authentication scheme.

Base URL¶

https://fetchly.example.com

Routes are absolute; there is no shared /api prefix for every family (/download/{id} and /share/{token} sit at the root).

Authentication¶

The API uses the session cookie, exactly like the browser. There is no API token and no bearer scheme. See API Authentication.

When authentication is disabled, every endpoint is open.

OpenAPI¶

The app is built on FastAPI, so the generated schema is available at the framework defaults:

https://fetchly.example.com/docs           # Swagger UI
https://fetchly.example.com/redoc          # ReDoc
https://fetchly.example.com/openapi.json   # Raw schema

Endpoint families¶

The full list is in Endpoints.

Content types¶

CSRF¶

/login, /logout, and every state-changing route under /api/* are CSRF-protected with a double-submit cookie (fetchly_csrf) — not just /api/submit. Send the token back either in the X-CSRF-Token header or, for form bodies, as a csrf_token field. A mismatch returns 403. Safe methods (GET, HEAD, OPTIONS) are never checked.

Status codes¶

Errors are FastAPI's shape:

{"detail": "Invalid type. Allowed: audio, video"}

Rate limits¶

Every route is limited per client IP. See Rate Limiting.

Example session¶

BASE=https://fetchly.example.com
JAR=$(mktemp)

# 1. Fetch the login page: sets the CSRF cookie and embeds the anti-bot token
curl -sc "$JAR" "$BASE/login" -o /tmp/login.html
CSRF=$(awk '$6=="fetchly_csrf"{print $7}' "$JAR")
CAPTCHA=$(grep -oP 'name="captcha_token"[^>]*value="\K[^"]+' /tmp/login.html)

# 2. Log in. POST /login takes JSON; wait ~1 s, because a submission that
#    arrives faster than that trips the time trap.
sleep 1
curl -sb "$JAR" -c "$JAR" -X POST "$BASE/login" \
  -H "Content-Type: application/json" \
  -H "X-CSRF-Token: $CSRF" \
  -d "{\"username\":\"admin\",\"password\":\"...\",\"captcha_token\":\"$CAPTCHA\",\"honeypot\":\"\"}"

# 3. Use the session
curl -sb "$JAR" "$BASE/api/jobs?limit=10"

# 4. Submit a download (form-encoded, CSRF-protected)
curl -sb "$JAR" -X POST "$BASE/api/submit" \
  -H "X-CSRF-Token: $CSRF" \
  -d "url=https://www.youtube.com/watch?v=..." \
  -d "type=audio" -d "quality=max"

Live updates¶

Prefer SSE over polling:

curl -Nb "$JAR" "$BASE/events"

The stream emits job state changes plus a keep-alive every 5 seconds. Buffering proxies break it — see Reverse Proxy.