Skip to main content
PATCH
Update a sample
Atomically updates any combination of an owned sample’s display name, unified field values, and isotropic microns-per-pixel value. The response is the full owned sample detail, including inference-job history. fields is keyed by stable definition key. Each supplied value replaces that field’s complete value; null clears it. This payload replaces Tags:
Tags values are trimmed and lowercased, duplicates collapse, each value must be between 1 and 50 characters without commas or control characters, and a sample may carry at most 50 distinct Tags values. Public is readable through fields.public but is not writable through this endpoint; publication uses its protected flow. Use GET /sample-fields to discover keys, value types, origin, storage, and writability. The retired top-level tags property is rejected with HTTP 400.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

id
string<uuid>
required

Body

application/json
name
string | null

Trimmed display name. Null or an empty string reverts to filename. NUL characters are rejected.

Maximum string length: 200
Pattern: ^[^\u0000]*$
fields
object

Complete values for the named fields, not deltas. Null clears a field. fields.tags is the complete desired tag set; fields.public is read-only and returns 403.

mpp

User-reported microns per pixel. Object axes must be equal; anisotropic input is rejected.

Required range: 0 < x <= 100

Response

Updated owned sample detail

An owned sample's curated read model and its 50 newest inference jobs. jobCount is the uncapped total.

ownership
enum<string>
required
Available options:
mine
id
string<uuid>
required
appUrl
string<uri>
required

Canonical browser URL for this owned sample.

name
string | null
required

Human-friendly display name, or null if unset (falls back to filename).

filename
string
required

Original uploaded filename.

status
string
required

Lifecycle status: uploading, upload_failed, deid_running, deid_failed, preprocessing, ready, or preprocess_failed.

fileSize
string
required

Uploaded file size in bytes (string-encoded 64-bit integer).

widthPx
integer | null
required

Level-0 width in pixels, or null before the dimensions probe completes.

heightPx
integer | null
required

Level-0 height in pixels, or null before the dimensions probe completes.

mpp
number | null
required

Effective isotropic microns per pixel (user override → calibrated slide value), or null when the sample has no usable scale yet.

fields
object
required

Unified field values keyed by stable definition key. Tags is a string array at tags; Public is a boolean at public. Values are validated against the organization's definitions.

createdAt
string<date-time> | null
required
expiresAt
string<date-time> | null
required

When the sample moves to Trash. Null when it never expires.

expiresAtSource
enum<string> | null
required

org_default = derived from the org policy at upload time. custom = set by an explicit expiration call (a date or a never-expire pin). Null when the sample has no expiration and no org policy applies.

Available options:
org_default,
custom,
null
expiresInDays
integer | null
required

Whole days until expiry, clamped at 0 for a sample at/past its date but not yet swept. Null when the sample never expires.

willExpire
boolean
required

True when the sample has an expiration date set.

trashedAt
string<date-time> | null
required

When the sample entered Trash, or null if it is still active. Trashed samples are permanently deleted 7 days after this time.

jobs
object[]
required
Maximum array length: 50
jobCount
integer
required

Total inference-job count for the sample before the 50-job cap.

Required range: x >= 0
segmentation
object
required