All list endpoints in the OptiPub API support pagination, sorting, column selection, and query parameter filtering.

Pagination

Control which page of results you receive and how many items per page.

Parameter	Type	Description	Default
`page`	integer	The page number to return	`1`
`per_page`	integer	The number of results per page	`10`
`offset`	integer	Page offset (alternative to `page`)	—

GET /publications?page=2&per_page=25

Every list response includes pagination metadata you can use to navigate results:

{
  "current_page": 2,
  "per_page": 25,
  "total": 73,
  "last_page": 3,
  "next_page_url": "/publications?page=3&per_page=25",
  "prev_page_url": "/publications?page=1&per_page=25",
  "data": [ ... ]
}

Field	Description
`total`	Total number of records matching the query
`last_page`	The highest available page number
`next_page_url`	URL for the next page, or `null` if you're on the last page
`prev_page_url`	URL for the previous page, or `null` if you're on the first page

Use offset as an alternative to page when you need to skip a specific number of pages into the result set:
GET /messages?offset=5&per_page=10

Sorting

Order results by any sortable field using the sort parameter.

Parameter	Type	Format
`sort`	string	`column_name\|asc` or `column_name\|desc`

# Newest first
GET /messages?sort=created_at|desc

# Alphabetical by name
GET /publications?sort=name|asc

# Recently updated
GET /templates?sort=updated_at|desc

Common sortable columns:

Column	Description
`id`	Record ID
`name`	Name field
`title`	Title field
`created_at`	Creation timestamp
`updated_at`	Last modified timestamp
`active`	Active/inactive status
`email`	Email address
`date`	Date field

Available sortable columns vary by endpoint. Refer to the individual endpoint documentation for specifics.

Column Selection

By default, responses include all fields. Use columns[] to request only the fields you need — this reduces response size and can improve performance.

Parameter	Type	Description
`columns[]`	string	A field to include in the response. Repeat for multiple fields.

GET /publications?columns[]=id&columns[]=name&columns[]=created_at

{
  "data": [
    { "id": 1, "name": "Daily Briefing", "created_at": "2024-03-15T10:30:00Z" },
    { "id": 2, "name": "Weekly Digest", "created_at": "2024-06-01T14:00:00Z" }
  ]
}

Filtering

Filter results by passing column names as query parameters. Any column on the resource can be used as a filter — the behavior depends on the column's data type.

String Columns

String filters are case-insensitive and support pattern matching with ^ and $ operators:

Syntax	Behavior	Example
`value`	Contains	`name=daily` — matches "Daily Briefing", "My Daily Report"
`^value`	Starts with	`name=^daily` — matches "Daily Briefing" but not "My Daily Report"
`value$`	Ends with	`name=report$` — matches "My Daily Report" but not "Report Card"
`^value$`	Exact match	`name=^Daily Briefing$` — matches only "Daily Briefing"

# Subscriptions where email starts with "john"
GET /subscriptions?email=^john

# Templates with names ending in "promo"
GET /templates?name=promo$

Numeric Columns

Numeric filters support comparison operators as a prefix on the value:

Operator	Meaning	Example
(none)	Equals	`id=5`
`=`	Equals	`id==5`
`>`	Greater than	`id=>100`
`>=`	Greater than or equal	`id=>=100`
`<`	Less than	`id=<50`
`<=`	Less than or equal	`id=<=50`

# Messages with ID greater than 500
GET /messages?id=>500

Date Columns

Date filters use the same comparison operators as numeric columns:

# Resources created after a specific date
GET /resources?created_at=>=2025-01-01

# Subscriptions updated before a date
GET /subscriptions?updated_at=<2025-06-01

Boolean Columns

Pass true or false:

# Only active subscriptions
GET /subscriptions?active=true

Array Filtering

Pass the same parameter multiple times to match any of the values (IN query):

# Subscriptions for publication 1 or 3
GET /subscriptions?publication_id[]=1&publication_id[]=3

Combining Filters

All filter types can be combined in a single request:

GET /subscriptions?publication_id=3&active=true&email=^john&created_at=>=2025-01-01

Combining Parameters

All parameters can be used together in a single request:

GET /messages?publication_id=5&sort=created_at|desc&page=1&per_page=50&columns[]=id&columns[]=subject&columns[]=created_at

This fetches the first 50 messages for publication 5, sorted newest first, returning only id, subject, and created_at.