> 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-5/search-opportunities.md). # Search opportunities This endpoint allows for the efficient searching and filtering of opportunity role records based on specified query parameters such as title, description, category, status, and created date. It is designed to support operations that require accessing detailed opportunity role information quickly and effectively. **Endpoint and Usage:**\ **Endpoint:** `GET /api/opportunities/search/`\ **Base URL:** `https://api.vomevolunteer.com` **Query Parameters:** **Core Filters** * `id` (uuid): Filters opportunity roles by ID. * `title` (string): Filters opportunity roles by title. * `description` (string): Filters opportunity roles by description. * `status` (string): Filters opportunity roles by status. * `created_at` (string, ISO-8601): Filters opportunity roles 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`. * `ordering` (string): Sorts results by `created_at` or `-created_at`. **Opportunity Statuses** * `0`: Draft * `1`: Published * `2`: Unpublished **Sample Requests** ```http # id GET /api/opportunities/search/?id=2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1 # title GET /api/opportunities/search/?title=mentor # description GET /api/opportunities/search/?description=weekend # status GET /api/opportunities/search/?status=1 # created_at GET /api/opportunities/search/?created_at=2024-09-06T02:57:15.008656Z # created_at.gt GET /api/opportunities/search/?created_at.gt=2024-09-06T02:57:15.008656Z # created_at.gte GET /api/opportunities/search/?created_at.gte=2024-09-06T02:57:15.008656Z # created_at.lt GET /api/opportunities/search/?created_at.lt=2024-09-06T02:57:15.008656Z # created_at.lte GET /api/opportunities/search/?created_at.lte=2024-09-06T02:57:15.008656Z # ordering ascending GET /api/opportunities/search/?ordering=created_at # ordering descending GET /api/opportunities/search/?ordering=-created_at ``` **Category Filters**\ Search by related category fields: * `category.id` (uuid): Filters opportunity roles by the related category ID. * `category_id` (uuid): Alias for `category.id`. * `category.title` (string): Filters opportunity roles by the related category title. * `category_title` (string): Alias for `category.title`. **Sample Requests** ```http # category id GET /api/opportunities/search/?category.id=d610ab31-e480-4ef1-9e35-94f94ebacde9 # category_id alias GET /api/opportunities/search/?category_id=d610ab31-e480-4ef1-9e35-94f94ebacde9 # category title GET /api/opportunities/search/?category.title=Community Outreach # category_title alias GET /api/opportunities/search/?category_title=Community Outreach ``` **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/opportunities/search/?title=mentor&status=1", headers=headers ) ``` **Response Structure:**\ The response from this endpoint returns a paginated list of opportunities that match the query parameters, including details about each role’s related category and public share URL. **Example Response Object:** ```json { "count": 1, "next": null, "previous": null, "results": [ { "id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1", "created_at": "2026-02-05T07:40:29.324645Z", "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://www.vomevolunteer.com/opportunity-board/test%20organization/weekend%20mentor/2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1" } ] } ``` **Example Response Structure** **Summary Information** * `count`: Total number of matching opportunity roles. * `next`: URL for the next page of results, or `null`. * `previous`: URL for the previous page of results, or `null`. **Opportunity Role Object** * `id`: Unique ID of the opportunity role. * `category`: Related category information. * `category.id`: Unique ID of the category. * `category.title`: Title of the category. * `category.description`: Description of the category. * `title`: Title of the opportunity. * `description`: Description of the opportunity. * `share_opportunity_url`: Public share URL for the opportunity. This may be `null` if the role is not published. --- # 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-5/search-opportunities.md?ask=&goal= ``` `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.