Release Pages API ================ The Release Pages API allows you to retrieve information about release pages in Lighthouse. Release pages contain metadata about planned content releases and can be filtered by date, status, and other parameters. Endpoint ------- .. http:get:: /api/v2/pages/?type=releases.ReleasePage Return a list of release pages. :query type: **Required**. Set to ``releases.ReleasePage`` to retrieve release pages. :query limit: Maximum number of items to return (default: 200, max: 200) :query offset: Starting position for pagination (default: 0) :query fields: Comma-separated list of fields to include (default: id, title, meta). Use ``*`` for all fields. :query search: Full-text search across release titles and content. Searches within release titles and associated product names. :query search_operator: How to handle multiple search terms (``and`` requires all terms, ``or`` requires at least one term). Default: ``or`` :query expected_date_after: Filter for releases expected after this date (inclusive, ISO format: YYYY-MM-DD) :query expected_date_before: Filter for releases expected before this date (inclusive, ISO format: YYYY-MM-DD) :query expected_date: Filter for releases expected on an exact date (ISO format: YYYY-MM-DD) :query status: Filter by status code (``draft``, ``announced``, ``scheduled``, or ``published``) :query ordering: Field to sort by (e.g., ``expected_date`` or ``-expected_date`` for descending) :reqheader Authorization: Required. Token-based authentication. :statuscode 200: Success :statuscode 400: Bad request (invalid parameters) :statuscode 401: Authentication required :statuscode 403: Permission denied Request Example ------------- .. code-block:: http GET /api/v2/pages/?type=releases.ReleasePage&expected_date_after=2025-01-01&ordering=-expected_date HTTP/1.1 Host: lighthouse-api.yipit.systems Authorization: Token YOUR_API_TOKEN Response Example -------------- .. code-block:: json { "meta": { "total_count": 3 }, "items": [ { "id": 31, "meta": { "type": "releases.ReleasePage", "detail_url": "http://localhost/api/v2/pages/31/", "html_url": "http://localhost/investor/investor-releases/default-sector/tests/new-tests-release-5/", "slug": "new-tests-release-5", "first_published_at": "2025-05-12T17:13:58.305328-04:00" }, "title": "New Tests Release", "expected_date": "2025-06-15", "expected_time_period": "AM", "target_date": null, "content_scheduled": false, "status": { "code": "announced", "label": "Announced", "color": "#6366f1", "description": "Expected on 2025-06-15" }, "announcement_reports": [ { "id": 10, "title": "Report Type", "slug": "report-type", "url": "http://localhost/vertical/sector/product/product-reports/report-type/", "type": "EmailableIndexPage", "deliverable_id": null, "from_name": "YipitData", "model_group_slug": "slug", "products": [ { "id": 1, "name": "Test Product", "short_name": "test_product", "product_directory_id": "44058b08-03ec-4fb5-b3ca-24bcb6a7e5a1", "status": null } ], "child_pages": [] } ] }, { "id": 29, "meta": { "type": "releases.ReleasePage", "detail_url": "http://localhost/api/v2/pages/29/", "html_url": "http://localhost/investor/investor-releases/default-sector/tests/new-tests-release-3/", "slug": "new-tests-release-3", "first_published_at": "2025-05-12T17:12:56.781807-04:00" }, "title": "Another Release", "expected_date": "2025-05-20", "expected_time_period": "PM", "target_date": null, "content_scheduled": false, "status": { "code": "announced", "label": "Announced", "color": "#6366f1", "description": "Expected on 2025-05-20" }, "announcement_reports": [] } ] } Pagination ---------- The API uses offset-based pagination with a default page size of 200 items (maximum 200 items per page). **Pagination Parameters** - ``limit`` - Number of items per page (default: 200, max: 200) - ``offset`` - Starting position (default: 0) **Examples** .. code-block:: http # First 200 items (default) GET /api/v2/pages/?type=releases.ReleasePage HTTP/1.1 # First 50 items GET /api/v2/pages/?type=releases.ReleasePage&limit=50 HTTP/1.1 # Items 201-400 (second "page" of 200) GET /api/v2/pages/?type=releases.ReleasePage&offset=200 HTTP/1.1 # Items 51-100 (second "page" of 50) GET /api/v2/pages/?type=releases.ReleasePage&limit=50&offset=50 HTTP/1.1 # Combine with filters GET /api/v2/pages/?type=releases.ReleasePage&status=announced&offset=100&limit=50 HTTP/1.1 **Calculating Pagination** To paginate through all results: 1. Start with ``offset=0`` 2. Use your desired ``limit`` (up to 200) 3. For the next "page", set ``offset = previous_offset + limit`` 4. Continue until you receive fewer items than the limit (indicating the last page) For example, to get all results in chunks of 100: - Page 1: ``offset=0&limit=100`` (items 1-100) - Page 2: ``offset=100&limit=100`` (items 101-200) - Page 3: ``offset=200&limit=100`` (items 201-300) - Continue until fewer than 100 items are returned Search ------ The API supports full-text search across release titles and associated content using Wagtail's built-in search functionality. **Search Parameters** - ``search`` - Search term or phrase to match against release content - ``search_operator`` - How to handle multiple search terms (``and`` or ``or``, default: ``or``) **Examples** .. code-block:: http # Search for releases containing "weekly" GET /api/v2/pages/?type=releases.ReleasePage&search=weekly HTTP/1.1 # Search for releases with specific product (e.g., "Walmart") GET /api/v2/pages/?type=releases.ReleasePage&search=Walmart HTTP/1.1 # Search with multiple terms (all must match) GET /api/v2/pages/?type=releases.ReleasePage&search=weekly+report&search_operator=and HTTP/1.1 # Combine search with other filters GET /api/v2/pages/?type=releases.ReleasePage&search=weekly&status=announced&ordering=-expected_date HTTP/1.1 **Search with Specific Fields** .. code-block:: bash # Search for releases containing "June" and return only id and title curl -H "Authorization: Token YOUR_API_TOKEN" \ "http://localhost:8000/api/v2/pages/?type=releases.ReleasePage&search=June&fields=id,title" # Search for releases with a specific product and return basic fields curl -H "Authorization: Token YOUR_API_TOKEN" \ "http://localhost:8000/api/v2/pages/?type=releases.ReleasePage&search=Walmart&fields=id,title,expected_date" # Search and return all fields curl -H "Authorization: Token YOUR_API_TOKEN" \ "http://localhost:8000/api/v2/pages/?type=releases.ReleasePage&search=weekly&fields=*" **What Gets Searched** The search functionality indexes: - Release page titles - Associated product names (from announcement reports) - Other release content and metadata **Search Tips** - Use specific product names to find releases containing those products - Search terms are case-insensitive - Partial matches are supported (e.g., "week" will match "weekly") - Multiple terms with ``search_operator=or`` will find releases containing any of the terms - Multiple terms with ``search_operator=and`` will find releases containing all of the terms Field Definitions --------------- **Top-level Response Fields** .. list-table:: :header-rows: 1 :widths: 20 15 65 * - Field - Type - Description * - meta - object - Contains ``total_count`` (total number of release pages across all results) * - items - array - Array of release page objects **Release Page Object Fields** .. list-table:: :header-rows: 1 :widths: 20 15 65 * - Field - Type - Description * - id - integer - Unique identifier for the release page * - meta - object - Metadata about the page (type, URLs, etc.) * - title - string - Title of the release * - expected_date - string - Expected date of the release (ISO format: YYYY-MM-DD) * - expected_time_period - string - Expected time period (AM or PM, can be null) * - target_date - string - Scheduled publication date and time (ISO format with timezone, can be null) * - content_scheduled - boolean - Whether content for this release has been scheduled * - status - object - Current status information with code, label, color, and description * - announcement_reports - array - Report types only (EmailableIndexPage instances) - excludes feeds and other content types Announcement Reports Schema -------------------------- The ``announcement_reports`` field contains an array of report type objects (EmailableIndexPage instances). Each object in the array represents a report type that will be included in the announcement for this release. .. note:: The ``announcement_reports`` field only contains report types. It does not include feeds, dashboards, charts, or any other content types. Only EmailableIndexPage instances that represent report types are included in this field. Schema for each announcement report object: .. list-table:: :header-rows: 1 :widths: 25 15 60 * - Field - Type - Description * - id - integer - Unique identifier for the report type page * - title - string - Title of the report type * - slug - string - URL slug for the report type page * - url - string - Full URL to the report type page * - type - string - Page type (will be "EmailableIndexPage") * - deliverable_id - string - External deliverable identifier (can be null) * - from_name - string - Sender name for emails from this report type * - model_group_slug - string - Model group identifier for this report type * - products - array - Array of product objects associated with this report type * - child_pages - array - Array of child report pages under this report type Product object schema within ``products``: .. list-table:: :header-rows: 1 :widths: 25 15 60 * - Field - Type - Description * - id - integer - Unique identifier for the product * - name - string - Display name of the product * - short_name - string - Short name/code for the product * - product_directory_id - string - UUID identifier from the product directory * - status - string - Product status (can be null) Child page object schema within ``child_pages``: .. list-table:: :header-rows: 1 :widths: 25 15 60 * - Field - Type - Description * - id - integer - Unique identifier for the child page * - title - string - Title of the child page * - slug - string - URL slug for the child page * - date_published - string - Publication date (ISO format, can be null) * - subject_line - string - Email subject line for the report * - notable - boolean - Whether this is a notable report * - type - string - Page type of the child (e.g., "ReportPage") Status Values ------------- Status Codes: .. list-table:: :header-rows: 1 :widths: 20 80 * - Status Code - Description * - draft - Release is not live (unpublished), still being edited * - announced - Release is published with expected_date set but no target_date * - scheduled - Release is published with target_date set in the future * - published - Publication date is in the past (either expected_date or target_date) Filtering by Status ----------------- The ``status`` parameter allows you to filter releases by their current status code: * ``draft`` - Returns unpublished releases (``live=False``) * ``announced`` - Returns published releases with no target_date set (``live=True, target_date__isnull=True``) * ``scheduled`` - Returns published releases with future target_date (``live=True, target_date__isnull=False, target_date__gt=now``) * ``published`` - Returns releases with past publication dates (``Q(expected_date__lt=now.date()) | Q(target_date__lt=now)``) Example: .. code-block:: http GET /api/v2/pages/?type=releases.ReleasePage&status=scheduled HTTP/1.1 Filtering by Date Range --------------------- You can use date parameters to filter releases by their expected date: * ``expected_date_after`` - Returns releases expected on or after the specified date * ``expected_date_before`` - Returns releases expected on or before the specified date * ``expected_date`` - Returns releases expected on the exact date Examples: .. code-block:: http GET /api/v2/pages/?type=releases.ReleasePage&expected_date_after=2025-01-01&expected_date_before=2025-12-31 HTTP/1.1 GET /api/v2/pages/?type=releases.ReleasePage&expected_date=2025-05-15 HTTP/1.1 Sorting Results ------------- Use the ``ordering`` parameter to sort results: * ``ordering=expected_date`` - Sort by expected date in ascending order * ``ordering=-expected_date`` - Sort by expected date in descending order Example: .. code-block:: http GET /api/v2/pages/?type=releases.ReleasePage&ordering=-expected_date HTTP/1.1