Skip to main content
The Clinik class is the single entry point for all SDK operations. When you construct a client, it validates your API key format, configures retry logic, and exposes typed namespaces for every supported FHIR resource. Every method on those namespaces returns the same ApiResponse<T> envelope, which gives you the resource data alongside request metadata.

​
Constructor

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(apiKey: string, options?: ClinikOptions);
​
apiKey
string
required
Your secret API key. Keys follow the format clk_live_* for production and clk_test_* for the sandbox environment. Never hardcode this value — read it from an environment variable.
​
options
ClinikOptions
Optional configuration object. All fields have safe defaults.

​
ClinikOptions

​
baseUrl
string
default:"https://api.clinikapi.com"
Base URL for all API requests. The SDK enforces HTTPS and warns at startup if you provide an HTTP URL.
​
timeout
number
default:"30000"
Request timeout in milliseconds. Requests that exceed the limit throw a ClinikApiError with code timeout.
​
retries
number
default:"2"
Maximum retry attempts on 5xx errors, 429 rate-limit responses, and network failures. Uses jittered exponential backoff. Set to 0 to disable.

​
Resource namespaces

After construction, the client exposes 14 resource namespaces. Each namespace maps to a FHIR R4 resource type and provides the same five standard methods. 
clinik.patients          // Patient
clinik.practitioners     // Practitioner
clinik.practitionerRoles // PractitionerRole
clinik.encounters        // Encounter
clinik.observations      // Observation
clinik.medications       // Medication
clinik.prescriptions     // MedicationRequest
clinik.appointments      // Appointment
clinik.intakes           // QuestionnaireResponse
clinik.consents          // Consent
clinik.labs              // DiagnosticReport
clinik.notes             // DocumentReference
clinik.assessments       // ClinicalImpression
clinik.documents         // Composition
Every namespace provides these methods:
MethodDescription
create(data)Create a new resource
read(id, options?)Read a resource by ID
update(id, data)Partially update a resource (JSON Patch internally)
delete(id)Delete a resource
search(params?)Search with filters and cursor pagination
Some namespaces use domain-specific method names — for example clinik.intakes.submit() and clinik.consents.sign() — where the action name is more semantically meaningful than create.

​
FHIR passthrough

For raw FHIR R4 access beyond what the simplified namespaces provide, use the fhir namespace: 
clinik.fhir.request(method: string, path: string, body?: unknown)
See FHIR Passthrough for full details.

​
ApiResponse<T>

Every SDK method returns Promise<ApiResponse<T>>. Destructure data for the resource and meta for request metadata. 
interface ApiResponse<T> {
  data: T;
  meta: ResponseMeta;
}

interface ResponseMeta {
  requestId: string;
  timestamp: string;
  status: number;
  rateLimitTotal?: number;
  rateLimitRemaining?: number;
  rateLimitReset?: number;
}
​
data
T
required
The requested resource or result. The generic type parameter T corresponds to the resource type returned by the method you called.
​
meta.requestId
string
required
A unique identifier for the request. Include this when filing support tickets — it lets the ClinikAPI team trace the exact server-side execution.
​
meta.timestamp
string
required
ISO 8601 timestamp of when the server processed the request.
​
meta.status
number
required
HTTP status code returned by the API.
​
meta.rateLimitTotal
number
Total number of requests allowed in the current rate-limit window.
​
meta.rateLimitRemaining
number
Number of requests you can still make before hitting the rate limit. Monitor this field to implement proactive throttling in high-throughput workflows.
​
meta.rateLimitReset
number
Seconds until the rate-limit window resets. Use this alongside rateLimitRemaining to schedule request bursts.

​
Example: using meta fields

const { data: patient, meta } = await clinik.patients.read('pt_abc123');

console.log('Patient:', patient.id);
console.log('Request ID:', meta.requestId);        // for support
console.log('Rate limit left:', meta.rateLimitRemaining); // proactive throttling

if ((meta.rateLimitRemaining ?? 100) < 10) {
  // Slow down — approaching the limit
  await sleep(meta.rateLimitReset! * 1000);
}

​
Security features

The SDK applies several security protections automatically:
  • Browser detection — warns if you import the SDK in a browser environment where the API key would be exposed.
  • HTTPS enforcement — warns at startup if baseUrl is not an HTTPS URL.
  • Path traversal protection — resource IDs are validated against the pattern [a-zA-Z0-9\-_.] before being interpolated into URLs.
  • FHIR include injection prevention — _include values are validated to prevent parameter injection.
  • Body size limits — request bodies over 1 MB are rejected client-side before being sent.
  • PHI sanitization — error messages never include patient data values, only field names and constraint descriptions.
  • Jittered retries — exponential backoff with random jitter prevents thundering-herd issues during outages.