Skip to navigation
APIsStudy ResourcesStudy Samples

Update samples

Updates between 1 and 100 samples on the study. The request is validated as a whole; if any item is invalid, none are updated.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Path parameters

studyIdstringRequiredformat: "^sdy_[a-zA-Z0-9]{10,22}$"
The unique identifier of the study.

Headers

X-Studies-Api-VersionstringOptional

Request

The changes to apply to each sample.
idstringRequiredformat: "^spl_[a-zA-Z0-9]{10,22}$"
The sample to update. Must be on the study.
sample_idstringOptional1-255 characters

The human-readable identifier written on the sample. Must be unique across your team and within the request.

statusenum or nullOptional

The new status. Only collected and planned are accepted, and null leaves the status unchanged. Moving to collected requires collected_at, either already set or sent in the same item; planned rejects it.

Allowed values:
collected_atstring or nullOptional>=1 character

When the sample was collected, as a full ISO-8601 UTC date-time: either an explicit UTC instant (offset Z or +00:00) or an offset-less date-time taken as UTC. Date-only values and non-UTC offsets are rejected. May not be before the animal’s date of birth. Null is accepted only while the sample has no collection time, and changes nothing.

timepointstring or nullOptional

When the sample is due relative to the study schedule, as an ISO-8601 duration such as P1D or PT4H, optionally negative. For a sample from a definition it must be one of the definition’s timepoints; otherwise its magnitude must be zero or between 1 minute and 365 days. Null clears it.

commentsstring or nullOptional<=255 characters
A comment recorded against the sample. Null clears it.
detailslist of objects or nullOptional

Replaces the sample’s measured attributes; null clears them. Each key must be valid for the sample type and appear once, a non-null value must be a non-negative number and needs a unit, and a unit already recorded for a key cannot change.

metadatamap from strings to any or nullOptional

Custom fields merged into the existing metadata, keyed by your team’s active sample metadata glossary slugs. Set an individual value to null to delete that key; keys your team marks mandatory cannot be deleted. Multi-select values must be arrays.

Response headers

X-RateLimit-LimitintegerOptional
The number of requests permitted in the current rate limit window.
X-RateLimit-RemainingintegerOptional

The number of requests still available in the current rate limit window. When several limits apply, this reflects the per-API-key limit, so a request can be rejected while this value is above zero.

X-RateLimit-ResetintegerOptional
The number of seconds until the current rate limit window resets.

Response

The updated samples.
datalist of objects
The samples.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
429
Too Many Requests Error