> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Upload and manage your own formulary catalogs, then use them in Eka's medical search.

A dataset is your own catalog of one kind of clinical item: your drug formulary, your lab investigations, results and panels, 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](https://developer.eka.care/api-sdk/datasets/medical-db/drugs-and-labs.md) 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 these kinds of catalog. Each page lists every column you can send, which ones are mandatory, the values they accept, and a sample file.

| Catalog | `type` | Mandatory columns | Details |
| - | - | - | - |
| Drugs | `medication` | `medication_id`, `name` | [Medications](https://developer.eka.care/api-sdk/datasets/medications.md) |
| Lab investigations: tests, scans and packages a doctor orders | `lab_investigation` | `investigation_id`, `name` | [Lab investigations](https://developer.eka.care/api-sdk/datasets/lab-investigations.md) |
| Lab results: the values that come back, each with one unit | `lab_result` | `result_id`, `name` | [Lab results](https://developer.eka.care/api-sdk/datasets/lab-results.md) |
| Lab panels: named, ordered collections of results, like CBC | `lab_panel` | `panel_id`, `name`, `member_result_ids` | [Lab panels](https://developer.eka.care/api-sdk/datasets/lab-panels.md) |
| Symptoms | `symptom` | `symptom_id`, `name` | [Symptoms](https://developer.eka.care/api-sdk/datasets/symptoms.md) |
| Diagnoses | `diagnosis` | `diagnosis_id`, `name` | [Diagnoses](https://developer.eka.care/api-sdk/datasets/diagnoses.md) |

Upload lab results before lab panels: every panel member must already be a stored result.

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. 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

* **[Create or update records](https://developer.eka.care/api-sdk/datasets/write.md)**: send a JSON list or a CSV file, in `upsert` or `reconcile` mode, with an optional dry run
* **[List records](https://developer.eka.care/api-sdk/datasets/list.md)** and **[Get a record](https://developer.eka.care/api-sdk/datasets/get.md)**: read your catalog back
* **[Export the catalog as CSV](https://developer.eka.care/api-sdk/datasets/export.md)**: download it in the same format the write endpoint accepts
* **[List CSV import batches](https://developer.eka.care/api-sdk/datasets/batches.md)**: check that an upload landed
* **[Deactivate records](https://developer.eka.care/api-sdk/datasets/delete.md)**: remove records reversibly
* **[Delete the whole catalog](https://developer.eka.care/api-sdk/datasets/delete-all.md)**: remove every record permanently
* **[Get](https://developer.eka.care/api-sdk/datasets/search-status-get.md)** and **[set](https://developer.eka.care/api-sdk/datasets/search-status-set.md)** partner search status: switch medical search over to your catalog

For medications, use a `form_name` from the [accepted drug forms](https://developer.eka.care/docs/datasets/forms.md) 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:

```
Authorization: Bearer <access_token>
```

See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md) for how to get one.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.