> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.minikai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.minikai.com/_mcp/server.

# External URIs

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.
`$MINIKAI_BASE_URL` below is your region's base URL, which [Data regions](/guides/get-started/data-regions) lists.

```bash
# By Minikai id
curl "$MINIKAI_BASE_URL/api/v1/Minis/8f3c1e2a-1b4d-4c9a-9f21-2e7a6b0d54c8" \
  -H "Authorization: Bearer sk_live_..."

# The same Mini, by its external URI
curl "$MINIKAI_BASE_URL/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.