Skip to content
Artist Alley

Create a new collection

POST
/collections

Creates a manual-membership collection owned by the caller. Query-membership and hybrid modes ship in 1.11.B; for now only membership=manual is accepted.

Authorizations

Section titled “Authorizations ”

Request Body required

Section titled “Request Body required ”
object
name
required
string
>= 1 characters <= 200 characters
description
string
visibility
string
default: private
Allowed values: private org-only followers explicit-share
membership

Only manual is accepted in 1.11.A; passing query or hybrid returns 400 until 1.11.B ships.

string
default: manual
Allowed values: manual query hybrid
expires_at
string format: date-time
nullable
purpose
string
nullable
field_values

Initial values for collection-scoped custom fields. The handler validates that every required=true collection field is present; missing required fields return 422 with required_collection_field_missing.

Array<object>
object
field_id
required
string format: uuid
value_text
string
nullable
value_num
number
nullable
value_date
string format: date-time
nullable
value_options
Array<string>
nullable
value_ref
string format: uuid
nullable

Responses

Section titled “ Responses ”

201

Section titled “201 ”

Collection created

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"
}

422

Section titled “422 ”

A required collection-scoped field (see field_definition.subject_kind = 'collection' + required = true) is missing from the request body. This gate is enforced on CREATE only; subsequent UPDATEs don’t re-validate.

object
error
required
string
reason
required
string
Allowed values: required_collection_field_missing
field_code
string
field_label
string

500

Section titled “500 ”

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed