Patient Vault v3 API

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

---

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. Behavior & Use Cases: - Soft-deleted attachments are excluded - Filter by documentType (e.g. lab_result) Important Notes: - Requires authentication

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Query Parameters

Responses

200 OK

List of patient attachments.

DTO: PatientAttachmentListResponseDTO

{
  "attachments": "example-value"
}

Example

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. Returns a server-assigned documentId and a signed download URL. Behavior & Use Cases: - Parts: file (required binary) plus form fields documentType (required), name (optional) and metadata (optional JSON object) - name defaults to the uploaded filename when omitted - Not idempotent — each call creates a new attachment with its own documentId - Signed download URLs are short-lived; re-fetch the attachment to refresh Important Notes: - Requires authentication

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Request Body

Content-Type: application/json · DTO: PatientAttachmentRequestDTO

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

Responses

201 Created

Attachment stored successfully.

DTO: PatientAttachmentResponseDTO

{
  "id": "example-value",
  "patientId": "example-value",
  "documentType": "example-value",
  "name": "example-value",
  "active": true,
  "contentType": "example-value",
  "sizeBytes": "example-value",
  "metadata": "example-value",
  "downloadUrl": "example-value",
  "downloadUrlExpiresAt": "example-value",
  "createdAt": "example-value"
}

Example

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. Returns a server-assigned documentId and a signed download URL. Behavior & Use Cases: - Parts: file (required binary) plus form fields documentType (required), name (optional) and metadata (optional JSON object) - name defaults to the uploaded filename when omitted - Not idempotent — each call creates a new attachment with its own documentId - Signed download URLs are short-lived; re-fetch the attachment to refresh Important Notes: - Requires authentication

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Request Body

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

Responses

201 Created

Attachment stored successfully.

DTO: PatientAttachmentResponseDTO

{
  "id": "example-value",
  "patientId": "example-value",
  "documentType": "example-value",
  "name": "example-value",
  "active": true,
  "contentType": "example-value",
  "sizeBytes": "example-value",
  "metadata": "example-value",
  "downloadUrl": "example-value",
  "downloadUrlExpiresAt": "example-value",
  "createdAt": "example-value"
}

Example

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. Important Notes: - Requires authentication - Returns 404 if no active attachment with that id exists for the patient; deactivated attachments are not retrievable

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Responses

200 OK

Attachment found.

DTO: PatientAttachmentResponseDTO

{
  "id": "example-value",
  "patientId": "example-value",
  "documentType": "example-value",
  "name": "example-value",
  "active": true,
  "contentType": "example-value",
  "sizeBytes": "example-value",
  "metadata": "example-value",
  "downloadUrl": "example-value",
  "downloadUrlExpiresAt": "example-value",
  "createdAt": "example-value"
}

Example

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. Important Notes: - Requires authentication - Operates only on an active attachment; deleting one that is already deactivated (or does not exist) returns 404

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

Responses

200 OK

Attachment deactivated successfully.

DTO: PatientAttachmentDeleteResponseDTO

{
  "id": "example-value",
  "active": true,
  "deletedAt": "example-value"
}

Example

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