Storage locations

Boxes, shelves and cases: where copies are kept. Copies belong to a place by name.

5 operations

List your storage locations

GET/collection/locations

Signed in

Every box and shelf, by name, with how many copies are in each (all of them in one page). A place’s copies: GET /collection/items?filter[location]=<name>.

SDK method: collector.listLocations()
Key scopes: collection:read
Headers: If-None-MatchX-Request-Id

Responses

200OKYour places.

object

dataarray of Locationrequired
nextCursornullrequired
Always null: every place comes in one page.

304Not ModifiedNot modified: your copy (the ETag in If-None-Match) is current.

3Errors401 · 429 · 500

401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

curl 'https://api.collection.id/v1/collection/locations' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

{
  "data": [
    {
      "id": "2b4d6f8a-0c1e-4a3c-9e5f-7b9d1f3a5c7e",
      "name": "Long box 12",
      "kind": "long_box",
      "notes": null,
      "copyCount": 214,
      "labelCode": null,
      "lastAuditedAt": null,
      "createdAt": "2026-10-11T06:47:11.610Z"
    }
  ],
  "nextCursor": null
}

Add a storage location

POST/collection/locations

Signed inIdempotency-Key

A box, shelf or case. Its kind is guessed from the name when left out ("Long box 12" is a long box).

SDK method: collector.createLocation()
Key scopes: collection:write
Headers: Idempotency-KeyX-Request-Id

Request body required · application/json

LocationCreate

namestringrequired
Its name, unique in your collection ("Long box 12").
at most 480 characters
kindenum
Guessed from the name when left out.
One oflong_boxshort_boxmagazine_boxboxdrawershelf
and 2 more
slab_caseother
notesstring or null
at most 2000 characters

Responses

201CreatedAdded.

Location

A place you keep copies (a box, a shelf). Copies belong to it by name: their location.

idstring (uuid)required
namestringrequired
kindstringrequired
long_box, short_box, magazine_box, box, drawer, shelf, slab_case or other.
notesstring or nullrequired
copyCountintegerrequired
labelCodestring or nullrequired
The code on its printed label, if it has one.
lastAuditedAtstring (date-time) or nullrequired
createdAtstring (date-time)required

7Errors400 · 401 · 409 · 413 · 422 · 429 · 500

400
invalid_request invalid_json invalid_idempotency_key
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
invalid_idempotency_key: The Idempotency-Key isn’t 1–255 visible ASCII characters.
401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
409
idempotency_in_progress location_exists
idempotency_in_progress: The first request with this key is still running.
location_exists: You already have a place with that name.
413
payload_too_large
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
422
idempotency_key_reused
idempotency_key_reused: This key was used for a different request.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

curl -X POST 'https://api.collection.id/v1/collection/locations' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Long box 12"
  }'

{
  "id": "2b4d6f8a-0c1e-4a3c-9e5f-7b9d1f3a5c7e",
  "name": "Long box 12",
  "kind": "long_box",
  "notes": null,
  "copyCount": 0,
  "labelCode": null,
  "lastAuditedAt": null,
  "createdAt": "2026-10-11T06:47:11.610Z"
}

Get a storage location

GET/collection/locations/{id}

Signed in

One place, with how many copies are in it.

SDK method: collector.getLocation()
Key scopes: collection:read
Headers: If-None-MatchX-Request-Id

Path parameters

idstring (uuid)required

Responses

200OKThe place.

Location

A place you keep copies (a box, a shelf). Copies belong to it by name: their location.

idstring (uuid)required
namestringrequired
kindstringrequired
long_box, short_box, magazine_box, box, drawer, shelf, slab_case or other.
notesstring or nullrequired
copyCountintegerrequired
labelCodestring or nullrequired
The code on its printed label, if it has one.
lastAuditedAtstring (date-time) or nullrequired
createdAtstring (date-time)required

304Not ModifiedNot modified: your copy (the ETag in If-None-Match) is current.

4Errors401 · 404 · 429 · 500

401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404
not_found location_not_found
not_found: Nothing at that address.
location_not_found: No place of yours with that id.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

curl 'https://api.collection.id/v1/collection/locations/2b4d6f8a-0c1e-4a3c-9e5f-7b9d1f3a5c7e' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

{
  "id": "2b4d6f8a-0c1e-4a3c-9e5f-7b9d1f3a5c7e",
  "name": "Long box 12",
  "kind": "long_box",
  "notes": null,
  "copyCount": 214,
  "labelCode": null,
  "lastAuditedAt": null,
  "createdAt": "2026-10-11T06:47:11.610Z"
}

Remove a storage location

DELETE/collection/locations/{id}

Signed in

Removes the place and its label. Its copies keep their location text; they aren’t moved or removed.

SDK method: collector.deleteLocation()
Key scopes: collection:write
Headers: X-Request-Id

Path parameters

idstring (uuid)required

Responses

200OKRemoved.

object

ok"true"required

4Errors401 · 404 · 429 · 500

401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
404
not_found location_not_found
not_found: Nothing at that address.
location_not_found: No place of yours with that id.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

curl -X DELETE 'https://api.collection.id/v1/collection/locations/2b4d6f8a-0c1e-4a3c-9e5f-7b9d1f3a5c7e' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN"

{
  "ok": true
}

Change a storage location

PATCH/collection/locations/{id}

Signed in

Rename it (its copies follow the new name: Collector and Pro plans), change its kind or notes, or record when you last checked it.

SDK method: collector.updateLocation()
Key scopes: collection:write
Headers: X-Request-Id

Path parameters

idstring (uuid)required

Request body required · application/json

LocationPatch

namestring
Renames it on its copies too.
at most 480 characters
kindenum
One oflong_boxshort_boxmagazine_boxboxdrawershelf
and 2 more
slab_caseother
notesstring or null
at most 2000 characters
lastAuditedAtstring (date-time) or null
When you last checked what’s in it.
at most 64 characters

Responses

200OKThe place as it is now.

Location

A place you keep copies (a box, a shelf). Copies belong to it by name: their location.

idstring (uuid)required
namestringrequired
kindstringrequired
long_box, short_box, magazine_box, box, drawer, shelf, slab_case or other.
notesstring or nullrequired
copyCountintegerrequired
labelCodestring or nullrequired
The code on its printed label, if it has one.
lastAuditedAtstring (date-time) or nullrequired
createdAtstring (date-time)required

8Errors400 · 401 · 403 · 404 · 409 · 413 · 429 · 500

400
invalid_request invalid_json
invalid_request: The query or body doesn’t match the schema (see errors[]).
invalid_json: The body isn’t JSON.
401
unauthorized
unauthorized: Not signed in (no session or token, or an expired one).
403
feature_required
feature_required: Renaming a place (its copies follow) comes with the Collector and Pro plans.
404
not_found location_not_found
not_found: Nothing at that address.
location_not_found: No place of yours with that id.
409
location_exists
location_exists: You already have a place with that name.
413
payload_too_large
payload_too_large: The body is over 1,048,576 bytes, this operation’s limit.
429
rate_limited temporarily_blocked
rate_limited: Over the caller’s limit: the per-minute burst or the per-day quota (RateLimit headers; wait Retry-After seconds).
temporarily_blocked: Too many refused requests in a row: blocked for a while (Retry-After says how long).
500
internal
internal: Something went wrong on our side (quote the requestId).

curl -X PATCH 'https://api.collection.id/v1/collection/locations/2b4d6f8a-0c1e-4a3c-9e5f-7b9d1f3a5c7e' \
  -H "Authorization: Bearer $COLLECTOR_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Long box 12 (Marvel)"
  }'

{
  "id": "2b4d6f8a-0c1e-4a3c-9e5f-7b9d1f3a5c7e",
  "name": "Long box 12 (Marvel)",
  "kind": "long_box",
  "notes": null,
  "copyCount": 214,
  "labelCode": null,
  "lastAuditedAt": null,
  "createdAt": "2026-10-11T06:47:11.610Z"
}