Skip to navigation

Update study groups

Beta

Applies a partial update to between 1 and 100 treatment groups on the study. A property left out keeps the value the group holds. Setting no moves a group to that position and renumbers the study’s other groups around it, so the response lists only the groups you sent while the no of others may have changed. The request is validated as a whole; if any item is invalid, none are updated. The study may not be archived or canceled.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth 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 study group.
idstringRequiredformat: "^grp_[a-zA-Z0-9]{10,22}$"
The study group to update. Must be on the study.
namestringOptional1-255 characters
The name of the study group. May not be blank.
colorstringOptionalformat: "^#([0-9a-fA-F]{3}){1,2}$"

The color of the study group, as a three- or six-digit hex code.

max_animalsintegerOptional0-100
The maximum number of animals the study group may hold. May not be below the number of animals already assigned to the group.
controlbooleanOptional
Indicates this group is the control. A study has at most one control group, so a request may promote only one group, and promoting one is rejected while another group keeps the flag.
nointegerOptional>=1

The position the group takes among all the study’s groups. Each value must be unique within the request and between 1 and the number of groups on the study. The groups the request does not place keep their order and move to the positions left free, so the no of a group you did not send may change. A request that sets no no leaves the numbering untouched.

metadatamap from strings to anyOptional

Custom fields keyed by your team’s active study group metadata glossary slugs, merged into the group’s metadata. A value creates or updates the field, null clears it, and a field left out keeps its value. Fields your team marks mandatory cannot be cleared.

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 study groups.
datalist of objects
The study groups.

Errors

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