---
schema: "agents-md/1.0"
ai_agents_docs_site_root: "https://agents.1health.io/public/demo/api/"
rest_api_root: "/v3/patient/{patientId}/attach"
path_to_agent_file: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/attach/agents.md"
kind: "endpoints"
methods: [GET, POST, DELETE]
api_version: "v3"
parent: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/agents.md"
html: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/attach/index.html"
how_to: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/attach/how-to.md"
use_case: "https://agents.1health.io/public/demo/api/v3/patient/_patientId_/attach/use-case.md"
source_version: "43d07c0335624b7661c2872315a5f184e8c3d832"
extractor_model: "gpt-4o-2024-08-06"
extractor_prompt_version: "2026-08-13.v1"
reconciler_model: "claude-sonnet-4-6"
reconciler_prompt_version: "2026-08-13.v1"
generated_at: "2026-08-27T01:13:03.949984+00:00"
---

# /v3/patient/{patientId}/attach

**URL**: https://demo.1health.io/api/v3/patient/{patientId}/attach

APIs for uploading, listing, fetching, and deactivating a patient's file attachments (PDFs, images, audio, FHIR bundles) with structured metadata. Storage only — no content extraction.

## Endpoints

| Endpoint | Method | Description |
| --- | --- | --- |
| /v3/patient/{patientId}/attach | GET | List a patient's attachments |
| /v3/patient/{patientId}/attach | POST | Upload a file (multipart) and attach it to a patient |
| /v3/patient/{patientId}/attach | POST | Upload a file (multipart) and attach it to a patient |
| /v3/patient/{patientId}/attach/{documentId} | GET | Get a single patient attachment |
| /v3/patient/{patientId}/attach/{documentId} | DELETE | Deactivate a patient attachment |

---

## GET /v3/patient/{patientId}/attach

List a patient's attachments

### Overview

Returns all attachments for a patient, newest first, each with a fresh signed download URL. Requires authentication.

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Query Parameters

| Parameter | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| documentType | String | No |  | Optional filter by document type (e.g. lab_result, imaging, clinical_note, audio, fhir_bundle, referral, consent_form, other). Omit to list all. |

### Responses

#### 200 OK

List of patient attachments.

**DTO**: `PatientAttachmentListResponseDTO`

```json
{
  "attachments": [
    {}
  ]
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| attachments | List<PatientAttachmentResponseDTO> | No | The patient's attachment records. |

### Example

```bash
curl -X GET "https://demo.1health.io/api/v3/patient/1001/attach" \
  -H "Authorization: Bearer $TOKEN"
```

## POST /v3/patient/{patientId}/attach

Upload a file (multipart) and attach it to a patient

### Overview

Same as the JSON upload, but the file is sent as a `multipart/form-data` part instead of base64. Requires authentication.

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Request Body

**Content-Type**: `application/json` · **DTO**: `PatientAttachmentRequestDTO`

```json
{
  "documentType": "example-value",
  "data": "example-value",
  "name": "example-value",
  "metadata": "example-value"
}
```

| Field | Type | Required | Constraints | Description |
| --- | --- | --- | --- | --- |
| documentType | string | Yes | allowableValues: [lab_result, imaging, clinical_note, audio, fhir_bundle, referral, consent_form, other] | The category of document being uploaded. |
| data | string | Yes |  | The file bytes, base64-encoded. |
| name | string | No |  | Display name. Defaults to the uploaded filename / a generated name when omitted. |
| metadata | object | No |  | Arbitrary structured key/value metadata stored alongside the file. Returned on the single-item read. |

### Responses

#### 201 Created

Attachment stored successfully.

**DTO**: `PatientAttachmentResponseDTO`

```json
{
  "id": 1001,
  "patientId": 1001,
  "documentType": "example-value",
  "name": "example-value",
  "active": true,
  "contentType": "example-value",
  "sizeBytes": 1001,
  "metadata": {},
  "downloadUrl": "example-value",
  "downloadUrlExpiresAt": "2024-01-15T09:30:00Z",
  "createdAt": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Server-assigned attachment (document) ID. |
| patientId | Long | Yes | ID of the patient the attachment belongs to. |
| documentType | String | No | The category of document. |
| name | String | No | Display name. |
| active | Boolean | No | Whether the attachment is active. Deactivated attachments are retained but have no download URL. |
| contentType | String | No | MIME type of the file. |
| sizeBytes | Long | No | Size of the file in bytes. |
| metadata | Map<String, Object> | Yes | Arbitrary structured key/value metadata stored with the file. Populated only on the single-item read. |
| downloadUrl | String | No | Time-limited signed URL for downloading the file. |
| downloadUrlExpiresAt | LocalDateTime | No | When the signed download URL expires (UTC). |
| createdAt | LocalDateTime | No | When the attachment was created (UTC). |

### Example

```bash
curl -X POST "https://demo.1health.io/api/v3/patient/1001/attach" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" -d '{"documentType": "example-value", "data": "example-value", "name": "example-value", "metadata": "example-value"}'
```

## POST /v3/patient/{patientId}/attach

Upload a file (multipart) and attach it to a patient

### Overview

Same as the JSON upload, but the file is sent as a `multipart/form-data` part instead of base64. Requires authentication.

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |

### Request Body

**Content-Type**: `multipart/form-data` · **DTO**: `PatientAttachmentMultipartRequestDTO`

### Responses

#### 201 Created

Attachment stored successfully.

**DTO**: `PatientAttachmentResponseDTO`

```json
{
  "id": 1001,
  "patientId": 1001,
  "documentType": "example-value",
  "name": "example-value",
  "active": true,
  "contentType": "example-value",
  "sizeBytes": 1001,
  "metadata": {},
  "downloadUrl": "example-value",
  "downloadUrlExpiresAt": "2024-01-15T09:30:00Z",
  "createdAt": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Server-assigned attachment (document) ID. |
| patientId | Long | Yes | ID of the patient the attachment belongs to. |
| documentType | String | No | The category of document. |
| name | String | No | Display name. |
| active | Boolean | No | Whether the attachment is active. Deactivated attachments are retained but have no download URL. |
| contentType | String | No | MIME type of the file. |
| sizeBytes | Long | No | Size of the file in bytes. |
| metadata | Map<String, Object> | Yes | Arbitrary structured key/value metadata stored with the file. Populated only on the single-item read. |
| downloadUrl | String | No | Time-limited signed URL for downloading the file. |
| downloadUrlExpiresAt | LocalDateTime | No | When the signed download URL expires (UTC). |
| createdAt | LocalDateTime | No | When the attachment was created (UTC). |

### Example

```bash
curl -X POST "https://demo.1health.io/api/v3/patient/1001/attach" \
  -H "Authorization: Bearer $TOKEN"
```

## GET /v3/patient/{patientId}/attach/{documentId}

Get a single patient attachment

### Overview

Returns one active attachment by id, including its metadata and a fresh signed download URL. Requires authentication.

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |
| documentId | Long | Yes | The ID of the attachment. |

### Responses

#### 200 OK

Attachment found.

**DTO**: `PatientAttachmentResponseDTO`

```json
{
  "id": 1001,
  "patientId": 1001,
  "documentType": "example-value",
  "name": "example-value",
  "active": true,
  "contentType": "example-value",
  "sizeBytes": 1001,
  "metadata": {},
  "downloadUrl": "example-value",
  "downloadUrlExpiresAt": "2024-01-15T09:30:00Z",
  "createdAt": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | Server-assigned attachment (document) ID. |
| patientId | Long | Yes | ID of the patient the attachment belongs to. |
| documentType | String | No | The category of document. |
| name | String | No | Display name. |
| active | Boolean | No | Whether the attachment is active. Deactivated attachments are retained but have no download URL. |
| contentType | String | No | MIME type of the file. |
| sizeBytes | Long | No | Size of the file in bytes. |
| metadata | Map<String, Object> | Yes | Arbitrary structured key/value metadata stored with the file. Populated only on the single-item read. |
| downloadUrl | String | No | Time-limited signed URL for downloading the file. |
| downloadUrlExpiresAt | LocalDateTime | No | When the signed download URL expires (UTC). |
| createdAt | LocalDateTime | No | When the attachment was created (UTC). |

### Example

```bash
curl -X GET "https://demo.1health.io/api/v3/patient/1001/attach/1001" \
  -H "Authorization: Bearer $TOKEN"
```

## DELETE /v3/patient/{patientId}/attach/{documentId}

Deactivate a patient attachment

### Overview

Soft-deletes an attachment: it is marked deleted and excluded from the list. The file is retained for compliance purposes. Requires authentication.

### Authorization

Bearer JWT required. See the [authentication guide](https://agents.1health.io/public/demo/api/authentication/agents.md).

### Path Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| patientId | Long | Yes | The ID of the patient. |
| documentId | Long | Yes | The ID of the attachment. |

### Responses

#### 200 OK

Attachment deactivated successfully.

**DTO**: `PatientAttachmentDeleteResponseDTO`

```json
{
  "id": 1001,
  "active": true,
  "deletedAt": "2024-01-15T09:30:00Z"
}
```

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| id | Long | No | ID of the deactivated attachment. |
| active | boolean | No | Whether the attachment is active. |
| deletedAt | LocalDateTime | No | Timestamp when the attachment was deactivated (UTC). |

### Example

```bash
curl -X DELETE "https://demo.1health.io/api/v3/patient/1001/attach/1001" \
  -H "Authorization: Bearer $TOKEN"
```

---

## Navigation
Parent: https://agents.1health.io/public/demo/api/v3/patient/_patientId_/agents.md · Site guide: https://agents.1health.io/public/demo/api/agents.md