Lists

What lists are

A list is structured data: rows with the fields you define, like a lightweight database. Use lists for reading logs, trackers, inventories and anything else with columns. A list can hold up to 50,000 rows.

Find your lists at Lists. The filters show My lists, Shared with me, Watching, Deleted and All. The overview can be shown as Cards, Data grid, Tree or Entity diagram, which draws your lists and the connections between them.

Creating a list

1. On Lists, choose New list.
2. Define the fields in one of three ways:
   • Build fields: add each field yourself.
   • From a template: start from a built-in or saved template, with its example rows.
   • Describe it (AI): describe the list and let AI propose fields. See AI assistance.
3. Give it a Title, an optional Description and a Visibility: Private, Anyone with the link, or Public.
4. Optionally choose a Folder and a Parent list.
5. Choose Create list.

Import CSV on the Lists page creates a list from a spreadsheet file instead.

Fields

Open Fields in a list to add, edit, reorder or archive fields. Each field has a label, a type, and options such as Required, Hidden, a placeholder, help text, a default value and validation.

Schema changes never destroy data:

• Changing a field's type first checks your rows with Check rows and reports any values that won't fit the new type. The stored data isn't rewritten.
• Archiving a field keeps its data for 30 days. Restore it from the archived fields at the bottom of the Fields window.

A field can also be shown only when other fields match conditions, using Show this field when…. See the schema reference below.

Adding and editing rows

• Type in the table. Click a cell to edit it. Arrow keys move between cells, and Alt+↑/↓ moves a row.
• Use the form. Add row opens a form. Tick Add another after saving to enter several rows in a row.
• Paste from a spreadsheet. Paste tab-separated cells into the table. Extra lines become new rows, and you can undo the paste.
• Import a CSV. Import maps the file's columns to your fields. All rows are checked first, and either all are saved or none are.

Open a row to see its Details, Comments (with @mentions) and History, where you can restore an earlier version.

If someone else changed the same field while you were editing, a Resolve edit conflict window lets you keep yours, take theirs, or merge them. Changes from others appear live.

Views

Each list can have several views, of five kinds: Table, Kanban, Calendar, Gallery and Tree. A view keeps its own filters, sorting, hidden fields and grouping.

• Views are personal unless an owner or manager shares them with everyone who can open the list.
• Fork to personal view makes your own copy of a shared view.
• Make my default and Make default for everyone set which view opens first.

Organizing lists

• Folders: create folders on the Lists page. Names are up to 80 characters and must be unique within their parent. Deleting a folder moves its lists up to the parent folder.
• Child lists: give a list a parent to build a hierarchy, with breadcrumbs. Add child list creates one directly.
• Connections: Connect lists draws a labelled link from one list to another. Link-to-row fields connect lists too.

The More list actions menu on a list also has Settings…, Duplicate…, Save as template…, Transfer ownership… and Delete list…. Deleted lists can be restored from the Deleted filter.

Sharing and publishing

Choose Share to invite people by handle or email, or to create a share link. Roles are:

Share links can be viewer, commenter or editor links, with an expiry (never, 1 day, 7 days or 30 days) and an optional password. Viewer and commenter links work without an account. Choose Revoke to turn a link off. A list in a shared folder is shared with the people who have access to that folder.

Public lists have a read-only page at /@handle/lists/…, an RSS feed of new rows, and appear on your profile. Signed-in visitors can Watch a list to hear about changes.

GitHub-backed lists

A GitHub-backed list mirrors a repository's issues as rows, with a fixed set of fields. Choose Refresh from GitHub to pull the latest issues. Connect GitHub first in Settings → Integrations.

Exporting

Export on a list downloads it as CSV, JSON or Markdown. To export many lists at once, see Export your data.

Schema reference

Behind the Fields window, every list has a schema: a JSON document that lists its fields. It's the only schema format. The Fields window writes it for you, and you see it directly when you use the API: pass a fields array to POST /v1/lists, or add one field with POST /v1/lists/{id}/fields. A list's JSON export includes its fields in the same shape.

{
  "schema_version": 1,
  "fields": [
    { "key": "title", "label": "Title", "type": "text", "required": true, "display_order": 0 },
    { "key": "status", "label": "Status", "type": "select", "display_order": 1,
      "options": [{ "value": "todo", "label": "To do" }, { "value": "done", "label": "Done" }] },
    { "key": "done_on", "label": "Done on", "type": "date", "display_order": 2,
      "visibility": { "all": [{ "field": "status", "op": "eq", "value": "done" }] } }
  ]
}

A schema holds up to 200 fields, and each key must be unique.

Field properties

Field types

Validation

validation can include:

• min and max for numbers, currency and ratings.
• integer: true for whole numbers only.
• min_length, max_length and pattern (a regular expression) for text fields.
• multiple: true to allow several values in person, link-to-row, image and file fields, and max_selections to cap them.
• list_id, the target list for a link-to-row field.

Visibility rules

A visibility rule is a group: {"all": [...]} matches when every item matches (AND), and {"any": [...]} when at least one does (OR). Items are conditions, or more groups for nesting. A condition is {"field": "key", "op": "...", "value": ...} and can only refer to other fields in the same list.

Text comparisons ignore case. A required field that its rule hides isn't required.