Skip to main content

Documentation Index

Fetch the complete documentation index at: https://brezelscraper.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Use API keys for server-to-server access. Use your dashboard session for browser-driven flows.

​
Create an API key

Create API keys in the dashboard under Integrations. Important behavior:
  • Keys always start with bscraper_
  • The full secret is shown exactly once when you create it
  • You can keep up to 10 active keys per user
  • Revoked keys stay in the list for audit visibility, but they stop working immediately

​
Send an authentication header

You can authenticate with either header:
HeaderExample
AuthorizationAuthorization: Bearer bscraper_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
X-API-KeyX-API-Key: bscraper_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Both methods are equivalent.

​
Example request

curl https://api.brezelscraper.com/api/v1/jobs \
  -H "Authorization: Bearer bscraper_your_key_here"

​
Session auth vs API keys

  • The dashboard uses your signed-in session cookie.
  • API keys are the right choice for backend jobs, scripts, and external automations.
  • The Google OAuth callback endpoint relies on a browser session and is not designed for direct server-to-server calls.

​
Rate limits

The API router applies different limits based on the authenticated context:
Auth contextSustained rateBurst
Free API key2 req/s5
Paid API key10 req/s30
Dashboard session5 req/s20
POST /api/v1/jobs has a tighter per-user limiter on top of the global rate limit:
  • Sustained rate: 1 req/s
  • Burst: 3

​
Idempotency for POST /api/v1/jobs

Job creation is billable. If your client retries blindly after a timeout, you can create duplicate jobs and duplicate charges. Send an Idempotency-Key header on POST /api/v1/jobs to make retries safe: 
curl -X POST https://api.brezelscraper.com/api/v1/jobs \
  -H "Authorization: Bearer bscraper_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5a2c6b7e-3f9d-4f4f-9e1e-1d3b0a8c1c2e" \
  -d '{
    "name": "Berlin cafes",
    "keywords": ["cafes in berlin"],
    "lang": "en"
  }'
Current behavior:
  • Replay window: 24 hours
  • Same key and same request body: returns the cached response, with Idempotent-Replayed: true
  • Same key and different request body: returns 409 Conflict with idempotency_key_in_use_with_different_body
  • Same key while the first request is still running: returns 409 Conflict with idempotency_key_in_use and Retry-After: 1
  • Maximum key length: 255 bytes

​
Common error shape

Most failures return the same JSON envelope: 
{
  "code": 401,
  "message": "User not authenticated"
}
Common statuses:
  • 401 for missing or invalid authentication
  • 400 for validation or query parameter errors
  • 409 for idempotency conflicts
  • 422 for invalid JSON or invalid UUID path values
  • 429 for rate limiting or concurrent job limits