# Create a collection and store records

Make a collection in the console, give a version its fields, promote it live and add records, which your app reads and a form can fill.

A collection is a table of your own: release notes, testimonials, the contact
requests a form sends in. Its fields live in a version, which you promote live
once it is ready, and each record follows the live version. This guide makes
**Contact requests** for Acme Analytics, which the
[forms guide](/forms/create-a-form) then fills from a public form.

> **Note:**
  A console role that can create collections, their versions and records, and
  room in your plan for one more collection.

## 1. Open Collections

[Open Collections in the console](https://console.buildbase.app/dashboard/admin/collections)

In the left rail choose **Content**, then **Collections** under **Data**.
**All collections** lists each one with its slug and who made it. Press
**Create collection**.

![The Collections page under Content, with the Collections menu item under Data highlighted as step 1 and the Create collection button as step 2](/images/collections/create-a-collection/collections-page.webp)

## 2. Name it

In **Create new collection**, fill **Name** and **Collection slug**, the name
your code reads it by, such as `contact-requests`. Press **Create**.

![The Create new collection dialog: Name Contact requests, and the Collection slug contact-requests highlighted as step 2](/images/collections/create-a-collection/create-collection.webp)

## 3. Make a version

Press **View** on its row. **Schema versions** holds the versions of its
fields. Press **Create new version**, give it a **Name** such as `v1`, and
press **Create**.

![The Create new version dialog: Name v1, and the Create button highlighted as step 3](/images/collections/create-a-collection/create-version.webp)

## 4. Add its fields

Press **View** on the version. Under **No fields yet**, press **Add field** for
each field: a **Title** and a **Slug**, its **Type** (text, rich text, number,
bool, date, colour, link, email or file), whether it is a **Required field**,
and optional **Helper text** and **Default value**. A file field also takes
**Largest file (MB)** and **Files per submission** ([file
fields](/collections/overview#file-fields)).

![The Add new field dialog: Title Email, Slug email, the Type Email highlighted as step 4, Required field ticked, Helper text and Default value](/images/collections/create-a-collection/add-field.webp)

A field of type **file** takes images and stores each as an asset; set how
large one may be and how many one record holds.

![The Add new field dialog for a file field, Title Attachment, with Largest file (MB) highlighted as step 4 and Files per submission](/images/collections/create-a-collection/file-field.webp)

## 5. Check the fields

The version lists its fields with their slug, type, whether each is required,
and their help text and default value. Edit or delete a field here until the
version goes live.

![The version's fields, highlighted as step 5: Name (text, required), Email (email, required) and Message (text, not required)](/images/collections/create-a-collection/fields.webp)

## 6. Promote it live

Back on **Schema versions**, press **Promote** on the version and confirm with
**Promote**. The live version is the one records follow; a live version cannot
be edited, and promoting cannot be undone.

![The Promote to live dialog: Are you sure you want to promote this version to live? This action is irreversible, with the Promote button highlighted as step 6](/images/collections/create-a-collection/promote.webp)

Its **Status** now reads **Live**. A version promoted after it makes this one
**Deprecated**.

![Schema versions: v1 with 3 fields, version number 1, and the Live badge highlighted as step 7](/images/collections/create-a-collection/live.webp)

## 7. Add a record

Press **View records**, then **Add record**. Fill the fields and press
**Create record**.

![The Add Record dialog: Name Priya Shah, highlighted as step 8, Email priya.shah@acme.example, Message, and the Create record button](/images/collections/create-a-collection/add-record.webp)

**Edit** on a record changes it (**Save record**), and **Remove** deletes it.
Records a form sends in land here too, with the form in the **Form** column.

![All records: Priya Shah's record, with the Edit button highlighted as step 9 beside Remove](/images/collections/create-a-collection/records.webp)

## 8. Read the records in your app

```bash
curl -G https://api.console.buildbase.app/api/collections/data/contact-requests \
  -H "Authorization: $BUILDBASE_TOKEN" \
  --data-urlencode 'latest=true'
```

Which version a read returns, and the server SDK's helper, are in the
[records API](/collections/records-api).

## Change the fields later

Press **Create new version**: it starts with the live version's fields. It is a
**Draft** until you promote it, so change its fields while your app keeps
reading the live one.

![Schema versions: v2 with the Draft badge highlighted, version number 2 and its Promote button, above v1, Live](/images/collections/create-a-collection/new-version.webp)

Promote it when it is ready. The new version is **Live**, the old one
**Deprecated**, and `latest=true` reads only the records stored against the new
version ([choosing a version](/collections/records-api#choosing-a-version)).

## Check it works

`GET /api/collections/data/contact-requests?latest=true` returns the record you
added.

## Things to watch out for

- **A live version cannot be edited, and a promote cannot be undone.** Change the fields in a new version.
- **After a promote, `latest=true` returns only the records stored against the new version.** Read older ones with `version=<n>` ([choosing a version](/collections/records-api#choosing-a-version)).
- **A version with no fields cannot be promoted.**
- **Only the person who made a collection can delete it.**
- **Deleting a record leaves its files in Assets.**

## Next Steps

- [Create a form](/forms/create-a-form) - let visitors add records to this collection.
- [Collections overview](/collections/overview) - versions, field types and file fields.
- [Records API](/collections/records-api) - read and write records from your code.