Collections API

The Collections API allows 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

List collections

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

limit - (int) Optional. Number of collections to return. Min: 1. Max: 100. Default: 20.
limit-items - (int) Optional. Number of items per collection to return. Min: 1. Max: 1000. Default: 20.
page-token - (string) Optional. The token to retrieve another page of results.

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

Expect a status code of 200.
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 results.

Read a Collection

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.

Collection Read 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.

Create a Collection

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 will respond with a 201 status code and a Collection model.

Rename a Collection

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

The server will respond with a 200 status code and a Collection model.

Delete a Collection

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

id - (string) unique ID of the collection to delete

Delete Collection Response

Expect a response status code of 204

Add item to a collection

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 add the items to
items - ([]string) A list of item ids to add to the collection

Add item response

Expect a response status code of 204

Remove one or more items from a collection

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

id - (string) unique ID of the collection to remove the items from
items - ([]string) A list of item ids to remove from the collection

Remove item response

Expect a response status code of 204

Re-order items in a collection

Send 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) 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.

Re-order items response

Expect a response status code of 200

Clone a collection

Create a copy (including items) of a collection

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

id - (string) unique ID of the collection to clone.
name - (string) what to name the cloned collection.

Clone 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.

Retrieve collections that an item belongs to

Retrieve a list of collections to which a particular item belongs. Only returns collections that the user initiating the request has access to.

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.

Collections for an item 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}"
}

Expect a status code of 200.
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 results.

Add Item(s) to Collection(s) in Bulk

This endpoint allows you to associate one or more items to one or more collections. Up to 1000 items and 1000 collections can be submitted at a time.

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

Bulk Add 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"
        }
    ]
}

Expect a status code of 200
successes - ([]BulkSuccess) An array of BulkSuccess models
failures - ([]BulkFailure) An array of BulkFailure models

Remove Item(s) from Collection(s) in Bulk

This endpoint allows you to remove one or more items from one or more collections. Up to 1000 items and 1000 collections can be submitted at a time.

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

Bulk Remove 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"
        }
    ]
}

Expect a status code of 200
successes - ([]BulkSuccess) An array of BulkSuccess models
failures - ([]BulkFailure) An array of BulkFailure models

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.

Table of contents