The Engine Room
← qannasapi.comOne key. The whole catalog. A receipt on every response.
QannasAPI is the unified public-web-data API underneath the done-for-you jobs on our front page. One POST, one bearer token, one JSON envelope — people, companies, contacts, websites, SERP, ads, maps, and the Gulf's classifieds. Estimate any call for free, pay only on results, and read the exact charge off the response headers.
Free one-time credits · qk_test_ keys never bill · a miss returns data: null and charges 0
Not a developer? The jobs on our front page run these same endpoints — no code needed.
Overview
What you get behind one key
The plumbing a data team would otherwise build and maintain — already behind the same bearer token.
One key, one bill, one schema
Every action returns the same envelope: { status, request_id, data }. The code you write for your first call keeps working for your ten-thousandth.
Success-only billing
A call that returns no result is HTTP 200 with data: null and X-Credits-Charged: 0. Upstream failures are never billed and are safe to retry.
Free estimates on everything
POST /v1/data/{action}:estimate quotes the credit cost and charges nothing. Workflows also accept dry_run: true.
Server-side workflows
Six chained jobs run on our side with per-step success-only billing — one call instead of five, and you pay only for steps that produced data.
Quickstart
First call in three steps
No proxies to rotate, no headless browsers to babysit, no parsers to repair.
- 1. Mint a keyCreate a workspace, confirm your email, then mint a qk_live_ or qk_test_ key. Every request carries Authorization: Bearer.
- 2. Estimate for freePOST /v1/data/{action}:estimate returns the credit cost of the call you are about to make and charges zero.
- 3. Call itSame envelope every time. Read X-Credits-Charged and X-Credits-Balance off the response headers to know exactly what it cost.
# 1 — what will this cost? (free)
curl -X POST https://api.qannasapi.com/v1/data/contacts/find-email:estimate \
-H "Authorization: Bearer $QANNAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "Jane Doe, Acme Logistics"}'
# 2 — run it. Same envelope, every time.
curl -X POST https://api.qannasapi.com/v1/data/contacts/find-email \
-H "Authorization: Bearer $QANNAS_API_KEY" \
-d '{"query": "Jane Doe, Acme Logistics"}'
# < 200 OK
# < X-Credits-Charged: 5
# < X-Credits-Balance: 95
# {"status":"OK","request_id":"...","data":{...}}qk_test_ keys cost zero credits and are workspace quota-bound. Chains touching a paid source return deterministic fixtures; fully first-party chains may return live data.
MCP & agents
A hosted MCP server, scoped read-only
The same catalog, exposed to AI agents over Streamable HTTP JSON-RPC 2.0 — including the six workflows, each with a free dry_run quote.
Endpoint
POSThttps://api.qannasapi.com/mcp
Streamable HTTP · JSON-RPC 2.0 · 34 tools · 13 read-only scopes
34 scoped tools
28 data and usage tools plus the 6 workflow tools. Call tools/list to discover the current set for your token rather than trusting a copied list.
Read-only by construction
All 13 scopes are reads. There is no write scope to withhold — a token can look things up and can never change, send, or delete anything.
Deny-by-default tokens
qm_ tokens are shown once, stored as a SHA-256 digest, minted by workspace owners and admins, and revoked instantly (the next request fails).
In-band cost reporting
Every tool result carries _credits_charged and _credits_balance, so an agent can tell the user what a call cost without a second request.
Authentication: read this before you plan an integration
The MCP endpoint currently takes a static bearer token — there is no OAuth yet, though it is on the roadmap. In practice that means any client with a custom-header field connects today, while hosted connector directories that require an OAuth sign-in flow cannot yet. We do not name a client as supported until it has passed our own staging smoke test.
Known gaps — deliberately listed
- Delta cursors (since_cursor / track_delta) are REST-only and are not passed through the MCP tools.
- Consensus-verified contacts, classifieds listings and hiring signals are REST-only. Agent workflows reach them through a recipe, not a tool call.
- MCP calls always spend real credits — there is no test-key sandbox on the qm_ token path.
Any MCP client whose settings accept a URL plus a custom header will connect: header name Authorization, value Bearer followed by your token. Copy-paste configurations for individual clients are published as each one passes our smoke test.
SDKs & tooling
Generate a client, or just read the spec
The OpenAPI 3.1 document is the contract; everything else is generated from it.
OpenAPI 3.1
The full public specification, hosted on this site and safe to point a generator at.
Interactive reference
Every endpoint, schema and example, browsable — with the request bodies you will actually send.
Postman collections
The API collection plus recipe collections, generated from the same spec so they cannot drift.
Automation adapters
Nodes and connectors for the common automation platforms are built; marketplace listings are in progress.
Cookbooks
Worked recipes with real credit arithmetic
Each one shows the estimate, the call sequence, and what it actually costs.
Estimate before you call
01Quote the exact credit cost of any action before you run it, for free.
Read the credit headers
02Audit every charge straight off the response, with no end-of-month reconciliation.
Handle misses and retries
03Tell a miss apart from a failure, and retry only what is safe to retry.
Build a lead list
04Search, find the email, verify it — one call instead of three, billed per step.
Clean an email list
05Batch-verify a list and get a decay report back, without hand-rolling a queue.
Connect an MCP client
06Point an agent at the hosted MCP server and let it quote its own work first.
Delta cursors filter what you receive; they do not discount it. A check that returns nothing new still charges nothing, because nothing was found.
Pricing & metering
You can audit every charge from the response
Credits, public per-action prices, and three headers that tell you exactly where you stand.
Headers on every data call
X-Credits-Charged, X-Credits-Balance and X-Price-Book. No end-of-month reconciliation, no guessing.
Per-result pricing on searches
Searches charge per contact found, not per attempt. A bigger search costs more because it returns more.
Free evaluation
A one-time credit grant on signup, plus qk_test_ keys that never bill and are workspace quota-bound.
Volume and enterprise
Custom price books, higher rate-limit tiers and provisioned spend caps for teams running at scale.
Reliability
Judge us on our numbers
Published find-rates
GET /v1/public/hit-rates returns anonymized, cohort-protected statistics on how often we actually return data. No key required.
Estimates cost nothing
Quote any action or workflow before you run it, as often as you like, for zero credits.
Honest failures
An unrouted chain returns 501 not_implemented rather than a plausible empty result — and upstream errors are never charged.
Start with a free estimate.
Mint a key, quote a call, and see the whole contract for yourself before you spend a credit.