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

GET /api/v2/pages/?type=releases.ReleasePage

Return a list of release pages.

Query Parameters:

type – Required. Set to releases.ReleasePage to retrieve release pages.
limit – Maximum number of items to return (default: 200, max: 200)
offset – Starting position for pagination (default: 0)
fields – Comma-separated list of fields to include (default: id, title, meta). Use * for all fields.
search – Full-text search across release titles and content. Searches within release titles and associated product names.
search_operator – How to handle multiple search terms (and requires all terms, or requires at least one term). Default: or
expected_date_after – Filter for releases expected after this date (inclusive, ISO format: YYYY-MM-DD)
expected_date_before – Filter for releases expected before this date (inclusive, ISO format: YYYY-MM-DD)
expected_date – Filter for releases expected on an exact date (ISO format: YYYY-MM-DD)
status – Filter by status code (draft, announced, scheduled, or published)
ordering – Field to sort by (e.g., expected_date or -expected_date for descending)

Request Headers:

Authorization – Required. Token-based authentication.

Status Codes:

200 OK – Success
400 Bad Request – Bad request (invalid parameters)
401 Unauthorized – Authentication required
403 Forbidden – Permission denied

Request Example

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

{
    "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

# 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:

Start with offset=0
Use your desired limit (up to 200)
For the next “page”, set offset = previous_offset + limit
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

# 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

# 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

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

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:

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:

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:

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:

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:

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:

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:

GET /api/v2/pages/?type=releases.ReleasePage&ordering=-expected_date HTTP/1.1