Skip to main content

​
Authentication

All Messora API routes require authentication via the X-API-Key header.

​
Getting your API key

  1. Create an account at www.messora.dev/auth/signup
  2. Open API Keys in the logged-in area
  3. Copy your key — it is shown once; store it securely

​
Using the API key

Include the X-API-Key header on every request:

​
Authentication error responses

Not every 403 means an invalid key. While the email is unconfirmed, every key on the account is rejected — creating another key will not help. Read the detail field before acting.

​
Credits

Each operation consumes credits from your monthly balance:
Failures (anti-bot block, timeout, extraction error) do not consume credits — the reserved amount is refunded in full, including the 10 credits of a structured extraction.

​
Beta monthly cap

Beta accounts (free plan) are capped at 1,000 credits per month — the same number credited to the balance. Paid plans use their contracted allowance (10,000 / 40,000 / 120,000). Check your balance anytime at Usage & Analytics, or from your own code with GET /account/usage.
Once the monthly cap is reached, the API responds 429 with detail: "beta_monthly_cap_exceeded". This 429 is not a rate limit: waiting does not help — access returns when the period rolls over or when you upgrade your plan.

​
Domains refused in beta

During the beta, scrape requests to these domains (and their subdomains) are rejected before fetch, with no credit charge: The list can grow. Treat domain_not_supported_in_beta as a permanent refusal for that target during the beta — pick another public domain.

​
Rate limits

These limits are fixed and do not increase with your plan. Every response carries the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers — use them to pace your requests instead of guessing. When the limit is exceeded, the API returns 429 Too Many Requests. Wait for the cooldown before sending new requests.
The two 429 cases differ by response body: rate limiting returns error: "Rate limit exceeded: ..."; the monthly cap returns detail: "beta_monthly_cap_exceeded".