# Curate groups of entries

> Build a hand-picked, ordered list of entries such as Featured on homepage, reorder it, and let your website load it by identifier in your chosen order.

A group is a hand-picked, ordered list of entries, such as "Featured on homepage" or "Coastal road trip". Your website or app loads a group by its identifier and gets the entries in exactly the order you set. This page shows editors how to create and manage groups, and developers how groups appear in the API.

## When should I use a group?

Use a group when people, not rules, decide which entries belong together and in which order. Filters and types answer "all campsites in this region"; a group answers "our five favourite campsites, best first". An entry can be in any number of groups, and entries of different types can share a group.

Owners and Editors can create and change groups. Developers can view them.

## Create a group

Groups live in **Entries**. The switch at the top of the entry list toggles between **Entries** and **Groups** (shortcut: ⌘G on a Mac, Ctrl+G on Windows).

1. In **Entries**, click **New** and choose **New group**. It is in the same menu as the types, whichever view you are in.
2. Enter a **Name**, for example "Featured on homepage".
3. Check the **Identifier**. Spatibase suggests one based on the name, such as `featured-on-homepage`, and you can change it.
4. Optionally add a **Description**.
5. Click **Create group**.

The identifier is the name your website or app uses to load the group, so pick one you are happy to keep. Two groups in a project cannot share one.

The list on the left shows each group with its number of entries and how many of them are published, and **Unpublished changes** or **Will be removed** when something about the group waits for the next publish.

## Add entries to a group

There are three ways to add entries:

- **From the group:** open the group in the **Groups** view, click **Add entries**, search by title or filter by type, tick the entries and confirm. Entries already in the group are marked "Already in group".
- **From an entry:** in the entry editor, use **+ Add to group…** in the **Groups** section. It takes effect right away, and the entry must be saved first.
- **For many entries at once:** select them in the entry list and choose **Add to group…** in the bar at the bottom. See [Find, edit and export entries](https://spatibase.com/docs/content/find-edit-export/#act-on-several-entries-at-once).

You can also add every entry of an import to groups in the import wizard. See [Import your data](https://spatibase.com/docs/content/import/).

## Reorder and remove entries

The order you see under **Entries in this group** is the order apps get.

- Point at an entry and drag it by the handle that appears on its left. With the keyboard, focus the handle and press the up or down arrow.
- Point at an entry to see its pin on the map; click it (or the pin) to open the entry. The list then stays filtered to the group until you clear the **Group** filter.
- Click the **x** that appears at the right of an entry (**Remove from group**) to take it out of the group. The entry itself is not deleted.

## Do group changes need publishing?

Yes. Changes to a group wait for the next **Publish** of the project and go live together with the entries: adding, removing and reordering entries, editing the group's name, identifier or description, creating a group and deleting one. Until then apps keep seeing the group as it was at the last publish. A group with changes waiting shows **Unpublished changes** in the list, and its editor says "Will go live at the next publish". A new group is not live until the first publish.

What apps see also depends on each entry's status. A group only ever shows its **published** entries, and none of a type that is switched off. An entry that is still a draft is left out until it is published, and it appears in its place in the order as soon as it is. See [Drafts and publishing](https://spatibase.com/docs/publish/draft-and-published/).

## Rename or delete a group

Open the group, change its **Name**, **Identifier** or **Description**, and click **Save changes**.

> **Important:** Changing a group's identifier, or deleting the group, breaks every website or app that loads the group by its old key. Tell your developer before you do it.

To delete a group, choose **Delete group** and confirm. Only the group is removed: the entries in it stay where they are.

Right-click a group in the list for **Open**, **Show its entries** (the **Entries** list filtered to that group), **Duplicate** (a copy named "… (copy)" with the same entries in the same order) and **Delete…**.

## How do groups appear in the API?

The Content Delivery API lists every group of a project and returns each group's published entries in the order the editors arranged them. For example, with `$PROJECT_ID` as your project's id:

```http
GET https://api.spatibase.com/delivery/v1/projects/$PROJECT_ID/groups
GET https://api.spatibase.com/delivery/v1/projects/$PROJECT_ID/groups/featured-on-homepage
```

- `/groups` lists all groups with the number of published entries in each.
- `/groups/{apiKey}` returns one group and its published entries, in your order.
- `/entries?group=featured-on-homepage` filters entries by group, and adding `&sort=group` keeps the group's order while you combine it with other filters.
- Every entry in the API lists the identifiers of the groups it belongs to.

If the project's Content Delivery API is private, these requests need an identifier. See [Access and identifiers](https://spatibase.com/docs/publish/access-and-keys/). Developers find the details in the [Content Delivery API](https://spatibase.com/docs/reference/delivery-api/) reference.

## Related

- [Find, edit and export entries](https://spatibase.com/docs/content/find-edit-export/)
- [Drafts and publishing](https://spatibase.com/docs/publish/draft-and-published/)
- [Content Delivery API](https://spatibase.com/docs/reference/delivery-api/)