Rafiq API

Pass your API key as a Bearer token on every request.

• Keys are scoped to a single organization: every request, upload, job and quota check stays inside that organization — a key can never see another organization's data.
• A revoked key stops authenticating immediately, with no grace period — the next request made with it gets a 401.
• If your organization is suspended or permanently deleted, every key on it stops working immediately too, even though the key record itself is untouched.
• GET /languages and GET /openapi.json are the two exceptions — public reference endpoints that need no key at all.

Every service draws from one shared credit pool per organization — there's no separate quota per service.

• A transcription job is charged one credit per second of audio, rounded up.
• A document job is charged OCR_CREDITS_PER_PAGE credits per page, deducted once the page count is known — at completion, not at submit time.

Every error response has the same shape:

Codes returned by the endpoints below:

Set callback_url when you submit a job and rafiq-api POSTs the result to it once the job reaches a terminal state, so you don't have to poll GET .../{id}.

The payload shape depends on the job type and outcome:

// Transcription — completed
{ "id": "…", "status": "completed", "transcript": { ... } }

// Transcription — failed
{ "id": "…", "status": "failed", "error": { "code": "...", "message": "..." } }

// Document — completed
{ "id": "…", "status": "completed", "pages": 12, "formats": ["md"] }

// Document — failed
{ "id": "…", "status": "failed", "error": { "code": "...", "message": "..." } }

A completed document job's payload carries only the page count and formats, never the extracted text — fetch that separately with GET /api/v1/documents/{id}?format=md|txt|json.

A signed delivery carries an X-Rafiq-Signature header: the HMAC-SHA256 hex digest of the exact raw request body, computed with your organization's webhook signing secret.

Verify against the exact bytes of the body as received. Parsing the JSON and re-serializing it before verifying produces a different string and will fail intermittently.

Delivery is retried up to 3 times, waiting 1 second then 2 seconds between attempts, if your endpoint doesn't return a successful response. After the last attempt fails, rafiq-api stops trying.

const crypto = require("crypto");

// rawBody must be the exact, unparsed request body — the same bytes rafiq-api
// signed. Verifying JSON.parse(rawBody) re-serialized will fail intermittently:
// key order and whitespace are not guaranteed to round-trip identically.
function isValidSignature(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return (
    signatureHeader.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signatureHeader), Buffer.from(expected))
  );
}