API Reference

STT and LLM over REST, plus realtime transcription over a streaming WebSocket. This reference documents the endpoints currently available in the Playground, including authentication, request and response formats, asynchronous job handling, and errors.

Quickstart

Every REST call authenticates with your license key in the X-License-Key header. The base URL for all endpoints is:

Base URL

https://api.denthub.ai

Use the license key issued to your account.
Send it in the X-License-Key header on every request.
Call an endpoint. A minimal first request:

First request

curl -X POST https://api.denthub.ai/chat/completions \
  -H "X-License-Key: <license-key>" \
  -H "Content-Type: application/json" \
  -d '{ "model": "densper", "messages": [{ "role": "user", "content": "Summarize the chief complaint for this patient." }] }'

Authentication

REST endpoints read the license key from the X-License-Key request header. The realtime WebSocket cannot use a custom header (browsers cannot set headers on a WS handshake), so it takes the key in the ?key= query parameter instead.

denthub issues one license key per account, scoped to that account. Never embed your key in client-side code you ship to end users.

Asynchronous jobs & webhooks

Most published endpoints answer in the same response. File STT runs as a background job instead: the POST hands back a job id right away, and you collect the result by polling GET /stt/{id} or by giving us a callbackUrl to call.

Keep polling until the job's status reaches a terminal state:

status	Meaning
PENDING	queued, not started yet
PROCESSING	running
COMPLETED	done — the result is in the response
FAILED / ERROR	the job did not finish
PARTIAL	finished, but the result is incomplete

Prefer a push over polling? Set a callbackUrl and we send it the finished job on completion (and expect a 200 back):

Webhook payload

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "COMPLETED"
}

Endpoints

Operational notes

Rate limits: none published — contact support for high-volume needs.
Correlation: the job id returned by each async POST is your handle for polling and for support requests.

Errors & authall STT & LLM REST endpoints

Authenticate every REST call with the license key issued to your account, in the X-License-Key header. Errors are returned as an ErrorResponseEntity:

{
  "errorCode": "1003",
  "message": "Invalid License."
}

HTTP	errorCode	Meaning	When
400	1000	Bad Request	Request validation failed or malformed request body
401	1003	Unauthorized	Missing or invalid license key in X-License-Key header
404	1002	Not Found	Requested resource not found or access denied
500	5000	Server Error	Internal server error — retry later or contact support

Some endpoints run as background jobs and return a status you poll (or receive by webhook); others respond synchronously. See Asynchronous jobs for how polling and callbacks work.