Patient Vault — 1health

Attach

/v3/patient/{patientId}/attach endpoint reference.

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.

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

{
  "attachments": [
    {}
  ]
}

Field	Type	Nullable	Description
attachments	List	No	The patient's attachment records.

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. Requires authentication.

Authorization

Bearer JWT required. See the authentication guide.

Path Parameters

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

Request Body

Content-Type: application/json · DTO: PatientAttachmentRequestDTO

{
  "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

{
  "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

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.

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

{
  "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

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.

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

{
  "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

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.

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

{
  "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

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

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

Attach

Endpoints

GET/v3/patient/{patientId}/attach

Overview

Authorization

Path Parameters

Query Parameters

Responses

200 OK

Example

POST/v3/patient/{patientId}/attach

Overview

Authorization

Path Parameters

Request Body

Responses

201 Created

Example

POST/v3/patient/{patientId}/attach

Overview

Authorization

Path Parameters

Request Body

Responses

201 Created

Example

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

Overview

Authorization

Path Parameters

Responses

200 OK

Example

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

Overview

Authorization

Path Parameters

Responses

200 OK

Example

Navigation