Managing CMS Collections and Items

Get your site ID

Every collection is associated with a specific Webflow site. You’ll need your site_id to create a collection. You can find this by calling the List Sites endpoint and locating the site you want to work with in the response.

1
from webflow import Webflow
2
3
client = Webflow(
4
    access_token="YOUR_ACCESS_TOKEN",
5
)
6
client.sites.list()

Define the collection schema

Next, you’ll define the schema for your collection. This includes the displayName for the collection, the singularName for its items, the slug for the collection, and an array of fields.

Default fields

Each collection will always have the following fields in its schema:

• name - The name of the item
• slug - The slug of the item. Slugs should be unique, and formatted as all lowercase with no spaces. Any spaces will be converted to ”-”.

Custom fields

You can add additional custom fields to the collection. Each field will have its own type, displayName, slug, and other properties to configure its behavior. A collection’s schema can have up to 60 fields. To see the different field types and their properties, see the Field Types & Item Values Reference.

Here is an example of a schema for a “Hitchhiker’s Guide” collection that includes various field types:

1
{
2
  "displayName": "Guide Entries",
3
  "singularName": "Guide Entry",
4
  "slug": "guide-entries",
5
  "fields": [
6
    {
7
      "type": "PlainText",
8
      "displayName": "Entry Title",
9
      "slug": "entry-title",
10
      "isRequired": true
11
    },
12
    {
13
      "type": "RichText",
14
      "displayName": "Entry HTML",
15
      "slug": "entry-html"
16
    },
17
    {
18
      "type": "Image",
19
      "displayName": "Illustration Image",
20
      "slug": "illustration-image"
21
    },
22
    {
23
      "type": "Number",
24
      "displayName": "Importance Level",
25
      "slug": "importance-level"
26
    },
27
    {
28
      "type": "Switch",
29
      "displayName": "Is Essential",
30
      "slug": "is-essential"
31
    },
32
    {
33
      "type": "Reference",
34
      "displayName": "Related Entry",
35
      "slug": "related-entry",
36
      "metadata": {
37
        "collectionId": "7f15043107e2fc95644e93807ee25dd6"
38
      }
39
    },
40
    {
41
      "type": "Option",
42
      "displayName": "Item Type",
43
      "slug": "item-type",
44
      "metadata": {
45
        "options": [
46
          {"name": "Survival Gear"},
47
          {"name": "Gadget"},
48
          {"name": "Other"}
49
        ]
50
      }
51
    }
52
  ]
53
}

Create the collection

With your site_id and schema, you can now create the collection by making a POST request to the Create Collection endpoint.

1
from webflow import ReferenceField, ReferenceFieldMetadata, StaticField, Webflow
2
3
client = Webflow(
4
    access_token="YOUR_ACCESS_TOKEN",
5
)
6
client.collections.create(
7
    site_id="580e63e98c9a982ac9b8b741",
8
    display_name="Blog Posts",
9
    singular_name="Blog Post",
10
    slug="posts",
11
    fields=[
12
        StaticField(
13
            is_required=True,
14
            type="PlainText",
15
            display_name="Title",
16
            help_text="The title of the blog post",
17
        ),
18
        StaticField(
19
            is_required=True,
20
            type="RichText",
21
            display_name="Content",
22
            help_text="The content of the blog post",
23
        ),
24
        ReferenceField(
25
            is_required=True,
26
            type="Reference",
27
            display_name="Author",
28
            help_text="The author of the blog post",
29
            metadata=ReferenceFieldMetadata(
30
                collection_id="23cc2d952d4e4631ffd4345d2743db4e",
31
            ),
32
        ),
33
    ],
34
)

Get the collection ID

First, you need the id of the collection you want to create an item for. The Create Collection response will include the collection’s id. However, you can also get the collection ID by calling the List Collections endpoint and finding the collection in the response.

1
from webflow import Webflow
2
3
client = Webflow(
4
    access_token="YOUR_ACCESS_TOKEN",
5
)
6
client.collections.get(
7
    collection_id="580e63fc8c9a982ac9b8b745",
8
)

Create a collection item

To add an item, send a POST request to the Create Collection Item endpoint. The fieldData object in the request body must match the schema you defined for the collection.

1
from webflow import (
2
    CollectionItemPostSingle,
3
    CollectionItemPostSingleFieldData,
4
    Webflow,
5
)
6
7
client = Webflow(
8
    access_token="YOUR_ACCESS_TOKEN",
9
)
10
client.collections.items.create_item(
11
    collection_id="580e63fc8c9a982ac9b8b745",
12
    request=CollectionItemPostSingle(
13
        is_archived=False,
14
        is_draft=False,
15
        field_data=CollectionItemPostSingleFieldData(
16
            name="Pan Galactic Gargle Blaster Recipe",
17
            slug="pan-galactic-gargle-blaster",
18
        ),
19
    ),
20
)

List collection items

To get a list of all items in a collection, send a GET request to the List Collection Items endpoint.

1
from webflow import Webflow
2
3
client = Webflow(
4
    access_token="YOUR_ACCESS_TOKEN",
5
)
6
client.collections.items.list_items(
7
    collection_id="580e63fc8c9a982ac9b8b745",
8
)

Pagination

When listing items, the response will be paginated. You can control the pagination using the limit and offset query parameters.

• limit: The maximum number of items to return (up to 100).
• offset: The number of items to skip from the beginning of the list.

By default, the API will return up to 100 items. If a collection contains more than 100 items, you can use offset to retrieve additional pages of results. For example, to get the second page of 100 items, you would set offset to 100.

The response will include a pagination object with total, limit, and offset fields, which you can use to loop through the pages of results.

1
// Snippet from GET /v2/collections/{collection_id}/items response
2
{
3
  "items": [
4
    // ... item data ...
5
  ],
6
  "pagination": {
7
    "total": 250,
8
    "limit": 100,
9
    "offset": 100
10
  }
11
}

Update a collection item

To modify an existing item, you’ll first need its id. You can get the item’s id by calling the List Collection Items endpoint and finding the item in the response.

Then, use the PATCH endpoint to Update a Collection Item. You only need to provide the fields you want to change in the fieldData object.

1
from webflow import CollectionItemPatchSingleFieldData, Webflow
2
3
client = Webflow(
4
    access_token="YOUR_ACCESS_TOKEN",
5
)
6
client.collections.items.update_item(
7
    collection_id="580e63fc8c9a982ac9b8b745",
8
    item_id="580e64008c9a982ac9b8b754",
9
    is_archived=False,
10
    is_draft=False,
11
    field_data=CollectionItemPatchSingleFieldData(
12
        name="Pan Galactic Gargle Blaster Recipe",
13
        slug="pan-galactic-gargle-blaster",
14
    ),
15
)

Delete a collection item

To remove an item from a collection, you’ll need its id. You can get the item’s id by calling the List Collection Items endpoint and finding the item in the response.

Then, use the DELETE endpoint to Delete a Collection Item.

1
from webflow import Webflow
2
3
client = Webflow(
4
    access_token="YOUR_ACCESS_TOKEN",
5
)
6
client.collections.items.delete_item(
7
    collection_id="580e63fc8c9a982ac9b8b745",
8
    item_id="580e64008c9a982ac9b8b754",
9
)