Skip to main content
A dataset is your own catalog of one kind of clinical item: your drug formulary, your lab test menu, or your lists of symptoms and diagnoses. The Datasets API lets you load these catalogs into Eka, keep them in sync with your system, and switch Eka’s Medical Database search over to them. Every request acts only on the workspace your access token belongs to. You cannot read or change another workspace’s data.

​
Dataset types

You can upload four kinds of catalog. Each page lists every column you can send, which ones are mandatory, the values they accept, and a sample file. Records are identified by your id. Writing a record whose id already exists updates it.

​
Preparing a file

These rules apply to every catalog, whether you upload a CSV in the console or through the API.
  • One header row, then one row per record. Column names are the ones listed on each catalog’s page. Columns can be in any order, and you only need the mandatory ones plus whatever else you have.
  • Common alternative column names are understood. For example id for your id column, or eka_id for ekaid. A column Eka doesn’t recognise is ignored, with a warning.
  • Leave a cell empty when you don’t have the value.
  • Lists in one cell use | between values, like CBC|Hemogram. The one exception is a drug’s generic_list and generic_list_ids, which use +. In JSON, send these as lists instead.
  • Yes/no columns accept true or false (also yes/no and 1/0).
  • Quote any value containing a comma, like "Chest pain, unspecified". Spreadsheet programs do this when they save as CSV.
  • Save as UTF-8 CSV if you can. Files saved by Excel on Windows also work.
  • Up to 50,000 rows per file.

​
Endpoints

For medications, use a form_name from the accepted drug forms so the drug is linked to Eka’s dosage form.

​
Mapping your records to Eka ids

Every record can carry an optional ekaid: Eka’s own id for the same item, taken from Eka’s reference list (for example lb-1322178942 for a lab test). When it is set, Eka products such as the EMR recognise your item and can offer features built on Eka’s data, like calculators. Eka stores the id as you send it and does not check it, so make sure each mapping is right.

​
Keeping a catalog in sync

To mirror a catalog from your system on a schedule, send the whole catalog each time in reconcile mode. Records you no longer send are deactivated, not deleted, so sending them again restores them.
1

Dry run

POST /admin/datasets/v1/?type=medication&mode=reconcile&dry_run=true with the full catalog. Nothing is written; the response shows how many records would be inserted, updated, reactivated and deactivated.
2

Commit

If the counts look right, send the same request without dry_run. If more than half of your catalog would be deactivated, the request is rejected with a shrink_guard error, the usual sign of a truncated export. Pass confirm_shrink=true only if you really mean it.
3

Verify

For CSV uploads, GET /admin/datasets/v1/batches/?type=medication shows the latest batch and its row counts.
4

Enable search (first sync only)

POST /admin/datasets/v1/search-status/?type=medication with {"enabled": true}. Later syncs don’t need to repeat this. Set it back to false to roll back.

​
Writes are all-or-nothing

If any record or CSV row fails validation, nothing in the request is written. The errors list in the response names every failing record, field and value, so you can fix them all at once.

​
Limits

  • Request bodies are limited to 10 MB. For a larger catalog, send it as several upsert requests (a reconcile must contain the whole catalog in one request).
  • A request must finish within 29 seconds.
  • List and batch pages return at most 1000 items (limit, default 100).

​
Authentication

All endpoints require an access token in the Authorization header:
See Authorization for how to get one.