# Upload a patient photo

Operation ID: `patient.uploadPhoto`

Store a base64-encoded photo as a FHIR Binary for the authenticated patient and link it via the patient's photo-binary extension. When the patient is linked to an Athena chart, mirror the same image there (create when absent and replace when present). The FHIR write remains successful if the best-effort Athena mirror fails. Requires a patient Bearer JWT.

## Public method

`uploadPhoto`

Signature: `patient.uploadPhoto(request)`

Return type: `Promise<PhotoUploadResponse>`

## Authentication

Classification: **AUTHENTICATED**

Schemes: `bearerAuth`

## Prerequisites

None documented.

## HTTP

`POST /patients/photo`

## Path parameters

None.

## Query parameters

None.

## Body parameters

| Name | Type | Required | Format | Allowed values | Default | Nullable | Description |
|---|---|---:|---|---|---|---:|---|
| `body` | [`patient.UploadPhotoRequest`](../models/patient.UploadPhotoRequest.md) | No |  |  |  | No |  |

Request model: [`patient.UploadPhotoRequest`](../models/patient.UploadPhotoRequest.md)

## Request example

```json
{
  "content_type": "image/png",
  "data": "c3ludGhldGljLWltYWdl"
}
```

## Success responses

| Status | Shape | Content type | Description |
|---|---|---|---|
| `201` | [`patient.UploadPhotoResponse`](../models/patient.UploadPhotoResponse.md) | application/json | Patient photo stored |

## Success response examples

### 201

```json
{
  "athena_photo_status": "linked",
  "binary_id": "string",
  "openloop_photo_status": "linked",
  "steadymd_photo_status": "linked"
}
```

## Common errors

| Status | Shape | Content type | Description |
|---|---|---|---|
| `400` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | data is missing |
| `401` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Authorization required — missing, invalid, expired, or non-patient Bearer JWT |
| `404` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | The authenticated patient has no FHIR Patient record |
| `500` | [`patient.ErrorResponse`](../models/patient.ErrorResponse.md) | application/json | Internal server error |

## Error examples

### 400 — data is required

```json
{
  "error": "data (base64) is required"
}
```

### 401 — Missing or invalid access token

```json
{
  "error": "Authorization required"
}
```

### 404 — Patient not found

```json
{
  "error": "Patient not found"
}
```

### 500 — Unexpected service failure (sanitized example)

```json
{
  "error": "Internal server error"
}
```

## NodeJS / TypeScript implementation

```ts
import { HCSDK } from "@healthcloudai/hc-sdk";
import type { PhotoUploadRequest } from "@healthcloudai/hc-sdk";
```

```ts
const request = {
  "content_type": "image/png",
  "data": "c3ludGhldGljLWltYWdl"
};

const result = await patient.uploadPhoto(request);
```

## cURL

```bash
curl -X POST \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{"content_type":"image/png","data":"c3ludGhldGljLWltYWdl"}' \
  'https://dev-api-patient.health.cloud/patients/photo'
```

## Notes

None.

## Prepared Test Console scenario

No canonical scenario is currently associated.

## Real response

No approved real integration response is currently published. Unapproved candidates are never rendered as examples.