Queries and Filters

Queries

Queries can be used to filter the data that is returned from the API based on specific criteria. Queries are passed as query parameters in the URL and are formatted as key=value. Multiple queries can be passed in a single request by separating them with an ampersand &.

Important

  • Queries are only available for GET requests to plural endpoints.
  • While it is not standard HTTP practice, the REST API will allow you to pass query parameters in the request body for GET requests as long as the correct Content-Type header is set. This may be useful when you need to force the type of a query parameter or when the query parameter is too long to fit in the URL.

Query Filters

Below are the available query filters that can be used with the REST API. Each filter has a specific name and format that must be followed. Filters can be used in combination with each other to create complex queries. To use a filter, simply add the filter name to the end of the field name in the query parameter separated by two underscores __.

Exact (exact)

Search for objects whose field value matches a given value exactly. This is assumed as the default query filter if no query filter is specified.

  • Name: exact
  • Examples:
    • https://pfsense.example.com/api/v2/examples?fieldname=example
    • https://pfsense.example.com/api/v2/examples?fieldname__exact=example

Starts With (startswith)

Search for objects whose field value starts with a given substring for non-array fields, or search for objects whose field value array starts with a given value for array fields.

  • Name: startswith
  • Example: https://pfsense.example.com/api/v2/examples?fieldname__startswith=example

Ends With (endswith)

Search for objects whose field value ends with a given substring for non-array fields, or search for objects whose field value array ends with a given value for array fields.

  • Name: endswith
  • Example: https://pfsense.example.com/api/v2/examples?fieldname__endswith=example

Contains (contains)

Search for objects whose field value contains a given substring for non-array fields, or search for objects whose field value array contains a given value for array fields.

  • Name: contains
  • Example: https://pfsense.example.com/api/v2/examples?fieldname__contains=example

Less Than (lt)

Search for objects whose field value is less than a given integer.

  • Name: lt
  • Example: https://pfsense.example.com/api/v2/examples?fieldname__lt=5

Less Than or Equal To (lte)

Search for objects whose field value is less than or equal to a given integer.

  • Name: lte
  • Example: https://pfsense.example.com/api/v2/examples?fieldname__lte=5

Greater Than (gt)

Search for objects whose field value is greater than a given integer.

  • Name: gt
  • Example: https://pfsense.example.com/api/v2/examples?fieldname__gt=5

Greater Than or Equal To (gte)

Search for objects whose field value is greater than or equal to a given integer.

  • Name: gte
  • Example: https://pfsense.example.com/api/v2/examples?fieldname__gte=5

Format (format)

Search for objects whose field value matches a given format.

  • Name: format
  • Examples:
  • https://pfsense.example.com/api/v2/examples?fieldname__format=ipv4
  • https://pfsense.example.com/api/v2/examples?fieldname__format=email

Supported Formats

  • ipv4: Search for objects whose field value is a valid IPv4 address.
  • ipv6: Search for objects whose field value is a valid IPv6 address.
  • ip: Search for objects whose field value is a valid IP address (IPv4 or IPv6).
  • subnetv4: Search for objects whose field value is a valid IPv4 subnet.
  • subnetv6: Search for objects whose field value is a valid IPv6 subnet.
  • subnet: Search for objects whose field value is a valid IP subnet (IPv4 or IPv6).
  • numeric: Search for objects whose field value is a valid numeric value.
  • email: Search for objects whose field value is a valid email address.
  • url: Search for objects whose field value is a valid URL.
  • mac: Search for objects whose field value is a valid MAC address.
  • fqdn: Search for objects whose field value is a valid Fully Qualified Domain Name (FQDN).
  • hostname: Search for objects whose field value is a valid hostname (without domain).
  • port: Search for objects whose field value is a valid port number.
  • portrange: Search for objects whose field value is a valid port range (separated by a colon :).
  • alias: Search for objects whose field value is an existing firewall alias's name.

Regex (regex)

Search for objects whose field value matches a given PCRE regular expression.

  • Name: regex
  • Example: https://pfsense.example.com/api/v2/examples?fieldname__regex=^example

Custom Query Filters

For advanced users, the REST API's framework allows for custom query filter classes to be added using PHP. Refer to Building Custom Query Filters for more information.

Pagination

Pagination can be used to limit the number of items returned in a single request. Pagination is controlled by two query parameters: limit and offset. The limit parameter specifies the number of items to return, and the offset parameter specifies the starting index of the items to return. Pagination is useful when working with large datasets to reduce the amount of data returned in a single request.

Important

  • Most endpoints do not impose a limit on the number of items returned by default. Refer to the endpoint's documentation to determine if a limit is imposed by default.
  • Pagination is only available for GET and DELETE requests to plural endpoints.
  • If combined with a query, pagination will be applied after the initial query is executed.