Create New Collection

Create a new Collection and store it

Request

Query Params

show

string

optional

limit the response to show only specific properties, see show & hide for more info

Example:

hide

string

optional

hide properties from the response, see show & hide for more info

Example:

name

Header Params

x-api-key

string

required

Default:

x-api-env

string

required

Default:

Body Params application/json

name

string

optional

Example:

Order 10199

description

string | null

optional

Example:

3x Chair Lissabon

due_date

string <date> | null

optional

Example:

2020-01-02

status

enum<string>

optional

Status of the collection

planned

collection is planned, and has cards visible on a board

not_planned

collection is on backlog

ignored

collection is in the archive

WARNING

On update the status can only be changed from ignored to not_planned or from not_planned to ignored.

For other actions please look at:

Move Collection to Backlog

Move Collection to Board

Allowed values:

plannednot_plannedignored

Example:

not_planned

custom_fields

array[object (CustomField) {10}]

required

name

string

optional

Name of the field

Example:

Weight

type

enum<string>

optional

Allowed values:

textnumberdatecheckboxemaillinkphonelistselectaddressdrawingtextareausers

Default:

text

Example:

number

scope

enum<string>

optional

Allowed values:

collectioncard

priority

integer

optional

Priority of the custom field in which the fields are ordered in the frontend

Example:

value

optional

drawing_id

string <uuid>

optional

components

object (CustomFieldOptionsAddress)

optional

list

array [object {3}]

optional

selected

object

optional

options

optional

Extra settings for number, select or list types

board_id

string <uuid>

required

Unique identifier of the Board

cover_image_url

string <uri> | null

optional

cover_image_checksum

string | null

write-onlyoptional

Match pattern:

^[a-fA-F0-9]{64}$

cover_color_hex

string | null

optional

Examples:

#FFF#8d46e0

Match pattern:

^#([A-Fa-f0-9]{3}){1,2}$

Example

{
  "board_id": "676d5342-4e87-7c05-32dc-8fbe47b1ca83",
  "name": "accusamus veniam velit",
  "description": "Maiores ea enim enim veritatis. Totam sapiente nemo sint ab ducimus. Adipisci laboriosam deleniti. Molestiae et quaerat id eius quis ipsam temporibus ipsa. Eos minima qui dolorum recusandae nisi possimus soluta. Quam laborum reiciendis esse sit adipisci.",
  "due_date": "2024-04-10T03:50:17.821Z",
  "source_type": "custom",
  "cover_image_url": "https://loremflickr.com/640/480/animals",
  "cover_image_checksum": "814781c9f54af3eb22f2dbca1bdc51e2428c6b690c3956f4af62455779cbb0b0",
  "cover_image_signature": "NYvVoD1n",
  "cover_image_bytes": 183539,
  "cover_color_hex": "#b6b"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

Responses

🟢201Created

application/json

Body

string <uuid>

read-onlyoptional

Unique identifier

name

string

optional

Example:

Order 10199

description

string | null

optional

Example:

3x Chair Lissabon

start

string <date> | null

read-onlyoptional

Earliest date from its Cards

Example:

2020-01-02

end

string <date> | null

read-onlyoptional

Latest date from its Cards

Example:

2020-08-13

due_date

string <date> | null

optional

Example:

2020-01-02

meta

object | null

read-onlyoptional

Hashmap with additional information for the collection, received via Order

Example:

{"bar":"foo","baz":"quux"}

Additional properties

string

optional

position

integer | null

read-onlyoptional

Position in the backlog, if collection is planned the postion will be null

Example:

source_type

enum<string>

read-onlyoptional

States if the collection is created directly (custom), by cloning a collection or via an Order

Allowed values:

customorderclone

Default:

custom

status

enum<string>

optional

Status of the collection

planned

collection is planned, and has cards visible on a board

not_planned

collection is on backlog

ignored

collection is in the archive

WARNING

On update the status can only be changed from ignored to not_planned or from not_planned to ignored.

For other actions please look at:

Move Collection to Backlog

Move Collection to Board

Allowed values:

plannednot_plannedignored

Example:

not_planned

progress

enum<string>

read-onlyoptional

progress of the cards within the collection

open - all cards are on the first status

partial - not all cards are on the first or last status

done - all cards are on the last status

Allowed values:

openpartialdone

Example:

open

warnings

array[string]

read-onlyoptional

Example:

[]

custom_fields

array[object (CustomField) {13}]

required

string <uuid>

read-onlyoptional

Unique identifier

name

string

optional

Name of the field

Example:

Weight

type

enum<string>

optional

Allowed values:

textnumberdatecheckboxemaillinkphonelistselectaddressdrawingtextareausers

Default:

text

Example:

number

scope

enum<string>

optional

Allowed values:

collectioncard

priority

integer

optional

Priority of the custom field in which the fields are ordered in the frontend

Example:

value

optional

drawing_id

string <uuid>

optional

components

object (CustomFieldOptionsAddress)

optional

list

array [object {3}]

optional

selected

object

optional

options

optional

Extra settings for number, select or list types

created_at

string <date-time>

read-onlyoptional

Date and time of creation

Example:

2024-04-11T10:22:15Z

updated_at

string <date-time>

read-onlyoptional

Date and time of last update

Example:

2024-04-11T10:22:15Z

board_id

string <uuid>

required

Unique identifier of the Board

cover_image_url

string <uri> | null

optional

cover_image_signature

string | null

read-onlyoptional

cover_image_bytes

integer

read-onlyoptional

>= 0

cover_color_hex

string | null

optional

Examples:

#FFF#8d46e0

Match pattern:

^#([A-Fa-f0-9]{3}){1,2}$

external_ref

string | null

read-onlyoptional

Third-party reference of the object, for informational purposes only

Example:

fb1033a2ed70

created_at

string <date-time>

read-onlyoptional

Date and time of creation

Example:

2024-04-11T10:22:15Z

updated_at

string <date-time>

read-onlyoptional

Date and time of last update

Example:

2024-04-11T10:22:15Z

Example

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "name": "Order 10199",
  "description": "3x Chair Lissabon",
  "start": "2020-01-02",
  "end": "2020-08-13",
  "due_date": "2020-01-02",
  "meta": {
    "bar": "foo",
    "baz": "quux"
  },
  "position": 13,
  "source_type": "custom",
  "status": "planned",
  "progress": "open",
  "warnings": [],
  "custom_fields": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "name": "Weight",
      "type": "text",
      "scope": "collection",
      "priority": 0,
      "value": "string",
      "drawing_id": "19ba6f6f-3365-4d74-bdc5-b3df4072c0ab",
      "components": {
        "latitude": 52.3156048,
        "longitude": 6.496432,
        "country": "Netherlands",
        "city": "Rijssen",
        "postal_code": "7462TB",
        "street1": "Hogepad 83",
        "street2": "Second floor"
      },
      "list": [
        {
          "name": "string",
          "value": "string",
          "color": "transparent"
        }
      ],
      "selected": {
        "name": "string",
        "value": "string",
        "color": ""
      },
      "options": {
        "unit": "kg",
        "align": "left",
        "decimals": 2
      },
      "created_at": "2024-04-11T10:22:15Z",
      "updated_at": "2024-04-11T10:22:15Z"
    }
  ],
  "board_id": "75e8c400-2dbc-43a3-9af4-ff9e6c099385",
  "cover_image_url": "http://example.com",
  "cover_image_signature": "string",
  "cover_image_bytes": 0,
  "cover_color_hex": "#FFF",
  "external_ref": "fb1033a2ed70",
  "created_at": "2024-04-11T10:22:15Z",
  "updated_at": "2024-04-11T10:22:15Z"
}

🟠422Unprocessable Content

🟠404Not Found

🟠401Not Logged In