Quarro Search API

One endpoint. Send a query, get search results fetched through a real mobile IP. All requests are HTTPS; all responses are JSON. Errors follow RFC 7807 application/problem+json.

Authentication

Pass your API key as a bearer token. Keys are shown once at creation and stored hashed — treat them like a password.

Authorization: Bearer qk_live_a1b2c3d4e5f6…

A missing, malformed, revoked, or unknown key all return the same 401 — we don't reveal which, so keys can't be enumerated.

POST /v1/search

POST https://api.quarro.dev/v1/search

curl https://api.quarro.dev/v1/search \
  -H "Authorization: Bearer qk_live_…" \
  -H "Content-Type: application/json" \
  -d '{"query":"best vector db 2026","count":10}'

Request schema

Field	Type	Required	Notes
`query`	string	yes	1–500 chars, no control characters. Trimmed.
`count`	integer	no	Results to return. Default 10, clamped to 1–50.

Body must be application/json and under 8 KB. Your query text is used for the search and then discarded — never stored or logged (we log its length only).

Response schema

200 OK:

{
  "query_echo": "best vector db 2026",
  "results": [
    { "title": "…", "url": "https://…",
      "snippet": "…", "engine": "google" }
  ],
  "meta": { "count": 10, "elapsed_ms": 812, "request_id": "g4f2a…" }
}

Error codes (RFC 7807)

Every error is application/problem+json with type, title, status, detail, instance, and a request_id for support.

{
  "type": "https://quarro.dev/errors/rate-limit-exceeded",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Per-key rate limit exceeded; retry shortly.",
  "instance": "/v1/search",
  "request_id": "g4f2a…"
}

HTTP	type	Meaning	What to do
400	`invalid-request`	Body/query failed validation (empty, >500 chars, control chars, not JSON, >8KB).	Fix the request.
401	`unauthorized`	Key missing, malformed, unknown, or revoked (indistinguishable by design).	Check the key; mint a new one if revoked.
429	`rate-limit-exceeded`	Per-key burst limit hit. Carries a `Retry-After` header (seconds).	Back off, retry after the header value.
429	`monthly-quota-exceeded`	Monthly plan quota exhausted.	Wait for reset or upgrade. No `Retry-After` (resets monthly).
502	`upstream-error`	Search backend or mobile-IP pool couldn't serve the request — includes "all nodes busy" (pool saturated, SIM-bounded).	Retry shortly with backoff.
503	`store-unavailable`	Key store temporarily unavailable — we fail closed (deny) rather than let anything through unauthenticated.	Retry shortly.

These are the only error types the API emits — they map 1:1 to the gateway's typed errors, so you can switch on type safely.

Rate limits & quota

Two independent limits apply:

Burst rate (per key, per minute) — smooths spikes; over it → 429 rate-limit-exceeded + Retry-After.
Monthly quota (per plan) — total searches/month; over it → 429 monthly-quota-exceeded.

Acceptable use

Quarro is for public, logged-off data only. You must not query authenticated/logged-in areas, harvest PII or credentials, fetch illegal content, or circumvent a target's access controls. Abuse leads to suspension and IP-range blocklisting. See the full Acceptable Use Policy, Terms, and Privacy Policy.