一个密钥。整个目录。每个响应都附收据。
QannasAPI 是我们首页那些全托管任务底层的统一公开网络数据 API。一次 POST、一个 Bearer 令牌、一套 JSON 封装——人物、公司、联系人、网站、SERP、广告、地图，以及海湾地区的分类信息。免费预估任何调用，只为结果付费，并直接从响应头读出确切扣费。
一次性免费积分 · qk_test_ 密钥永不扣费 · 未命中返回 data: null 且扣费为 0
不是开发者？我们首页的任务运行的正是这些端点——无需写代码。
概览
一个密钥背后你能得到什么
数据团队原本需要自行构建和维护的基础设施——已经藏在同一个 Bearer 令牌之后。
一个密钥、一张账单、一套数据模式
每个操作都返回同一套封装：{ status, request_id, data }。你为第一次调用编写的代码，在第一万次调用时依然有效。
只为成功结果计费
未返回结果的调用是 HTTP 200，带 data: null 和 X-Credits-Charged: 0。上游故障永不计费，可放心重试。
万事皆可免费预估
POST /v1/data/{action}:estimate 报出积分成本且分文不收。工作流同样接受 dry_run: true。
服务端工作流
六个串联任务在我们这边运行，逐步骤只为成功结果计费——一次调用代替五次，且只为产出数据的步骤付费。
快速入门
三步完成第一次调用
无需轮换代理，无需照看无头浏览器，无需修复解析器。
- 1. 创建密钥创建工作区，验证邮箱，然后创建 qk_live_ 或 qk_test_ 密钥。每个请求都携带 Authorization: Bearer。
- 2. 免费预估POST /v1/data/{action}:estimate 返回你即将发起的调用的积分成本，扣费为零。
- 3. 发起调用每次都是同样的封装。从响应头读出 X-Credits-Charged 和 X-Credits-Balance，就能精确知道这次花了多少。
# 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_ 密钥扣除零积分，并受工作区额度限制。涉及付费来源的调用链返回确定性的固定测试数据；完全第一方的调用链可能返回实时数据。
MCP 与智能体
托管的 MCP 服务器，带作用域限制且只读
同一个目录，通过 Streamable HTTP JSON-RPC 2.0 暴露给 AI 智能体——包括六个工作流，每个都支持免费的 dry_run 报价。
端点
POSThttps://api.qannasapi.com/mcp
Streamable HTTP · JSON-RPC 2.0 · 34 tools · 13 read-only scopes
34 个带作用域限制的工具
28 个数据与用量工具，外加 6 个工作流工具。请调用 tools/list 来发现你的令牌当前可用的工具集，而不要照抄一份复制来的清单。
从构造上就是只读
全部 13 个作用域都是读取操作。根本不存在需要收回的写入作用域——令牌可以查询信息，但永远无法更改、发送或删除任何东西。
默认拒绝的令牌
qm_ 令牌仅显示一次，以 SHA-256 摘要形式存储，由工作区所有者和管理员创建，并可即时撤销（下一次请求即失败）。
带内成本报告
每个工具结果都携带 _credits_charged 和 _credits_balance，智能体无需第二次请求就能告诉用户这次调用花了多少。
身份认证：规划集成之前请先读这一段
MCP 端点目前采用静态 Bearer 令牌——尚不支持 OAuth，但它已在路线图上。实际含义是：任何提供自定义请求头字段的客户端今天就能连接，而要求 OAuth 登录流程的托管连接器目录目前还不能。任何客户端在通过我们自己的预发布环境冒烟测试之前，我们都不会宣称支持它。
已知缺口——有意公开列出
- 增量游标（since_cursor / track_delta）仅限 REST，不会透传给 MCP 工具。
- 共识验证的联系人、分类信息列表和招聘信号仅限 REST。智能体工作流通过菜谱触达它们，而非工具调用。
- MCP 调用始终消耗真实积分——qm_ 令牌路径上没有测试密钥沙箱。
任何设置中支持填写 URL 加自定义请求头的 MCP 客户端都能连接：请求头名称为 Authorization，值为 Bearer 后接你的令牌。各客户端的可复制粘贴配置会在其通过我们的冒烟测试后逐一发布。
SDK 与工具链
生成一个客户端，或者直接读规范
OpenAPI 3.1 文档就是契约；其余一切都由它生成。
OpenAPI 3.1
完整的公开规范，托管在本站，可放心用于代码生成器。
交互式参考文档
每个端点、数据模式和示例均可浏览——附上你实际会发送的请求体。
Postman 集合
API 集合加菜谱集合，均由同一份规范生成，因此不会漂移。
自动化适配器
面向常见自动化平台的节点和连接器已构建完成；应用市场上架正在进行中。
实战菜谱
附带真实积分算术的成品菜谱
每一篇都展示预估、调用序列，以及实际花费。
调用前先预估
01在运行任何操作之前，免费获得它精确的积分成本。
读取积分响应头
02直接从响应中审计每一笔扣费，无需月底对账。
处理无结果与重试
03区分「没找到」和「失败」，只重试真正该重试的那一类。
构建潜客名单
04搜索、找到邮箱、核验邮箱 —— 一次调用取代三次，按步计费。
清洗邮箱名单
05批量核验一份名单并拿回衰减报告，无需自己手写队列。
接入 MCP 客户端
06把智能体指向托管的 MCP 服务器，让它先为自己的工作报价。
增量游标过滤的是你收到的内容；它不打折。一次没有新发现的检查依然扣费为零，因为什么都没找到。
定价与计量
每笔扣费都能从响应中审计
积分、公开的按操作价格，以及三个让你随时清楚账目的响应头。
每次数据调用都带响应头
X-Credits-Charged、X-Credits-Balance 和 X-Price-Book。无需月末对账，无需猜测。
搜索按结果计价
搜索按找到的联系人收费，而不是按尝试次数。更大的搜索花费更多，因为它返回得更多。
免费评估
注册即获一次性积分赠送，外加永不扣费、受工作区额度限制的 qk_test_ 密钥。
大用量与企业
面向规模化团队的自定义价格表、更高速率限制档位和预置支出上限。
可靠性
用我们的数字来评判我们
公开的命中率
GET /v1/public/hit-rates 返回匿名化、经群组保护的统计数据，展示我们实际返回数据的频率。无需密钥。
预估分文不收
在运行前为任何操作或工作流报价，想报多少次就报多少次，零积分。
诚实的失败
未路由的调用链返回 501 not_implemented，而不是一个貌似合理的空结果——且上游错误永不计费。