/

Browse the documentation

API reference · Core resources

Uploaded files

Files attached to a consultation, such as lab results or referral letters. Vetnio extracts their content so it can be used when generating documents.

Guides:Attach files to a consultation

The uploaded file object

A file attached to a consultation — typically lab results, imaging, or prior medical history provided by the vet or pet owner. Vetnio extracts the content in the background so it can be referenced by the AI scribe and chat features.

Attributes

fileNamestringrequired
Stable internal identifier for the file — a server-generated UUID returned by initUpload. Used in every subsequent endpoint (finalize, download, delete). Not intended for display; use originalFileName for that.
at least 1 characters
originalFileNamestringrequired
The file name as it was on the uploader's device. Shown to users in the UI. May contain characters that are unsafe for object-storage keys, which is why it is never used as a storage identifier.
at least 1 characters
mimeTypestringrequired
MIME type as recorded at upload time.
sizeBytesintegerrequired
Exact size of the file in bytes. finalizeUpload compares it with the size of the uploaded object and returns 412 until they match, so it must equal the number of bytes you PUT. No maximum is enforced by the API.
> 0 · ≤ 9007199254740991
statusenumrequired
Lifecycle state of the file:
- uploaded — the upload slot was reserved by initUpload; the bytes may not have been sent yet and no extraction has started. Call finalizeUpload after the PUT.
- analyzing — extraction is running in the background (usually seconds; longer for large PDFs).
- analyzed — extraction succeeded; the extracted text is available to document generation and chat features.
- failed — extraction errored; inspect errorMessage. Calling finalizeUpload again retries the extraction.
createdAtstringrequired
When the upload was initialized, as an ISO-8601 UTC timestamp. Does not reflect when the bytes arrived or when analysis completed.
errorMessagestringrequirednullable
Human-readable error from the content extractor. Populated only when status is failed, otherwise null.

The uploaded file object

{
  "fileName": "8f1c4a60-7e3b-4b6f-9a9d-6d9f3c8b2e4a",
  "originalFileName": "xray_bella_2024-06-12.pdf",
  "mimeType": "application/pdf",
  "sizeBytes": 184320,
  "status": "analyzed",
  "createdAt": "2026-09-14T08:42:10.000Z",
  "errorMessage": "string"
}

Initialize a file upload

POST/workspaces/{workspaceId}/consultations/{consultationId}/uploaded-files

Reserves a slot for a new file in the consultation and returns a short-lived presigned S3 URL. Three-step flow:

Call this endpoint to get uploadUrl and fileName.
PUT the file bytes directly to uploadUrl.
Call finalizeUpload with the same fileName to start content extraction, then poll GET .../uploaded-files until the status is analyzed or failed.

De-duplication is by SHA-256: a second initUpload with the same sha256 in the same consultation returns 409 CONFLICT, including when the first upload was never completed (delete that file first to retry). The slot is created immediately with status uploaded. If URL generation fails after the slot is created, the slot is removed so the client can safely retry. Returns 403 for archived consultations.

AcceptsPersonal key

Path parameters

workspaceIdstringrequired
Opaque identifier of the Vetnio workspace (veterinary clinic) that owns the resource. Scopes every request — callers can only access files under workspaces they are a member of.
consultationIdstringrequired
Identifier of the consultation (a single veterinary visit) the file is attached to. The consultation must belong to the same workspace as the authenticated caller.

Request body

originalFileNamestringrequired
The file name as it was on the uploader's device. Shown to users in the UI. May contain characters that are unsafe for object-storage keys, which is why it is never used as a storage identifier.
at least 1 characters
sha256stringrequired
Hexadecimal SHA-256 digest (64 characters) of the exact bytes you will upload, computed client-side. Used only for de-duplication: a consultation cannot hold two files with the same digest, so a second initUpload with the same value returns 409 CONFLICT. Vetnio does not verify that the uploaded bytes match it.
matches `^[a-f0-9]{64}$`
mimeTypeenumrequired
MIME type of the file. Restricted to the formats Vetnio can analyze: PDF, images (PNG / JPEG / WebP / GIF), plain text, CSV, Word (.docx), and Excel (.xlsx / .xls). Other values are rejected with 400. Not checked against the uploaded bytes, so send the real type: it decides how the content is extracted.
Possible values:application/pdfimage/pngimage/jpegimage/webpimage/giftext/csvtext/plainapplication/vnd.openxmlformats-officedocument.wordprocessingml.documentapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheetapplication/vnd.ms-excel
sizeBytesintegerrequired
Exact size of the file in bytes. finalizeUpload compares it with the size of the uploaded object and returns 412 until they match, so it must equal the number of bytes you PUT. No maximum is enforced by the API.
> 0 · ≤ 9007199254740991

Returns

uploadUrlstring (uri)required
Presigned S3 URL valid for 1 hour. PUT the raw file bytes (no multipart form) to this URL before it expires. If it lapses, delete this file and call initUpload again; a second initUpload with the same sha256 returns 409 while this slot exists.
s3Keystringrequired
Internal S3 object key where the file will live. Exposed for debugging only — clients should not depend on its format or attempt to access S3 directly with it.
fileNamestringrequired
Stable internal identifier for the file — a server-generated UUID returned by initUpload. Used in every subsequent endpoint (finalize, download, delete). Not intended for display; use originalFileName for that.
at least 1 characters

Errors

400: The request is malformed or failed validation.
401: The API key is missing, invalid or revoked.
403: The key is valid but may not perform this action on this resource.
500: Something went wrong on Vetnio's side.

Request

curl -X POST "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files" \
  -H "Authorization: Bearer $VETNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "originalFileName": "bella-haematology.txt",
  "sha256": "d57a006e8a0e77c47f3078d39431b871a44eefd7cb7a3ca63c6ac4f436cb0845",
  "mimeType": "text/plain",
  "sizeBytes": 96
}'

Response

{
  "uploadUrl": "https://storage.example.com/consultationInformation/demo-north-clinic/uploadedFiles/bc0cf418-6503-46eb-9828-c83f8c193426/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f?X-Amz-Expires=3600&X-Amz-Signature=…",
  "s3Key": "consultationInformation/demo-north-clinic/uploadedFiles/bc0cf418-6503-46eb-9828-c83f8c193426/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f",
  "fileName": "472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f"
}

List uploaded files for a consultation

GET/workspaces/{workspaceId}/consultations/{consultationId}/uploaded-files

Returns every file attached to a consultation, newest first (by createdAt). Each file carries its current analysis status and, when extraction failed, the error message. Use this endpoint to render a file list or to poll for the analyzing → analyzed transition after finalizeUpload. Files whose upload was initialized but never finalized are listed with status uploaded. Any member of the workspace can list the files.

AcceptsPersonal key

Path parameters

workspaceIdstringrequired
Opaque identifier of the Vetnio workspace (veterinary clinic) that owns the resource. Scopes every request — callers can only access files under workspaces they are a member of.
consultationIdstringrequired
Identifier of the consultation (a single veterinary visit) the file is attached to. The consultation must belong to the same workspace as the authenticated caller.

Returns

[ ]array of objectsrequired
Show child attributes
- fileNamestringrequired
  Stable internal identifier for the file — a server-generated UUID returned by initUpload. Used in every subsequent endpoint (finalize, download, delete). Not intended for display; use originalFileName for that.
  at least 1 characters
- originalFileNamestringrequired
  The file name as it was on the uploader's device. Shown to users in the UI. May contain characters that are unsafe for object-storage keys, which is why it is never used as a storage identifier.
  at least 1 characters
- mimeTypestringrequired
  MIME type as recorded at upload time.
- sizeBytesintegerrequired
  Exact size of the file in bytes. finalizeUpload compares it with the size of the uploaded object and returns 412 until they match, so it must equal the number of bytes you PUT. No maximum is enforced by the API.
  > 0 · ≤ 9007199254740991
- statusenumrequired
  Lifecycle state of the file:
  
  uploaded — the upload slot was reserved by initUpload; the bytes may not have been sent yet and no extraction has started. Call finalizeUpload after the PUT.
  
  analyzing — extraction is running in the background (usually seconds; longer for large PDFs).
  
  analyzed — extraction succeeded; the extracted text is available to document generation and chat features.
  
  failed — extraction errored; inspect errorMessage. Calling finalizeUpload again retries the extraction.
- createdAtstringrequired
  When the upload was initialized, as an ISO-8601 UTC timestamp. Does not reflect when the bytes arrived or when analysis completed.
- errorMessagestringrequirednullable
  Human-readable error from the content extractor. Populated only when status is failed, otherwise null.

Errors

400: The request is malformed or failed validation.
401: The API key is missing, invalid or revoked.
403: The key is valid but may not perform this action on this resource.
404: The resource does not exist or is not visible to this key.
500: Something went wrong on Vetnio's side.

Request

curl "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files" \
  -H "Authorization: Bearer $VETNIO_API_KEY"

Response

[
  {
    "fileName": "472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f",
    "originalFileName": "bella-haematology.txt",
    "mimeType": "text/plain",
    "sizeBytes": 96,
    "status": "analyzed",
    "createdAt": "2026-10-04T16:07:20.387Z",
    "errorMessage": null
  }
]

Delete an uploaded file

DELETE/workspaces/{workspaceId}/consultations/{consultationId}/uploaded-files/{fileName}

Removes the file and its extracted analysis text from S3, then deletes the database row. Idempotent — deleting a file that no longer exists still returns ok: true. If any S3 object fails to delete, the call returns 500 and the database row is preserved so the delete can be retried without leaking orphaned storage.

AcceptsPersonal key

Path parameters

workspaceIdstringrequired
Opaque identifier of the Vetnio workspace (veterinary clinic) that owns the resource. Scopes every request — callers can only access files under workspaces they are a member of.
consultationIdstringrequired
Identifier of the consultation (a single veterinary visit) the file is attached to. The consultation must belong to the same workspace as the authenticated caller.
fileNamestringrequired
Stable internal identifier for the file — a server-generated UUID returned by initUpload. Used in every subsequent endpoint (finalize, download, delete). Not intended for display; use originalFileName for that.
at least 1 characters

Returns

okbooleanrequired
Always true on success.

Errors

400: The request is malformed or failed validation.
401: The API key is missing, invalid or revoked.
403: The key is valid but may not perform this action on this resource.
404: The resource does not exist or is not visible to this key.
500: Something went wrong on Vetnio's side.

Request

curl -X DELETE "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f" \
  -H "Authorization: Bearer $VETNIO_API_KEY"

Response

{
  "ok": true
}

Get a download URL for an uploaded file

GET/workspaces/{workspaceId}/consultations/{consultationId}/uploaded-files/{fileName}/download-url

Returns a short-lived presigned URL the client can use to download the file directly from S3, bypassing the Vetnio API. Prefer this over streaming the file through the API — it keeps latency low and avoids large-payload bandwidth on our servers.

AcceptsPersonal key

Path parameters

workspaceIdstringrequired
Opaque identifier of the Vetnio workspace (veterinary clinic) that owns the resource. Scopes every request — callers can only access files under workspaces they are a member of.
consultationIdstringrequired
Identifier of the consultation (a single veterinary visit) the file is attached to. The consultation must belong to the same workspace as the authenticated caller.
fileNamestringrequired
Stable internal identifier for the file — a server-generated UUID returned by initUpload. Used in every subsequent endpoint (finalize, download, delete). Not intended for display; use originalFileName for that.
at least 1 characters

Returns

urlstring (uri)required
Presigned S3 URL valid for 1 hour that lets the client GET the original file bytes. Call this endpoint again to obtain a fresh URL if it expires.
originalFileNamestringrequired
The file name as it was on the uploader's device. Shown to users in the UI. May contain characters that are unsafe for object-storage keys, which is why it is never used as a storage identifier.
at least 1 characters
mimeTypestringrequired
MIME type as recorded at upload time — use this for the Content-Type response header when serving the download to the end user.

Errors

400: The request is malformed or failed validation.
401: The API key is missing, invalid or revoked.
403: The key is valid but may not perform this action on this resource.
404: The resource does not exist or is not visible to this key.
500: Something went wrong on Vetnio's side.

Request

curl "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f/download-url" \
  -H "Authorization: Bearer $VETNIO_API_KEY"

Response

{
  "url": "https://storage.example.com/consultationInformation/demo-north-clinic/uploadedFiles/bc0cf418-6503-46eb-9828-c83f8c193426/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f?X-Amz-Expires=3600&X-Amz-Signature=…",
  "originalFileName": "bella-haematology.txt",
  "mimeType": "text/plain"
}

Finalize a file upload and trigger analysis

POST/workspaces/{workspaceId}/consultations/{consultationId}/uploaded-files/{fileName}/finalize

Confirms that the bytes were uploaded and starts background content extraction (status becomes analyzing). Only call this after the PUT to the presigned URL has completed: the API checks that the stored object exists and has exactly sizeBytes bytes, and returns 412 PRECONDITION_FAILED until it does.

Safe to call multiple times: if the file is already analyzing or analyzed, the call does nothing and still returns ok: true. If the file is failed, calling it again retries extraction. Extraction runs after the response: Excel, CSV, plain-text and Word files are converted locally; PDFs go through OCR and images are described by an AI model. Poll GET .../uploaded-files for the result.

AcceptsPersonal key

Path parameters

workspaceIdstringrequired
Opaque identifier of the Vetnio workspace (veterinary clinic) that owns the resource. Scopes every request — callers can only access files under workspaces they are a member of.
consultationIdstringrequired
Identifier of the consultation (a single veterinary visit) the file is attached to. The consultation must belong to the same workspace as the authenticated caller.
fileNamestringrequired
Stable internal identifier for the file — a server-generated UUID returned by initUpload. Used in every subsequent endpoint (finalize, download, delete). Not intended for display; use originalFileName for that.
at least 1 characters

Returns

okbooleanrequired
Always true on success.

Errors

400: The request is malformed or failed validation.
401: The API key is missing, invalid or revoked.
403: The key is valid but may not perform this action on this resource.
500: Something went wrong on Vetnio's side.

Request

curl -X POST "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f/finalize" \
  -H "Authorization: Bearer $VETNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response

{
  "ok": true
}

{ "fileName": "8f1c4a60-7e3b-4b6f-9a9d-6d9f3c8b2e4a", "originalFileName": "xray_bella_2024-06-12.pdf", "mimeType": "application/pdf", "sizeBytes": 184320, "status": "analyzed", "createdAt": "2026-09-14T08:42:10.000Z", "errorMessage": "string" }

curl -X POST "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files" \ -H "Authorization: Bearer $VETNIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "originalFileName": "bella-haematology.txt", "sha256": "d57a006e8a0e77c47f3078d39431b871a44eefd7cb7a3ca63c6ac4f436cb0845", "mimeType": "text/plain", "sizeBytes": 96 }'

{ "uploadUrl": "https://storage.example.com/consultationInformation/demo-north-clinic/uploadedFiles/bc0cf418-6503-46eb-9828-c83f8c193426/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f?X-Amz-Expires=3600&X-Amz-Signature=…", "s3Key": "consultationInformation/demo-north-clinic/uploadedFiles/bc0cf418-6503-46eb-9828-c83f8c193426/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f", "fileName": "472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f" }

[ { "fileName": "472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f", "originalFileName": "bella-haematology.txt", "mimeType": "text/plain", "sizeBytes": 96, "status": "analyzed", "createdAt": "2026-10-04T16:07:20.387Z", "errorMessage": null } ]

curl -X DELETE "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f" \ -H "Authorization: Bearer $VETNIO_API_KEY"

curl "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f/download-url" \ -H "Authorization: Bearer $VETNIO_API_KEY"

{ "url": "https://storage.example.com/consultationInformation/demo-north-clinic/uploadedFiles/bc0cf418-6503-46eb-9828-c83f8c193426/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f?X-Amz-Expires=3600&X-Amz-Signature=…", "originalFileName": "bella-haematology.txt", "mimeType": "text/plain" }

curl -X POST "https://vetnio.com/api/v2/workspaces/demo-north-clinic/consultations/bc0cf418-6503-46eb-9828-c83f8c193426/uploaded-files/472d4fb2-e3b6-4c8b-a776-27bdc59ebd2f/finalize" \ -H "Authorization: Bearer $VETNIO_API_KEY" \ -H "Content-Type: application/json" \ -d '{}'