Skip to content
Hermes Health API
GuidesOpenAPI spec

Endpoints

Record request files

The file object

Unified file response covering both read (downloadUrl, extraction, verdicts, loose files) and write (uploadUrl, uploadHeaders) halves. Fields are populated based on the S3 helper invoked: `presigned_read` leaves the write fields empty, `presigned_write` leaves the read fields empty, and `presigned_read_write` populates both.

Attributes

  • uploadHeadersobject

    Extra headers to send with the upload. Normally empty.

  • expiresIninteger

    How long the URLs in this object stay valid, in seconds from when they were issued. Fetch a fresh object rather than caching one.

  • looseFilesobject[]

    Other files stored under this file's location that are not part of its own document set, such as separately uploaded scans, each with its own short-lived download URL. Empty when there are none or when this response only offers an upload.

  • looseFiles[].urlstring

    Short-lived presigned URL to download the file.

  • looseFiles[].fileNamestring

    The name a reader sees. For a record request's deliverables this is the unique name the shared presentation assigned (see `DeliverableView`), so it can differ from the object's own basename when two returns brought the same file name; everywhere else it IS the basename.

  • looseFiles[].keystring

    The file's full storage path, `/`-separated.

  • looseFiles[].sizeinteger

    The file's size in bytes.

  • looseFiles[].lastModifiedstring

    When the file was last written.

Conditional attributes

  • downloadUrlstring

    Short-lived presigned URL to download the file. Null when no file is stored yet, or when this response only offers an upload.

  • uploadUrlstring

    Short-lived presigned URL to upload the file: `PUT` the raw bytes to it exactly as issued, with no `Authorization` header. Uploading again replaces the file. Null when this response only offers a download.

  • extractionobject

    The document's extraction (form data under `data`, plus text and page count). Null for non-auth-check files.

  • verdictsobject

    The auth-check verdicts derived from `extraction`. Null for non-auth-check files or when the document hasn't been analyzed.

  • verdictCountsobject

    Tally of `verdicts` by status, a readability convenience for API consumers. Null exactly when `verdicts` is null.

  • embedTokenstring

    Standalone auth-check embed token, pre-minted on the upload path when the caller supplies patient context alongside the request for an upload URL. Equivalent to the token from `POST /v0/auth-check/<filename>/embed-token`, saving that round-trip. Null when no patient context was supplied.

  • looseFiles[].folderstring

    The display folder this file sits in, `/`-joined, relative to the listing root. Populated only where a listing presents a tree — a record request's deliverables — and omitted from the payload otherwise.

  • looseFiles[].uploadedByobject | object | object | object | object | object | object | object | object | object | object

    Who or what placed this file. Absent for older files recorded without attribution.

  • uploadedByobject | object | object | object | object | object | object | object | object | object | object

    Who or what placed this file. Absent when no attribution was recorded or when this endpoint does not report it.

GET/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/deliverables

List a record request's deliverables

Lists every deliverable returned for the record request as one flat tree, sorted by name. Each file carries the unique name the download, status and delete calls address it by, and the folder it displays under, if any.

ReturnsSuccess

  • filesobject[]

    The files stored at the listed location, each with its own short-lived download URL. Empty when there are none.

  • files[].urlstring

    Short-lived presigned URL to download the file.

  • files[].fileNamestring

    The name a reader sees. For a record request's deliverables this is the unique name the shared presentation assigned (see `DeliverableView`), so it can differ from the object's own basename when two returns brought the same file name; everywhere else it IS the basename.

  • files[].keystring

    The file's full storage path, `/`-separated.

  • files[].sizeinteger

    The file's size in bytes.

  • files[].lastModifiedstring

    When the file was last written.

Conditional attributes

  • files[].folderstring

    The display folder this file sits in, `/`-joined, relative to the listing root. Populated only where a listing presents a tree — a record request's deliverables — and omitted from the payload otherwise.

  • files[].uploadedByobject | object | object | object | object | object | object | object | object | object | object

    Who or what placed this file. Absent for older files recorded without attribution.

Errors

400401403404500

GET/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/deliverables/{filename}

Download a deliverable

Returns a short-lived presigned downloadUrl for the deliverable; fetch the file from that URL before expiresIn seconds elapse. filename is the name the deliverables listing shows, which is unique across the request and not always the stored file name.

Parameters

  • filenamestringpath, required

    The deliverable's name as the deliverables listing shows it.

ReturnsSuccess

Returns The file object.

Errors

400401403404500

DELETE/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/deliverables/{filename}

Delete a deliverable

filename is the name the listing shows. The flattened tree makes that unique across the request, so it is not always the stored basename.

Parameters

  • filenamestringpath, required

    The deliverable's name as the deliverables listing shows it.

ReturnsSuccess

Errors

400401403404500

HEAD/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/deliverables/{filename}

Check a deliverable's status

Returns the x-progress and x-etag headers without transferring the file. Poll this before downloading a large deliverable.

Parameters

  • filenamestringpath, required

    The deliverable's name as the deliverables listing shows it.

ReturnsFile metadata headers

Errors

400401403404500

PATCH/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/deliverables/{path}

Rename a deliverable

The path segment is the deliverable’s full path within the flattened tree, not just its leaf. Renaming changes the leaf only.

Parameters

  • pathstringpath, required

    The deliverable's full path within the deliverables tree, which may span several segments; the last segment is the file name being renamed.

Request bodyapplication/json

  • newFilenamestring

    The new file name. Any directory part is dropped and surrounding whitespace is trimmed. The name must not be empty, start with a dot, contain `"`, `;`, `\` or control characters, or exceed 255 bytes, or the call fails with `400`.

ReturnsSuccess

Errors

400401403404500

GET/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/documents

List a record request's documents

Lists the files in the record request’s documents folder. Returns 404 when the record request does not exist or is not visible to the caller.

ReturnsSuccess

  • filesobject[]

    The files stored at the listed location, each with its own short-lived download URL. Empty when there are none.

  • files[].urlstring

    Short-lived presigned URL to download the file.

  • files[].fileNamestring

    The name a reader sees. For a record request's deliverables this is the unique name the shared presentation assigned (see `DeliverableView`), so it can differ from the object's own basename when two returns brought the same file name; everywhere else it IS the basename.

  • files[].keystring

    The file's full storage path, `/`-separated.

  • files[].sizeinteger

    The file's size in bytes.

  • files[].lastModifiedstring

    When the file was last written.

Conditional attributes

  • files[].folderstring

    The display folder this file sits in, `/`-joined, relative to the listing root. Populated only where a listing presents a tree — a record request's deliverables — and omitted from the payload otherwise.

  • files[].uploadedByobject | object | object | object | object | object | object | object | object | object | object

    Who or what placed this file. Absent for older files recorded without attribution.

Errors

400401403404500

GET/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/documents/{filename}

Download a record request document

Returns a short-lived presigned downloadUrl for the named document; fetch the file from that URL before expiresIn seconds elapse. This call is read-only and never returns an upload URL. Returns 404 when the record request does not exist or is not visible to the caller.

Parameters

  • filenamestringpath, required

    The document's file name within the record request's documents folder.

ReturnsSuccess

Returns The file object.

Errors

400401403404500

PUT/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/documents/{filename}

Mint an upload URL for a record request document

GET on the same path is read-only, so a caller holding only ViewRecordRequests never receives an upload URL; minting requires UploadProviderPacket.

Parameters

  • filenamestringpath, required

    The file name to upload under, within the record request's documents folder.

ReturnsSuccess

Returns The file object.

Errors

400401403404500

PATCH/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/documents/{filename}

Rename a record request document

Renames the leaf only; the document stays in the same record request.

Parameters

  • filenamestringpath, required

    The current file name of the document to rename, within the record request's documents folder.

Request bodyapplication/json

  • newFilenamestring

    The new file name. Any directory part is dropped and surrounding whitespace is trimmed. The name must not be empty, start with a dot, contain `"`, `;`, `\` or control characters, or exceed 255 bytes, or the call fails with `400`.

ReturnsSuccess

Errors

400401403404500

DELETE/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/documents/{filename}

Delete a record request document

Permanently deletes the named file from the record request’s documents folder. Returns 404 when the record request does not exist or is not visible to the caller.

Parameters

  • filenamestringpath, required

    The document's file name within the record request's documents folder.

ReturnsSuccess

Errors

400401403404500

HEAD/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/documents/{filename}

Check a document's status

Returns the x-progress and x-etag headers without transferring the file.

Parameters

  • filenamestringpath, required

    The document's file name within the record request's documents folder.

ReturnsFile metadata headers

Errors

400401403404500

GET/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/{filename}

Download a record request attachment

Returns a short-lived presigned downloadUrl for the named file stored directly on the record request; fetch the file from that URL before expiresIn seconds elapse. This call is read-only and never returns an upload URL. Returns 404 when the record request does not exist or is not visible to the caller.

Parameters

  • filenamestringpath, required

    The attachment's file name, stored directly on the record request.

ReturnsSuccess

Returns The file object.

Errors

400401403404500

DELETE/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/{filename}

Delete a record request attachment

Permanently deletes the named file stored directly on the record request. Returns 404 when the record request does not exist or is not visible to the caller.

Parameters

  • filenamestringpath, required

    The attachment's file name, stored directly on the record request.

ReturnsSuccess

Errors

400401403404500

HEAD/v0/companies/{company_id}/projects/{project_id}/patients/{patient_id}/record-requests/{record_request_id}/{filename}

Check an attachment's status

Returns the x-progress and x-etag headers without transferring the file.

Parameters

  • filenamestringpath, required

    The attachment's file name, stored directly on the record request.

ReturnsFile metadata headers

Errors

400401403404500