Core concepts

External URIs

Reference Minis and Records by an identifier from your own system.

A Mini or Record can carry an external URI: a stable identifier that points back to the same thing in your own system, such as a participant or a note in your care platform. You set it when you create the resource, and from then on you can address that resource by the identifier you already hold.

Use an external URI in place of an id

Anywhere the API takes a Mini or Record id in the path, you can pass either the Minikai id or the resource’s external URI. Because the id sits in the URL path, URL-encode the URI so its slashes and colons don’t break the route:

$# By Minikai id
$curl https://api.minikai.com/minikai-public/api/v1/Minis/8f3c1e2a-1b4d-4c9a-9f21-2e7a6b0d54c8 \
>  -H "Authorization: Bearer sk_live_..."
$
$# The same Mini, by its external URI
$curl https://api.minikai.com/minikai-public/api/v1/Minis/https%3A%2F%2Fcare.example.com%2Fparticipants%2F123 \
>  -H "Authorization: Bearer sk_live_..."

Create on first write

If you send a PUT to a Mini or Record id that is an external URI Minikai hasn’t seen before, the resource is created. You can sync a participant or a note from your system in a single call, without checking whether it already exists first. A new Record also needs its Mini in the request body.

Fetch several at once

GET /Records accepts an externalUris query parameter, so you can pull back a set of Records by the identifiers your system already holds rather than making one request per id.