Tiba Copilot Developer Docs

Overview

Tiba Copilot connects to your EMR with simple REST endpoints for ingesting clinical content (documents, images, audio), extracting structured entities, exporting EHR-ready data, and performing clinical search. All requests are HTTPS with Bearer tokens.

Quickstart

1. Obtain an API key from Admin → API Keys.
2. Set environment variable API_BASE_URL (see environments below).
3. POST a sample document to /api/v1/ingest to kick off processing.
4. Subscribe to webhooks to receive processing updates.

Authentication

Use Bearer tokens in the Authorization header.

Authorization: Bearer <YOUR_API_KEY>

Base URL & Environments

• Local: http://localhost:8080
• Docker bridge (frontend → backend): http://backend:8080
• Production: https://api.tiba.co.ke (example)

export API_BASE_URL="https://api.tiba.co.ke" # set per environment

Document Ingestion

Upload PDFs/images; Tiba extracts entities and links to a patient record.

POST {API_BASE_URL}/api/v1/ingest
Content-Type: multipart/form-data
Authorization: Bearer <API_KEY>

Form fields:
- file: (pdf|png|jpg)
- patient_id: string
- source: string (optional)

curl -X POST "$API_BASE_URL/api/v1/ingest" \
-H "Authorization: Bearer $API_KEY" \
-F file=@/path/to/note.pdf \
-F patient_id="12345" \
-F source="external_emr"

Response (202 Accepted):

{ "job_id": "job_abc123", "status": "accepted" }

Audio Transcription

Upload clinical audio notes for ASR + medical entity extraction.

POST {API_BASE_URL}/api/v1/transcribe
Content-Type: multipart/form-data
Authorization: Bearer <API_KEY>

Form:
- audio: (wav|mp3|m4a)
- patient_id: string

Entity Extraction & EHR Export

Fetch normalized entities and structured EHR payloads after processing.

GET {API_BASE_URL}/api/v1/jobs/{job_id}
Authorization: Bearer <API_KEY>

200 OK
{
  "status": "completed",
  "entities": {
    "problems": [...],
    "medications": [...],
    "allergies": [...],
    "labs": [...]
  },
  "ehr_export": {
    "format": "FHIR",
    "bundle": { ... }
  }
}

Clinical Search

Ask questions in natural language across a patient's records.

POST {API_BASE_URL}/api/v1/search
Content-Type: application/json
Authorization: Bearer <API_KEY>

{ "patient_id": "12345", "query": "latest HbA1c and current meds" }

200 OK
{ "answers": [{ "type": "lab", "name": "HbA1c", "value": "7.4%", "date": "2025-02-18" }], "sources": [...] }

Webhooks

Receive asynchronous notifications for processing events.

• document.processed
• transcription.completed
• extraction.completed

Webhook payload:

POST https://your-app.com/webhooks/tiba
Headers:
- X-Tiba-Event: extraction.completed
- X-Tiba-Signature: t=timestamp,v1=hmac_sha256(payload, WEBHOOK_SECRET)

Body:
{ "job_id": "job_abc123", "patient_id": "12345", "status": "completed" }

Verify signatures using your WEBHOOK_SECRET (HMAC SHA-256 over raw request body).

Errors & Rate Limits

• 400: Validation error
• 401: Invalid/expired token
• 403: Insufficient permissions
• 404: Not found
• 409: Duplicate/conflict
• 429: Rate limited
• 5xx: Service error

Default rate limit example: 60 req/min per API key (contact us to increase).

SDK Example (Node/JS)

import axios from "axios";
const api = axios.create({
  baseURL: process.env.API_BASE_URL,
  headers: { Authorization: `Bearer ${process.env.API_KEY}` }
});

export async function ingest(file, patientId) {
  const form = new FormData();
  form.append("file", file);
  form.append("patient_id", patientId);
  const { data } = await api.post("/api/v1/ingest", form);
  return data;
}

Support

Need help or a higher rate limit? Email devrel@tiba.co.ke.