---
title: "Create a collection"
method: POST
path: "/v1/collections"
tags: ["Collections"]
---

# Create a collection

`POST /v1/collections`

## Request

- Base URL: `https://stashr.me`
- URL: `https://stashr.me/v1/collections`
- Auth: HTTP bearer

Create a collection: a named, live filter rule over the library. Invalid color or icon ids fail with a 422 listing the allowed values. Requires the write scope.

## Request body

- object
  - `color` string: A collection color id from the app (defaults to blue)
  - `filters` BookmarkFilters
    - `authorMode` 'include' | 'exclude'
    - `authors` string[]
    - `capturedAfter` string: Only bookmarks saved on/after this ISO-8601 date or datetime (inclusive)
    - `capturedBefore` string: Only bookmarks saved before this ISO-8601 date or datetime (exclusive)
    - `contentTypeMode` 'include' | 'exclude'
    - `contentTypes` string[]
    - `favorite` string[]
    - `media` string[]
    - `mediaMode` 'include' | 'exclude'
    - `note` string[]
    - `platformMode` 'include' | 'exclude'
    - `platforms` string[]
    - `tagMode` 'include_any' | 'include_all' | 'exclude_any' | 'exclude_all'
    - `tags` string[]
  - `icon` string: A collection icon id from the app
  - `name` string, required

## Response `201`

Collection created

- object
  - `data` Collection, required
    - `color` string, required
    - `filters` object, required
    - `icon` string, required
    - `id` string, uuid, required
    - `name` string, required
    - `pinned` boolean
    - `position` integer

## Other responses

- `400`: Malformed request (error.code bad_request or invalid_json)
- `401`: Missing, invalid, or expired credentials (error.code unauthorized)
- `402`: A Pro plan or active trial is required (error.code payment_required)
- `403`: The credential lacks the required scope (error.code forbidden)
- `404`: The resource does not exist or belongs to another account (error.code not_found)
- `422`: Validation failed; error.details.issues lists the fields (error.code validation_error)
- `429`: Too many requests (error.code rate_limited); wait Retry-After seconds, also given as error.retryAfterMs
- `500`: Something failed on Stashr's side (error.code internal_error); retryable

---

[API](https://skmtc.dev/stashr/apis/stashr-api.md) · [All operations](https://skmtc.dev/stashr/apis/stashr-api/llms.txt) · [OpenAPI document](https://skmtc.dev/stashr/apis/stashr-api/revisions/bcab186e0646?raw)