Skip to content
Hermes Health API
GuidesOpenAPI spec

Endpoints

Project 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}/{filename}

Download a project file

Returns a short-lived presigned downloadUrl for the named project file; fetch the file from that URL before expiresIn seconds elapse. This call is read-only. Returns 404 when the project does not exist or is not visible to the caller.

Parameters

  • filenamestringpath, required

    The project file's name, a single path segment.

ReturnsSuccess

Returns The file object.

Errors

401404500

PUT/v0/companies/{company_id}/projects/{project_id}/{filename}

Upload a project file

Returns a short-lived presigned uploadUrl, plus any uploadHeaders to send with it; PUT the file bytes to that URL before expiresIn seconds elapse. Uploading to a name that already exists replaces that file. A name that is empty or contains a slash, backslash, double quote, semicolon, or control character is rejected with 400.

Parameters

  • filenamestringpath, required

    The name to store the file under, a single path segment.

ReturnsSuccess

Returns The file object.

Errors

400401404500

DELETE/v0/companies/{company_id}/projects/{project_id}/{filename}

Delete a project file

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

Parameters

  • filenamestringpath, required

    The project file's name, a single path segment.

ReturnsSuccess

Errors

401404500

HEAD/v0/companies/{company_id}/projects/{project_id}/{filename}

Check a project file's status

Returns the x-progress and x-etag headers without transferring the file, so you can poll whether an upload has finished processing before downloading it.

Parameters

  • filenamestringpath, required

    The project file's name, a single path segment.

ReturnsFile metadata headers

Errors

401404500