Search and filter posts using Ransack gem query parameters. Returns filtered results based on the provided search criteria.

Ransack Predicates

Common predicates you can use:

  • _eq: Equal to

  • _cont: Contains (case insensitive)

  • _start: Starts with

  • _end: Ends with

  • _gt: Greater than

  • _gteq: Greater than or equal to

  • _lt: Less than

  • _lteq: Less than or equal to

  • _in: In array

  • _null: Is null

  • _not_null: Is not null

Sorting

Use q parameter for sorting:

  • q=created_at desc

  • q=title asc

  • q=author_id desc

Examples

  • Search by title: ?q=rails

  • Search by author: ?q=123

  • Date range: ?q=2024-01-01&q=2024-12-31

  • Multiple authors: ?q[]=1&q[]=2

Errors

Code Description
401 Unauthorized - Invalid or missing token
422 Unprocessable Entity - Invalid search parameters

Examples

# Simple title search
curl -X GET "https://your-domain.com/api/v2/posts/search?q[title_cont]=rails" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

# Complex search with multiple filters
curl -X GET "https://your-domain.com/api/v2/posts/search?q[title_cont]=guide&q[author_id_eq]=123&q[created_at_gteq]=2024-01-01&q[s]=created_at%20desc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

# Search multiple authors
curl -X GET "https://your-domain.com/api/v2/posts/search?q[author_id_in][]=1&q[author_id_in][]=2&q[s]=title%20asc" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json"

Success Response (200):
[
  {
    "id": 1,
    "title": "Rails Guide",
    "content": "A comprehensive rails guide...",
    "author_id": 123,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
]

Empty Results (200):
[]

Error Response (401):
{
  "error": "Unauthorized"
}

Params

Param name Description
q
optional

Ransack query parameters for filtering and sorting posts

Validations:

  • Must be a Hash

q[title_cont]
optional

Title contains text (case insensitive)

Validations:

  • Must be a String

q[title_eq]
optional

Title equals exact text

Validations:

  • Must be a String

q[title_start]
optional

Title starts with text

Validations:

  • Must be a String

q[title_end]
optional

Title ends with text

Validations:

  • Must be a String

q[content_cont]
optional

Content contains text

Validations:

  • Must be a String

q[author_id_eq]
optional

Author ID equals

Validations:

  • Must be a Integer

q[author_id_in]
optional

Author ID in list

Validations:

  • Must be an array of any type

q[created_at_gteq]
optional

Created at greater than or equal to date (YYYY-MM-DD)

Validations:

  • Must be a String

q[created_at_lteq]
optional

Created at less than or equal to date (YYYY-MM-DD)

Validations:

  • Must be a String

q[created_at_gt]
optional

Created at greater than date

Validations:

  • Must be a String

q[created_at_lt]
optional

Created at less than date

Validations:

  • Must be a String

q[updated_at_gteq]
optional

Updated at greater than or equal to date

Validations:

  • Must be a String

q[updated_at_lteq]
optional

Updated at less than or equal to date

Validations:

  • Must be a String

q[id_eq]
optional

Post ID equals

Validations:

  • Must be a Integer

q[id_gt]
optional

Post ID greater than

Validations:

  • Must be a Integer

q[id_lt]
optional

Post ID less than

Validations:

  • Must be a Integer

q[id_in]
optional

Post ID in list

Validations:

  • Must be an array of any type

q[s]
optional

Sort by field and direction (e.g., “created_at desc”, “title asc”)

Validations:

  • Must be a String

Headers

Header name Description
Authorization
required
Bearer token for authentication
uid
optional
User email (required for devise_token_auth)
client
optional
Client ID (required for devise_token_auth)