> For the complete documentation index, see [llms.txt](https://docs.vomevolunteer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.vomevolunteer.com/resources/editor-4/search-shifts.md).

# Search Shifts

This endpoint allows for the efficient searching and filtering of shift records based on specified query parameters such as title, timing, capacity, opportunity, category, and created date. It is designed to support operations that require accessing detailed shift information quickly and effectively.

Endpoint and Usage:

Endpoint: `GET /api/shifts/search/`

Base URL: `https://api.vomevolunteer.com`

Query Parameters:

Core Filters

* `id` (uuid): Filters shifts by ID.
* `title` (string): Filters shifts by title.
* `shift_title` (string): Alias for `title`.
* `description` (string): Filters shifts by description.
* `shift_description` (string): Alias for `description`.
* `created_at` (string, ISO-8601): Filters shifts by exact `created_at`.
* `created_at.gt` (string, ISO-8601): Filters by `created_at > value`.
* `created_at.gte` (string, ISO-8601): Filters by `created_at >= value`.
* `created_at.lte` (string, ISO-8601): Filters by `created_at <= value`.
* `created_at.lt` (string, ISO-8601): Filters by `created_at < value`.
* `created_date` (string, ISO-8601 date): Filters by the date portion of `created_at`.
* `created_on` (string, ISO-8601 date): Alias for `created_date`.
* `created_date.gt` / `created_on.gt`: Filters by created date greater than value.
* `created_date.gte` / `created_on.gte`: Filters by created date greater than or equal to value.
* `created_date.lt` / `created_on.lt`: Filters by created date less than value.
* `created_date.lte` / `created_on.lte`: Filters by created date less than or equal to value.
* `ordering` (string): Sorts results by `created_at`, `shift_start_at`, `shift_end_at`, or `spots`, in ascending or descending order.

Shift Timing Filters

* `shift_date` (string, ISO-8601 date): Filters by the date portion of `shift_start_at`.
* `date` (string, ISO-8601 date): Alias for `shift_date`.
* `shift_date.gt` / `date.gt`: Filters by shift date greater than value.
* `shift_date.gte` / `date.gte`: Filters by shift date greater than or equal to value.
* `shift_date.lt` / `date.lt`: Filters by shift date less than value.
* `shift_date.lte` / `date.lte`: Filters by shift date less than or equal to value.
* `shift_start_at` (string, ISO-8601): Filters by exact shift start timestamp.
* `shift_start_at.gt`, `shift_start_at.gte`, `shift_start_at.lt`, `shift_start_at.lte`: Range filters for shift start timestamp.
* `shift_start_time` (string): Filters by the time portion of `shift_start_at`.
* `start_time` (string): Alias for `shift_start_time`.
* `shift_start_time.gt`, `shift_start_time.gte`, `shift_start_time.lt`, `shift_start_time.lte`: Range filters for shift start time.
* `shift_end_at` (string, ISO-8601): Filters by exact shift end timestamp.
* `shift_end_at.gt`, `shift_end_at.gte`, `shift_end_at.lt`, `shift_end_at.lte`: Range filters for shift end timestamp.
* `shift_end_time` (string): Filters by the time portion of `shift_end_at`.
* `end_time` (string): Alias for `shift_end_time`.
* `shift_end_time.gt`, `shift_end_time.gte`, `shift_end_time.lt`, `shift_end_time.lte`: Range filters for shift end time.

Capacity Filters

* `spots` (integer): Filters shifts by exact spot count.
* `spots.gt` (integer): Filters shifts by `spots > value`.
* `spots.gte` (integer): Filters shifts by `spots >= value`.
* `spots.lt` (integer): Filters shifts by `spots < value`.
* `spots.lte` (integer): Filters shifts by `spots <= value`.

Opportunity and Category Filters

* `opportunity.id` (uuid): Filters by related opportunity ID.
* `opportunity_id` (uuid): Alias for `opportunity.id`.
* `opportunity.title` (string): Filters by related opportunity title.
* `opportunity_title` (string): Alias for `opportunity.title`.
* `category.id` (uuid): Filters by related category ID.
* `category_id` (uuid): Alias for `category.id`.
* `category.title` (string): Filters by related category title.
* `category_title` (string): Alias for `category.title`.

Sample Requests

```http
# id
GET /api/shifts/search/?id=645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d

# title
GET /api/shifts/search/?title=morning

# opportunity role id
GET /api/shifts/search/?opportunity.id=2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1

# category id
GET /api/shifts/search/?category.id=d610ab31-e480-4ef1-9e35-94f94ebacde9

# shift date
GET /api/shifts/search/?shift_date=2026-02-12

# shift start time
GET /api/shifts/search/?start_time.gte=09:00

# shift end time
GET /api/shifts/search/?end_time.lte=17:00

# spots
GET /api/shifts/search/?spots.gte=2

# created_at
GET /api/shifts/search/?created_at=2026-02-05T07:40:29.324645Z

# ordering by shift start
GET /api/shifts/search/?ordering=shift_start_at

# ordering by spots descending
GET /api/shifts/search/?ordering=-spots
```

Authorization:

Requests to this endpoint require an `API-KEY` in the header for authentication.

```python
headers = {
    "API-KEY": "your_unique_api_key_here"
}

response = requests.get(
    "https://api.vomevolunteer.com/api/shifts/search/?title=morning&spots.gte=2",
    headers=headers
)
```

Response Structure:

The response from this endpoint returns a paginated list of shifts that match the query parameters, including timing, spot counts, and the public share URL for each shift.

Example Response Object:

```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
   {
   "id": "645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
   "created_at": "2026-02-05T07:40:29.324645Z",
   "shift_start_at": "2026-02-12T09:00:00Z",
   "shift_end_at": "2026-02-12T13:00:00Z",
   "spots": 10,
   "spots_reserved": 4,
   "spots_available": 6,
   "opportunity": {
    "id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
    "created_at": "2026-02-02T10:15:00Z",
    "category": {
      "id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
      "title": "Community Outreach",
      "description": "Programs and roles related to outreach work."
    },
    "title": "Weekend Mentor",
    "description": "Support volunteers during weekend sessions.",
    "share_opportunity_url": "https://api.vomevolunteer.com/api/share/opportunity/73bb56fa-6c7f-4fce-ad5a-32eb1ba215a6"
  },
  "shift_location": "123 Main Street",
  "shift_title": "Morning Shift",
  "shift_description": "Support setup and check-in.",
  "share_shift_url": "https://api.vomevolunteer.com/api/share/shift/645dfb6c-437c-42a9-9cf7-2eaf9c0fa87d",
  "title": "Morning Shift",
  "description": "Support setup and check-in."
}
]}
```

Example Response Structure

Summary Information

* `count`: Total number of matching shifts.
* `next`: URL for the next page of results, or `null`.
* `previous`: URL for the previous page of results, or `null`.

Shift Object

* `id`: Unique ID of the shift.
* `created_at`: Created timestamp of the shift.
* `shift_start_at`: Start timestamp of the shift.
* `shift_end_at`: End timestamp of the shift.
* `spots`: Total shift capacity.
* `spots_reserved`: Number of currently filled spots.
* `spots_available`: Number of remaining spots.
* `opportunity`: Related opportunity role object with nested category data.
* `shift_location`: Derived display location for the shift.
* `shift_title`: Stored shift title.
* `shift_description`: Stored shift description.
* `share_shift_url`: Public share URL for the shift.
* `title`: Alias of `shift_title`.
* `description`: Alias of `shift_description`.

Validation Rules

* Invalid date, datetime, time, or integer values return `400 Bad Request`.
* `ordering` only accepts `created_at`, `-created_at`, `shift_start_at`, `-shift_start_at`, `shift_end_at`, `-shift_end_at`, `spots`, or `-spots`.
* If no `ordering` is supplied, results default to `shift_start_at`, then `created_at`.

Example validation error:

```json
{
  "detail": "Invalid date format for shift_start_at."
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.vomevolunteer.com/resources/editor-4/search-shifts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.