Update a cage

PATCH

https://acme-api.invivo.benchling.com/api/public/v1/cages/:cageId

PATCH

/api/public/v1/cages/:cageId

curl -X PATCH https://acme-api.invivo.benchling.com/api/public/v1/cages/cge_5mR8kWpQnL3xTv7YzBcDfH \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{}'

{
  "id": "cge_5mR8kWpQnL3xTv7YzBcDfH",
  "name": "string",
  "catalog": "string",
  "metadata": {
    "cohort_size": 24,
    "species": "Mus musculus"
  },
  "study": {
    "id": "sdy_3vQ8kZpLmN2xRt7YwBcDfG",
    "project_id": "pjt_9kLmNpQrStUvWxYzAbCdEf",
    "name": "string",
    "code": "string",
    "study_code_id": "sdc_7hJ4nQrXsT9wYzAbCdEfGh",
    "type": "internal",
    "status": "in_progress",
    "description": "string",
    "timezone": "America/Los_Angeles",
    "metadata": {
      "cohort_size": 24,
      "species": "Mus musculus"
    },
    "author": {
      "id": "usr_2fBnKqWxYz5tRvMpLsJdHc",
      "name": "string",
      "email": "string",
      "timezone": "string"
    },
    "owner": {
      "id": "usr_2fBnKqWxYz5tRvMpLsJdHc",
      "name": "string",
      "email": "string",
      "timezone": "string"
    },
    "started_on": "2026-09-18",
    "tracking_day_base": 1,
    "completed_at": "2026-09-18T14:03:22.123456Z",
    "canceled_at": "2026-09-18T14:03:22.123456Z",
    "created_at": "2026-09-18T14:03:22.123456Z",
    "updated_at": "2026-09-18T14:03:22.123456Z"
  },
  "created_at": "2026-09-18T14:03:22.123456Z",
  "updated_at": "2026-09-18T14:03:22.123456Z"
}

Updates the supplied attributes of an existing cage.

Authentication

AuthorizationBearer

OAuth authentication of the form <token>.

Path parameters

cageIdstringRequiredformat: "^cge_[a-zA-Z0-9]{10,22}$"

The unique identifier of the cage.

Request

The cage attributes to change.

study_idstringOptionalformat: "^sdy_[a-zA-Z0-9]{10,22}$"

Unique identifier for a study.

namestringOptional1-50 characters

The cage name.

metadatamap from strings to any or nullOptional

The metadata to merge into the cage. Set an individual value to null to delete that key.

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 cage.

idstringformat: "^cge_[a-zA-Z0-9]{10,22}$"

Unique identifier for a cage.

namestring<=50 characters

The name of the cage.

catalogstring or null<=255 characters

The generated catalog number of the cage.

metadatamap from strings to any or null

The metadata associated to the cage.

studyobject or null

The study the cage belongs to. Null when it is not assigned to a study.

created_atdatetime

UTC timestamp with microsecond precision, always suffixed with Z, in the form yyyy-MM-ddTHH:mm:ss.SSSSSSZ.

updated_atdatetime

UTC timestamp with microsecond precision, always suffixed with Z, in the form yyyy-MM-ddTHH:mm:ss.SSSSSSZ.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

429

Too Many Requests Error