List collections (filterable, paginated)

GET

/collections

• Local development behind nginx (port 8088 by default)

Returns collections ordered by created_at DESC, id DESC so the newest entries are first. Filters and cursor pagination match the assets list contract — pass back next_cursor opaquely as cursor to retrieve the following page.

Parameters

Query Parameters

owner_ref

integer format: int64

Filter to collections owned by this user_ref.

visibility

string

Allowed values: private org-only followers explicit-share

featured

boolean

Filters on whether the collection has an ORG-scoped placement in featured_items (ADR 0065). Featuring is a placement, not a property of the collection, so this asks “is it featured internally”, not “is its featured flag set” — the flag no longer exists.

tab

string

Allowed values: mine featured public shared all

Pre-canned filter for the collections hub:

• mine — collections owned by the caller (any visibility)
• featured — visibility=public AND org-featured (ADR 0065)
• public — visibility=public (every install-public collection)
• shared — collections the caller has ACL access to but doesn’t own
• all — every collection the caller is allowed to see (default) tab is mutually-exclusive with owner_ref/visibility/featured — when set it overrides those.

q

string

<= 200 characters

Free-text filter on name (case-insensitive substring).

limit

integer

default: 50 >= 1 <= 200

cursor

string

include_deleted

boolean

Admin-only. When true, soft-deleted collections appear alongside live rows. Non-admin callers ignored.

Responses

200

A page of collections

object

items

required

Array<object>

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

next_cursor

Opaque token for the next page; omitted on the final page. Pass back unchanged as the cursor query parameter.

string

nullable

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

500

Unexpected server error

object

error

required

Human-readable error summary

string

Example

the request could not be completed