# Newsroom News API 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: ```json { "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.