Skip to main content
PATCH
Update a sample
Atomically updates any combination of the sample’s display name, complete tag set, and isotropic microns-per-pixel value. Returns the full owned sample detail, including inference-job history. API keys use their existing organization access. OAuth access tokens must include both samples:read and samples:write, because the response contains read-only sample and job data. The tags array accepts at most 1,000 raw items. Values are trimmed and lowercased, duplicate normalized values collapse, and the resulting set may contain at most 50 distinct tags. When mpp is supplied and the effective value is countable, Strand enqueues a tissue recount even if the stored MPP is unchanged. If the update returns 500 because the recount could not be enqueued, the sample update has committed; retry the identical PATCH to enqueue the missing recount safely.

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]*$
tags
string[]

Complete desired tag set, with a transport-safety limit of 1,000 raw items. Each value is trimmed/lowercased, then must be 1–50 characters with no commas or NUL characters; duplicates collapse after normalization and at most 50 distinct normalized tags are allowed.

Maximum array length: 1000
Pattern: ^[^\u0000]*$
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
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.

tags
string[]
required

The sample's canonical tag strings, sorted alphabetically.

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