Collections API in Wasabi AiR

20 May 2024
6 Minutes to read

Collections API in Wasabi AiR

Updated on 20 May 2024
6 Minutes to read

Article summary

Did you find this summary helpful?

Thank you for your feedback

The Collections API enables you to create curated lists of items.

Model - Collection

{
    "id": "5df434f8031fdd45f669e39b42f2221a",
    "name": "foo",
    "num_items": 2,
    "user_id": "5dc1d37d24e702ea2658b6ae65f18bfd",
    "created_at": "2019-12-14T01:03:52.454906Z",
    "updated_at": "2019-12-14T01:03:52.454906Z"
}

id - (string) The collection’s unique identifier.
name - (string) The name of the collection.
num_items - (int) The number of items in the collection.
user_id - (string) The user ID of the collection’s owner.
created_at - (string) The timestamp when the collection was created.
updated_at - (string) The timestamp when the collection was last updated.

Model - CollectionItem

{
    "collection_id": "5df434f8031fdd45f669e39b42f2221a",
    "item_id": "5b5e5a5eb6a8341d1b13871fdf8c3fef",
    "display_order": 1,
    "added_at": "2019-12-16T14:50:11.186819Z"
}

collection_id - (string) The collection to which this CollectionItem belongs.
item_id - (string) The ID of the item.
display_order - (int) The order of this item in the collection.
added_at - (string) The timestamp when this item was added to the collection.

Model - ItemsList

{
    "items": [
        {
            "collection_id": "5df434f8031fdd45f669e39b42f2221a",
            "item_id": "5b5e5a5eb6a8341d1b13871fdf8c3fef",
            "display_order": 1,
            "added_at": "2019-12-16T14:50:11.186819Z"
        }
    ],
    "next_page": "NP-BAwEBBVRva2VuAf-CAAEDAQVMaW1pdAEEAAEGT2Zmc2V0AQQAAQZQYXJhbXMB_4QAAAAh_4MEAQERbWFwW3N0cmluZ11zdHJpbmcB_4QAAQwBDAAAB_-CAQIBAgA="
}

items - ([]Item) An array of item objects.
next_page - (string) The token to retrieve a subsequent page of results from the Collection Read endpoint. If this is an empty string, there are no additional pages of results.

Model - CollectionWithItems

{
    "collection": {
        "id": "5df434f8031fdd45f669e39b42f2221a",
        "name": "foo",
        "num_items": 2,
        "user_id": "5dc1d37d24e702ea2658b6ae65f18bfd",
        "created_at": "2019-12-14T01:03:52.454906Z",
        "updated_at": "2019-12-14T01:03:52.454906Z"
    },
    "items": {
        "items": [
            {
                "collection_id": "5df434f8031fdd45f669e39b42f2221a",
                "item_id": "5b5e5a5eb6a8341d1b13871fdf8c3fef",
                "display_order": 1,
                "added_at": "2019-12-16T14:50:11.186819Z"
            }
        ],
        "next_page": "NP-BAwEBBVRva2VuAf-CAAEDAQVMaW1pdAEEAAEGT2Zmc2V0AQQAAQZQYXJhbXMB_4QAAAAh_4MEAQERbWFwW3N0cmluZ11zdHJpbmcB_4QAAQwBDAAAB_-CAQIBAgA="
    }
}

collection - The collection model.
items - An ItemsList model.

Model - BulkSuccess

{
    "item_id": "5b5e5a5eb6a8341d1b13871fdf8c3fef",
    "collection_id": "5df434f8031fdd45f669e39b42f2221a"
}

item_id: (string) The unique ID of an item.
collection_id: (string) The unique ID of a collection.

Model - BulkFailure

{
    "item_id": "5b5e5a5eb6a8341d1b13871fdf8c3fef",
    "collection_id": "5df434f8031fdd45f669e39b42f2221a",
    "error": "some error string"
}

item_id: (string) The unique ID of an item.
collection_id: (string) The unique ID of a collection.
error: (string) An error message.

Listing Collections

GET /api/data/v3/collections?limit={limit}&limit-items={limit-items}&page-token={page-token}

limit - (int) Optional. The number of collections to return (default: 20, min: 1, max: 100).
limit-items - (int) Optional. The number of items per collection to return (default: 20, min: 1, max: 1000).
page-token - (string) Optional. The token to retrieve another page of results.

Response

{
    "collections": [
        {
            "collection": {
                "id": "5df434f8031fdd45f669e39b42f2221a",
                "name": "foo",
                "num_items": 2,
                "user_id": "5dc1d37d24e702ea2658b6ae65f18bfd",
                "created_at": "2019-12-14T01:03:52.454906Z",
                "updated_at": "2019-12-14T01:03:52.454906Z"
            },
            "items": {
                "items": [
                    {
                        "collection_id": "5df434f8031fdd45f669e39b42f2221a",
                        "item_id": "5b5e5a5eb6a8341d1b13871fdf8c3fef",
                        "display_order": 1,
                        "added_at": "2019-12-16T14:50:11.186819Z"
                    }
                ],
                "next_page": "NP-BAwEBBVRva2VuAf-CAAEDAQVMaW1pdAEEAAEGT2Zmc2V0AQQAAQZQYXJhbXMB_4QAAAAh_4MEAQERbWFwW3N0cmluZ11zdHJpbmcB_4QAAQwBDAAAB_-CAQIBAgA="
            }
        },
        ...
    ],
    "next_page": "{next page token}",
    "previous_page": "{previous page token}"
}

collections - []CollectionWithItems A list of CollectionWithItems objects.
next_page - (string) The token to retrieve a subsequent page of results. If this is an empty string, there are no additional pages of results.
previous_page - (string) The token to retrieve the previous page of results. If this is an empty string, you are on the first page of the results.

Expect a status code of 200.

Reading a Collection

To get the details for a collection, including the list of items:

GET /api/data/v3/collections/{id}?limit={limit}&page-token={page-token}

{id} - (string) The ID of the collection.
{limit} - (string) The number of items to include in the response.
{page-token} - (string) Optional. The token to retrieve another page of results.

Response

{
    "collection": {
        "id": "5df434f8031fdd45f669e39b42f2221a",
        "name": "foo",
        "num_items": 2,
        "user_id": "5dc1d37d24e702ea2658b6ae65f18bfd",
        "created_at": "2019-12-14T01:03:52.454906Z",
        "updated_at": "2019-12-14T01:03:52.454906Z"
    },
    "items": [
        {
            "collection_id": "5df434f8031fdd45f669e39b42f2221a",
            "item_id": "5b5e5a5eb6a8341d1b13871fdf8c3fef",
            "display_order": 1,
            "added_at": "2019-12-16T14:50:11.186819Z"
        },
        {
            "collection_id": "5df434f8031fdd45f669e39b42f2221a",
            "item_id": "6daabbd507f73881bcf571f0424e5892",
            "display_order": 3,
            "added_at": "2019-12-16T15:54:23.807625Z"
        }
    ],
    "next_page": "{next page token}",
    "previous_page": "{previous page token}"
}

The API responds with a status code of 200 and a CollectionWithItems model.

Creating a Collection

To add a new collection:

POST /api/data/v3/collections
{
    "name": "Awesome action movies"
}

name - (string) Required. Human-readable name of the collection.

Response

{
    "id": "5dfbc0ce85d2e2047a209fcf7a8f6fe3",
    "name": "Awesome action movies",
    "num_items": 0,
    "user_id": "5dc1d37d24e702ea2658b6ae65f18bfd",
    "created_at": "2019-12-19T18:26:22.525319Z",
    "updated_at": "2019-12-19T18:26:22.525319Z"
}

The API responds with a 201 status code and a Collection model.

Renaming a Collection

PUT /api/data/v3/collections/{id}
{
    "name": "new collection title"
}

Response

The server responds with a 200 status code and a Collection model.

Deleting a Collection

DELETE /api/data/v3/collections/{id}

id - (string) Unique ID of the collection to delete.

Response

Expect a response status code of 204.

Adding an Item(s) to a Collection

To add one or more items to a collection:

POST /api/data/v3/collections/{id}/items
{
    "items": [
        "1a9db061775230e03d5cdc98e4b5d218",
        "6daabbd507f73881bcf571f0424e5892"
    ]
}

id - (string) Unique ID of the collection to which you want to add the items.
items - ([]string) A list of item IDs to add to the collection.

Response

Expect a response status code of 204.

Removing One or More Items From a Collection

DELETE /api/data/v3/collections/{id}/items
{
    "items": [
        "1a9db061775230e03d5cdc98e4b5d218",
        "6daabbd507f73881bcf571f0424e5892"
    ]
}

id - (string) Unique ID of the collection from which to remove the items.
items - ([]string) A list of item IDs to remove from the collection.

Response

Expect a response status code of 204.

Reordering Items in a Collection

This endpoint sends an array of item IDs in the order you would like them to appear. All item IDs from the collection must be specified.

POST /api/data/v3/collections/{id}/reorder
{
    "item_ids": [
        "5789031d7d551417c16891d475429de3",
        "43na3125b9f5421e1cb5702deb8d45e",
        "5702031d7d551417c16891d475429ab5"
    ]
}

items - ([]string) The list of item IDs belonging to the collection in the order you want them to appear in the collection. The ID of every item in the collection must be specified.

Response

Expect a response status code of 200.

Cloning a Collection

To create a copy (including items) of a collection:

POST /api/data/v3/collections/{id}/clone
{
    "name": "my cloned comp"
}

id - (string) The unique ID of the collection to clone.
name - (string) A name for the cloned collection.

Response

Expect a response status code of 200 and for the server to respond with the Collection model in the body of the response.

Retrieving Collections to Which an Item Belongs

This endpoint retrieves a list of collections to which a particular item belongs. This returns only collections to which the user initiating the request has access.

GET /api/data/v3/items/{id}/collections?limit={limit}&page-token={page-token}

{id} - (string) The ID of the collection.
{limit} - (string) The number of items to include in the response.
{page-token} - (string) Optional. The token to retrieve another page of results.

Response

{
    "collections": [
        {
            "created_at": "2019-12-14T01:03:52.454906Z",
            "id": "5df434f8031fdd45f669e39b42f2221a",
            "name": "foo",
            "num_items": 2,
            "updated_at": "2019-12-14T01:03:52.454906Z",
            "user_id": "5dc1d37d24e702ea2658b6ae65f18bfd"
        },
        {
            "created_at": "2019-12-17T18:46:53.454604Z",
            "id": "jive",
            "name": "fooballs",
            "num_items": 2,
            "updated_at": "2019-12-17T18:46:53.454604Z",
            "user_id": "5dc1d37d24e702ea2658b6ae65f18bfd"
        }
    ],
    "next_page": "{next page token}",
    "previous_page": "{previous page token}"
}

collections - ([]Collection) A list of Collection models.
next_page - (string) The token to retrieve a subsequent page of results. If this is an empty string, there are no additional pages of results.
previous_page - (string) The token to retrieve the previous page of results. If this is an empty string, you are on the first page of the results.

Expect a status code of 200.

Adding an Item(s) to a Collection(s) in Bulk

This endpoint enables you to associate one or more items to one or more collections. You can submit up to 1000 items and 1000 collections at a time.

POST  /api/data/v3/collections/bulk
{
    "items": [
        "item1",
        "item2"
    ],
    "collections": [
        "5df434f8031fdd45f669e39b42f2221a",
        "5df434f8031fdd45f669e39bcdb74679"
    ]
}

Response

{
    "successes": [
        {
            "item_id": "item1",
            "collection_id": "5df434f8031fdd45f669e39b42f2221a"
        },
        {
            "item_id": "item2",
            "collection_id": "5df434f8031fdd45f669e39b42f2221a"
        }

    ],
    "failures": [
        {
            "item_id": "item1",
            "collection_id": "5df434f8031fdd45f669e39bcdb74679",
            "error": "some error"
        },
        {
            "item_id": "item2",
            "collection_id": "5df434f8031fdd45f669e39bcdb74679",
            "error": "some error"
        }
    ]
}

successes - ([]BulkSuccess) An array of BulkSuccess models.
failures - ([]BulkFailure) An array of BulkFailure models.

Expect a status code of 200.

Removing an Item(s) from a Collection(s) in Bulk

This endpoint enables you to remove one or more items from one or more collections. You can submit up to 1000 items and 1000 collections at a time.

DELETE  /api/data/v3/collections/bulk
{
    "items": [
        "item1",
        "item2"
    ],
    "collections": [
        "5df434f8031fdd45f669e39b42f2221a",
        "5df434f8031fdd45f669e39bcdb74679"
    ]
}

Response

{
    "successes": [
        {
            "item_id": "item1",
            "collection_id": "5df434f8031fdd45f669e39b42f2221a"
        },
        {
            "item_id": "item2",
            "collection_id": "5df434f8031fdd45f669e39b42f2221a"
        }

    ],
    "failures": [
        {
            "item_id": "item1",
            "collection_id": "5df434f8031fdd45f669e39bcdb74679",
            "error": "some error"
        },
        {
            "item_id": "item2",
            "collection_id": "5df434f8031fdd45f669e39bcdb74679",
            "error": "some error"
        }
    ]
}

successes - ([]BulkSuccess) An array of BulkSuccess models.
failures - ([]BulkFailure) An array of BulkFailure models.

Expect a status code of 200.

What's Next

Comments API in Wasabi AiR

Table of contents

Model - Collection
Model - CollectionItem
Model - ItemsList
Model - CollectionWithItems
Model - BulkSuccess
Model - BulkFailure
Listing Collections
Reading a Collection
Creating a Collection
Renaming a Collection
Deleting a Collection
Adding an Item(s) to a Collection
Removing One or More Items From a Collection
Reordering Items in a Collection
Cloning a Collection
Retrieving Collections to Which an Item Belongs
Adding an Item(s) to a Collection(s) in Bulk
Removing an Item(s) from a Collection(s) in Bulk