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

# Create Embed Session

> Get a one-time URL that shows a profile's lab results inside your app

Get a URL that shows the lab results of one profile as a read-only page. Open the URL in a WebView of your app or in a browser tab. Call this endpoint from your server each time the user opens the results, and never cache the URL.

Requires the `embed` and `results_view` scopes on a profile group of the profile. Aniva grants the `embed` scope on request. Without one of the two scopes, the request returns `403`.

> [!NOTE]
>
> The URL works once and for 5 minutes. When it opens, the page starts a 60-minute session that
> only that page holds. Archive your API key to close every open page at once.

## Request

### Path parameters

**id** `string` *required*

Unique identifier (UUID) of the profile whose results the page shows.

### Body

The body is optional. Without a body, the URL opens the biomarker list in the profile's language.

**language** `string`

Page language: `en`, `bg`, `ca`, `cs`, `da`, `de`, `el`, `es`, `et`, `fi`, `fr`, `ga`, `hr`, `hu`, `is`, `it`, `lb`, `lt`, `lv`, `mt`, `nl`, `no`, `pl`, `pt`, `ro`, `ru`, `sk`, `sl`, `sr`, `sv`, `tr` or `uk`. Default: the language of the profile.

**route** `object`

The page that the URL opens. Default: `{ "name": "biomarkers" }`. Any other `name` returns `400`.

**released pages**

**name** `string` *required*

One of:

* `biomarkers`: the list of all biomarkers with their latest results.
* `biomarker`: the detail page of one biomarker, with its trend, ranges and explanation. Needs `biomarker_id`.
* `twin`: the 3D body with a grade per health area. The user selects an area to see its biomarkers.

**biomarker\_id** `integer`

Only for `biomarker`. The `biomarker_id` of the biomarker, as in the results, for example `104`. Use the id, not the slug: a slug can change, the id stays.

**report** `object`

Limits every page to one lab report of the profile. Default: all reports of the profile. Send
exactly one of the three ids. The list, the trend of a biomarker and the twin then show the
results of that report only, and the page hides the appointment filter. The user cannot open
another report with this URL.

**properties**

**appointment\_id** `string`

The `id` of an appointment of the profile. Your key must have access to it, as for
[Get Lab Results](https://docs.anivahealth.com/api/appointments/get-results.md). If it does not, this endpoint returns
`404`, not `403`.

**home\_kit\_order\_id** `string`

The `id` of a home kit order of the profile. Your key must have access to it, as for
[Get Lab Results](https://docs.anivahealth.com/api/home-kit-orders/get-results.md) for home kit orders, and also needs
`home_kit_orders_view` or `home_kit_orders_manage`.

**document\_id** `string`

The `id` of a lab report that you uploaded for the profile with
[Upload Document](https://docs.anivahealth.com/api/documents/upload-document.md). Your key must have access to it, as for
[Get Document Results](https://docs.anivahealth.com/api/documents/get-document-results.md). If it does not, this endpoint
returns `404`, not `403`. The page shows the date of the lab test, or the upload date when
no value is read yet. While Aniva reads the document and has no value yet, every page tells
the user to open it again in a few minutes.

**appearance** `object`

The look of the page. The API adds it to the URL as search params.

**properties**

**theme** `string`

`light` or `dark`. Default: the system setting of the device.

**primary\_color** `string`

Hex colour of buttons and links, 3 or 6 digits, with or without `#`, for example `0f766e`.
Default: the brand colour of your profile group, else Aniva orange. Buttons keep white text,
so choose a dark colour.

**show\_logo** `boolean`

Show the logo of your profile group above the results. Default: `true`.

> [!TIP]
>
> You can also append the appearance params to a returned URL yourself, before the `#token=`
> fragment: `theme=light|dark`, `primary=<hex>` and `logo=0`. The page ignores an invalid value.
> The logo image always comes from your profile group, never from the URL.

## Response

On success, the API returns `201 Created`.

**url** `string` *required*

The page URL. The launch token is in the `#token=` fragment, so a browser never sends it to a
server. Open it once.

**expires\_at** `string` *required*

ISO 8601 instant after which the URL cannot be opened.

The session is not bound to one page. Inside the embed, the user can move from the twin to a biomarker and between the list and the detail pages. The page shows only lab results: it does not show values that Aniva calculates, files, chat or settings.

## Error responses

| Status | Description |
| - | - |
| `400` | Validation error — invalid profile ID, unknown `route.name`, invalid `biomarker_id`, invalid colour, or a `report` without exactly one valid UUID. |
| `403` | Forbidden — your API key is missing the `embed` or `results_view` scope, or the home kit scope for a home kit order report, or the profile is outside your access context. |
| `404` | Profile not found, or no biomarker has this `biomarker_id`, or the `report` is not an appointment, home kit order or uploaded document of this profile, or the report is outside your access. This endpoint returns `404`, not `403`, so that it does not show that the report exists. |
| `500` | Internal server error. |

```bash cURL theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/profiles/a3f1c2d4-8b7e-4f2a-9c1d-2e3f4a5b6c7d/embed-sessions \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "language": "de",
    "route": { "name": "biomarker", "biomarker_id": 104 },
    "report": { "appointment_id": "8d2e4f6a-1b3c-4d5e-9f70-a1b2c3d4e5f6" },
    "appearance": { "theme": "light", "primary_color": "0f766e" }
  }'
```

```bash One uploaded document theme={null}
curl --request POST \
  --url https://anivahealth.com/api/v1/profiles/{id}/embed-sessions \
  --header 'Authorization: Bearer <api_key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "report": { "document_id": "3f9a7c2e-5d4b-4e1a-8c6f-0b1d2e3f4a5b" }
  }'
```

```json 201 theme={null}
{
  "url": "https://anivahealth.com/de/embed/biomarkers/vitamin-d?theme=light&primary=0f766e#token=eyJwdXJwb3NlIjoiZW1iZWRfbGF1bmNoIi4uLn0.k7Qm2V0sZ1yH",
  "expires_at": "2026-11-19T20:17:43.000Z"
}
```

```json 400 theme={null}
{
  "error": "route.name: Invalid discriminator value. Expected 'biomarkers' | 'biomarker' | 'twin'"
}
```

```json 403 theme={null}
{
  "error": "Access denied: profile is outside your permission scope"
}
```

```json 404 theme={null}
{
  "error": "Appointment not found"
}
```

```json 404 document theme={null}
{
  "error": "Document not found"
}
```


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