Skip to content
Artist Alley

Partial update of a collection

PATCH
/collections/{id}

Only fields present in the body are touched. Pass expires_at: null to remove the TTL; omit the field to keep the current value.

Optimistic concurrency: pass the collection’s last-known updated_at as if_unchanged_since; 409 if the row has been edited since.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string format: uuid

Request Body required

Section titled “Request Body required ”

Partial update; only present fields are touched. Pass expires_at: null to clear the TTL.

object
name
string
>= 1 characters <= 200 characters
description
string
visibility
string
Allowed values: private org-only followers explicit-share
membership
string
Allowed values: manual query hybrid
expires_at
string format: date-time
nullable
purpose
string
nullable
if_unchanged_since

Optimistic-concurrency guard. When set, the server returns 409 EditConflict if the collection’s updated_at has advanced past this value. Omit to opt out of the check (legacy behaviour).

string format: date-time

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Updated

A user-owned collection of assets, per ADR 0009. UUID-keyed, federation-prepared (origin_server_id), with three orthogonal axes: visibility, membership, and lifecycle.

object
id
required
string format: uuid
owner_user_ref
required
integer format: int64
name
required
string
description
required
string
visibility
required
string
Allowed values: private org-only followers explicit-share
membership
required

manual only for 1.11.A. query and hybrid ship in 1.11.B once the search DSL (ADR 0010) lands.

string
Allowed values: manual query hybrid
expires_at

TTL. Null = permanent.

string format: date-time
nullable
purpose

Free-form admin-set hint (“for_review”, “for_proofing”, …). Replaces RS’s single-purpose archived flag.

string
nullable
origin_server_id

Federation home server. Null = local. Populated when collections sync in from a peer in a later phase.

string format: uuid
nullable
created_at
required
string format: date-time
updated_at
required
string format: date-time
deleted_at

Soft-delete timestamp. Non-null only on rows surfaced by the admin include_deleted=true listing (the trash view); null on live rows.

string format: date-time
nullable
deleted_reason

Optional reason captured at soft-delete time.

string
nullable

400

Section titled “400 ”

Malformed request

object
error
required

Human-readable error summary

string
Example
the request could not be completed

401

Section titled “401 ”

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
  "error": "authentication required: sign in and retry with a valid session or API token"
}

403

Section titled “403 ”

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

404

Section titled “404 ”

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

409

Section titled “409 ”

Edited by someone else after if_unchanged_since.

Returned with HTTP 409 when an optimistic-concurrency check fails. Carries the row’s current updated_at so the client can decide whether to reload + retry or surface a diff UI.

object
error
required

Human-readable summary (e.g. “asset was edited by someone else”).

string
updated_at
required

The current updated_at on the row (server-authoritative).

string format: date-time