Newsroom News API - PortalHQ KB

The Newsroom News API exposes published newsletter issues as JSON, so other systems can pull and display them. The school website is the most common consumer — a Latest News widget on the homepage that’s always up to date because it pulls live from PortalHQ.

What the API returns

Endpoints return JSON for:

Published issues — the list of all published issues, most recent first.
A single issue — title, publication date, sections, submissions, images.
Submissions / news items — individual content pieces with their parent issue and section.
Issue archive — paginated history.

The response includes the full text content, headlines, byline, images and links — everything you need to render the issue on a non-PortalHQ page.

Common use cases

School website “Latest News” feed — pulls the most recent 3-5 issues and displays a snippet of each.
Mobile app news view — pulls published submissions for in-app display.
Year-level newsletter archives — filter the news API by tag to show parents only the issues relevant to their year.
External archive search — index news content for site-wide search outside PortalHQ.

Authentication

The News API supports two access modes:

Public — published-only content, no auth required. Used by school websites.
Authenticated — full content including drafts, only with an API token. Used by internal integrations.

Public mode is read-only. Authenticated mode can be used to manage issues programmatically (creating, updating, publishing) where supported.

Endpoints

The exact endpoint URLs and schema are documented in the Swagger UI at /doc/swagger/ on your PortalHQ instance. The most common endpoints:

Endpoint	What it returns
`GET /newsroom/api/issues/`	List of published issues.
`GET /newsroom/api/issues/{id}/`	Single issue with all content.
`GET /newsroom/api/submissions/`	List of submissions across issues.
`GET /newsroom/api/submissions/{id}/`	Single submission.
`GET /newsroom/api/issues/?category={slug}`	Filter by category.
`GET /newsroom/api/issues/?tag={slug}`	Filter by tag.

Pagination, sorting and filtering work via standard query parameters.

Response format

All responses are JSON. A typical issue response includes:

{
  "id": "...",
  "title": "Term 2 Newsletter — Week 4",
  "publication_date": "2026-05-27",
  "category": "weekly-newsletter",
  "cover_image": "https://...",
  "sections": [
    {
      "name": "From the Principal",
      "submissions": [
        {
          "title": "...",
          "content": "...",
          "image": "..."
        }
      ]
    }
  ]
}

The exact fields vary — check the Swagger schema for the current contract.

Rate limits

The public API has rate limits to protect the service. Schools embedding the feed on their website don’t normally hit limits — the website caches the response. If you have a high-traffic integration, talk to PortalHQ support about token-based authenticated access with higher limits.

Caching

The API responds quickly but for production websites, cache the response at the consumer side:

5-15 minutes for a news feed widget.
Until next published issue for an issue archive (use the publication-date field to know when to invalidate).

CORS

For browser-based consumers (a school website’s JavaScript pulling the feed), PortalHQ supports CORS for known origins. Talk to PortalHQ support to whitelist your website’s domain.

Common issues

Empty response — usually means no published issues yet. Confirm at least one issue is in Published status.
403 Forbidden — authentication required for the endpoint you’re hitting. Use the public endpoint or include a token.
Stale content — your consumer is caching. Bust the cache or reduce TTL.

Documentation

See the Swagger UI at /doc/swagger/ for the live schema and to try requests against your school’s data. The Newsroom integrations section lists every endpoint with parameters and example responses.