Query Parameters

The generated API supports filtering, pagination, sorting, field selection, search, and total count via query parameters on GET list endpoints.

Filter Operators

Examples

# Filter by status
GET /api/v1/rooms?status=active

# Range query
GET /api/v1/rooms?capacity.gte=10&capacity.lte=50

# Pattern matching
GET /api/v1/rooms?name.like=conference

# Multiple values
GET /api/v1/rooms?roomType.in=meeting,conference,workshop

Pagination

GET /api/v1/rooms?limit=25&offset=50

The default limit can be configured per-resource in your definition:

crud: {
  list: {
    access: { roles: ["member"] },
    pageSize: 25,      // Default limit
    maxPageSize: 100,   // Maximum allowed limit
  },
},

Response Shape

{
  "data": [ /* records */ ],
  "pagination": {
    "limit": 25,
    "offset": 50,
    "count": 12
  }
}

• count — number of records returned on this page
• total — total matching records across all pages (only when ?total=true, see below)

Sorting

Sort by one or more fields. Use the - prefix for descending order.

Multi-Sort (Recommended)

# Sort by status ascending, then createdAt descending
GET /api/v1/rooms?sort=status,-createdAt

# Single field descending
GET /api/v1/rooms?sort=-createdAt

# Multiple fields
GET /api/v1/rooms?sort=priority,-createdAt,name

Legacy Format

The original sort + order format is still supported for backwards compatibility:

GET /api/v1/rooms?sort=name&order=desc

When the multi-sort format is detected (comma or - prefix), the order parameter is ignored.

Field Selection

Select which columns to return using ?fields=. Available on LIST and GET routes (not Views — they define their own field set).

# Return only id, name, and status
GET /api/v1/rooms?fields=id,name,status

# Combine with other query params
GET /api/v1/rooms?fields=id,name,status&status=active&sort=-createdAt

# Single record
GET /api/v1/rooms/rm_123?fields=id,name,capacity

All columns are available including system columns (id, organizationId, createdAt, modifiedAt, etc.). Invalid field names are silently ignored. If no valid fields are provided, all columns are returned.

Security: Masking still applies to selected fields. Requesting ?fields=ssn will return the masked value, not the raw data.

Total Count

Get the total number of matching records across all pages by adding ?total=true. Available on LIST and VIEW routes.

GET /api/v1/rooms?status=active&total=true

{
  "data": [ /* 25 records */ ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "count": 25,
    "total": 142
  }
}

This is opt-in because it runs an additional COUNT(*) query. Only use it when you need the total (e.g., for pagination UI).

Search

Full-text search across all text columns using ?search=. Available on LIST and VIEW routes.

# Search across all text fields
GET /api/v1/rooms?search=conference

# Combine with filters
GET /api/v1/rooms?search=conference&status=active

The search generates an OR'd LIKE condition across all text() columns in your schema:

WHERE (name LIKE '%conference%' OR description LIKE '%conference%')

Only columns defined with text() in your Drizzle schema are searchable. Non-text columns (integers, timestamps, UUIDs, blobs) are automatically excluded.

Complete Example

Combine all query parameters together:

GET /api/v1/rooms?fields=id,name,status,capacity&status=active&capacity.gte=10&search=conference&sort=capacity,-createdAt&limit=10&offset=20&total=true

This request:

1. Selects only id, name, status, capacity fields
2. Filters to active rooms with capacity >= 10
3. Searches text columns for "conference"
4. Sorts by capacity ascending, then createdAt descending
5. Paginates with 10 results starting at offset 20
6. Counts total matching records

Parameter Summary