Records are the data entries stored within collections. Learn how to create, read, update, delete, filter, sort, and expand records.

Records

Records are the data entries stored within collections. This guide covers all CRUD operations and advanced querying capabilities.

localhost:8000/admin/collections/posts/records

posts

5 records · base collection

Search records…

ID	title	status	created
rec_1a2b	Getting Started with FastCMS	published	2026-03-01
rec_3c4d	Building Your First Collection	published	2026-03-01
rec_5e6f	Authentication Deep Dive	draft	2026-03-02
rec_7g8h	Real-time with SSE	draft	2026-03-02
rec_9i0j	Deploying to Production	published	2026-02-28

Quick Start

# Create a record
curl -X POST http://localhost:8000/api/v1/collections/posts/records \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"title": "Hello World", "content": "My first post"}}'

# List records
curl http://localhost:8000/api/v1/collections/posts/records \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get single record
curl http://localhost:8000/api/v1/collections/posts/records/RECORD_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

# Update record
curl -X PATCH http://localhost:8000/api/v1/collections/posts/records/RECORD_ID \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"data": {"title": "Updated Title"}}'

# Delete record
curl -X DELETE http://localhost:8000/api/v1/collections/posts/records/RECORD_ID \
  -H "Authorization: Bearer YOUR_TOKEN"

Create a Record

POST /api/v1/collections/{collection_name}/records
Authorization: Bearer <token>
Content-Type: application/json

{
  "data": {
    "title": "My Post",
    "content": "Post content here",
    "published": true,
    "tags": ["news", "tech"]
  }
}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "data": {
    "title": "My Post",
    "content": "Post content here",
    "published": true,
    "tags": ["news", "tech"]
  },
  "created": "2025-12-22T10:30:00Z",
  "updated": "2025-12-22T10:30:00Z"
}

List Records

Query Parameters

Parameter	Type	Default	Description
`page`	int	1	Page number
`per_page`	int	20	Items per page (max: 100)
`sort`	string	—	Sort fields
`filter`	string	—	Filter expression
`search`	string	—	Full-text search
`expand`	string	—	Relations to expand
`fields`	string	—	Fields to return
`skipTotal`	bool	false	Skip total count for faster queries

Filtering

Operator	Description	Example
`=`	Equal	`status=active`
`!=`	Not equal	`status!=deleted`
`>`	Greater than	`age>18`
`>=`	Greater or equal	`views>=100`
`<`	Less than	`price<100`
`<=`	Less or equal	`stock<=10`
`~`	Contains (case-insensitive)	`title~hello`
`!~`	Does not contain	`title!~spam`
`?=`	Any in array	`tags?=[news,tech]`
`?!=`	Not in array	`category?!=[spam,ads]`

Combining Filters

# AND: Both conditions must be true
?filter=published=true&&views>100

# OR: Either condition can be true
?filter=featured=true||popular=true

# Complex
?filter=(status=active||status=pending)&&verified=true

DateTime Macros

Macro	Description
`@now`	Current datetime
`@today`	Start of today
`@yesterday`	Start of yesterday
`@day+7`	7 days from now
`@hour-2`	2 hours ago

# Records created today
?filter=created>=@today

# Records from the last 7 days
?filter=created>@day-7

Sorting

# Ascending
?sort=created

# Descending
?sort=-created

# Multi-field
?sort=-created,+title

# Random
?sort=@random

Expanding Relations

# Single relation
?expand=author

# Multiple relations
?expand=author,category,tags

# Nested relations
?expand=author.company

Full-Text Search

?search=hello world

Searches across all text, editor, email, and url fields.

Pagination

# Standard pagination
?page=2&per_page=50

# Skip total count for performance on large datasets
?skipTotal=true

JavaScript Examples

// Fetch records
const response = await fetch(
  'http://localhost:8000/api/v1/collections/posts/records?page=1&per_page=10&sort=-created',
  { headers: { 'Authorization': `Bearer ${token}` } }
);
const data = await response.json();

// Complex query
const params = new URLSearchParams({
  page: '1',
  per_page: '20',
  sort: '-created,+title',
  filter: 'published=true&&views>100',
  expand: 'author,category',
  fields: 'id,title,author,views,created'
});

const response = await fetch(
  `http://localhost:8000/api/v1/collections/posts/records?${params}`,
  { headers: { 'Authorization': `Bearer ${token}` } }
);

React Hook Example

import { useState, useEffect } from 'react';

function useRecords(collection, options = {}) {
  const [records, setRecords] = useState([]);
  const [loading, setLoading] = useState(true);
  const [pagination, setPagination] = useState({});

  useEffect(() => {
    const fetchRecords = async () => {
      setLoading(true);
      const params = new URLSearchParams({
        page: options.page || 1,
        per_page: options.perPage || 20,
        ...(options.sort && { sort: options.sort }),
        ...(options.filter && { filter: options.filter }),
        ...(options.expand && { expand: options.expand }),
      });

      const res = await fetch(
        `http://localhost:8000/api/v1/collections/${collection}/records?${params}`,
        { headers: { 'Authorization': `Bearer ${localStorage.getItem('token')}` } }
      );

      const data = await res.json();
      setRecords(data.items);
      setPagination({ total: data.total, page: data.page, totalPages: data.total_pages });
      setLoading(false);
    };

    fetchRecords();
  }, [collection, JSON.stringify(options)]);

  return { records, loading, pagination };
}

Bulk Operations — batch create, update, and delete
CSV Import/Export — import and export as CSV
Access Control — permission rules for records
Real-time — subscribe to record changes

Records

posts

On this page