FAQs

Answers to the most common questions

Answers to the most common API questions.

Can I use the API on Free plan?

Yes, with 100 requests/hour. Enough to test and integrate. For production use, Pro (1,000 req/h) or higher is recommended. Full details in the Rate limits section.

How do I verify my API key is valid?

Call GET /api/v1/me with your key in the Authorization header. A 200 with your plan, scopes, storage and exam count means the key works; a 401 unauthorized means it is invalid, revoked, or from a different environment (live vs test). Fastest health check, negligible quota use. You can also try it from the playground built into the Authentication section.

How do I see how much I am consuming from the API?

In the dashboard open /dashboard/api/usage. You see an hourly chart of the last 7 days per key, the most-used calls (endpoint + method) and recent 429s to detect if you are nearing the limit. If 429s become frequent, upgrade your plan or move part of the flows to sandbox (which has a separate bucket).

Is the X-CBCTHub-Version header required?

Not required, but recommended in production. If you omit it we use the latest stable version (today 2026-06-23) — fine to get started, risky if we later ship a breaking change. Pinning protects you: when a new version drops your system stays on the old one until you migrate deliberately. If you send an invalid value we return 400 with code unsupported_api_version. Details in Authentication → Versioning.

Are there official SDKs?

We publish the official OpenAPI 3.1 specification at https://cbcthub.com/openapi.json. From there you can auto-generate a type-safe SDK in TypeScript, Python, PHP, Go, Java and many more languages with openapi-generator. See the "OpenAPI & SDKs" section for the exact commands.

Is there a testing sandbox?

Yes. Generate a key with the cbct_test_ prefix from Settings → API → Sandbox tab. Everything you create with it lives isolated from production: no storage consumed, no plan quota used, and webhooks fire separately with livemode: false. Full details in the Sandbox / Test mode section.

How do I separate live and test webhook events?

Each subscription has two independent flags: enabled_live (default true) and enabled_test (default false). One subscription can receive both modes (and tell them apart via the payload's livemode field), or you can have separate subscriptions — one with enabled_live=true for production and another with enabled_test=true for staging.

Can I embed the viewer in my system?

Yes. Use viewer_url in an HTML iframe, or redirect the user. In public mode, the viewer opens without editing controls.

Does the shared link carry my center branding?

On Free plan it shows "Powered by CBCTHub". On Pro or higher you can enable full branding (logo, name, colors) from the dashboard.

Are there event webhooks?

Yes. We support exam.created, exam.confirmed, exam.deleted, report.published and report.signed. With HMAC SHA-256 signature and automatic retries. Full details in the Webhooks section.

How do I verify that a webhook really comes from CBCTHub?

Validate the HMAC SHA-256 of the raw body bytes (original bytes, not the parsed JSON) using the secret you received when creating the subscription. The X-CBCTHub-Signature header carries sha256=<base64>. Compare in constant time with crypto.timingSafeEqual (Node) or hmac.compare_digest (Python).

What happens if my webhook endpoint is down?

We retry automatically with exponential backoff: 30s, 2min, 10min, 1h, 6h, 24h. Max 6 attempts per event. After 20 consecutive failures the subscription auto-disables to stop hammering your endpoint. You can see each delivery log in GET /api/v1/webhooks/{id}/deliveries.

Can I upload reports in formats other than PDF?

For now only PDF (we validate %PDF- magic bytes). If you need to build the PDF from text, HTML or a template, do it on your side with any library (puppeteer, pdfkit, jspdf, wkhtmltopdf) and upload it as base64.

Can you sign a DPA?

Yes. Download the template at cbcthub.com/dpa, sign it and send back. We return it countersigned within 48 business hours.

How do I upload a CBCT that I have as a ZIP?

Use upload_mode="zip" on POST /api/v1/exams (with zip_size_bytes). We return ONE presigned URL; PUT the whole ZIP there (single request) and then call POST /api/v1/exams/{id}/process-zip. The server unzips in streaming (without loading the ZIP into RAM) and uploads each DICOM to R2. Done: exam ready in 3 calls instead of N. Limits: 1 GB ZIP, 5000 files inside, 5 GB expanded, 1.6 TB per individual file. curl/Node/Python examples in Upload flow → Option A.

Do you accept non-DICOM files?

The API accepts any format (we do not validate extension). But the 3D viewer only works with valid DICOM. For exam_type "mesh" we support STL and PLY.

How do we know if there is an incident?

We publish every incident on our public status page with a real-time timeline. Subscribe by email or RSS from the status page itself, or email soporte@cbcthub.com to be added to dedicated webhook alerts (Ultra / Enterprise plans). See the Reliability section for details.