API endpoints ​
Every endpoint of the REST API (version 1.0.0), made from the same OpenAPI 3.1 description the tests check. How to sign in, page through lists and cache answers is in REST API.
Your first API call ​
Two requests check that your API works, in a couple of minutes, before you read anything else. You need only your site's address and a terminal or a browser: no account, no token and no setup in the admin.
In the commands, replace news.example.com with your site's address. Your base URL is your site's address followed by /api/v1 (Your base URL explains where to find it).
1. Fetch your site's name.
curl https://news.example.com/api/v1/site
In Windows PowerShell:
Invoke-RestMethod https://news.example.com/api/v1/site | ConvertTo-Json -Depth 5
Or open https://news.example.com/api/v1/site in your browser. The answer starts like this (shortened; the full answer is under GET /site):
{
"data": {
"name": "The Harbour Herald",
"tagline": "Independent news from Port Aurel and the valley",
"url": "https://news.example.com",
"language": "en",
"…": "…"
}
}
If you see your own site's name under data.name, your base URL is right and the API is working.
2. Fetch the two latest articles.
curl "https://news.example.com/api/v1/posts?limit=2"
In Windows PowerShell:
Invoke-RestMethod "https://news.example.com/api/v1/posts?limit=2" | ConvertTo-Json -Depth 5
The answer has your newest published articles under data, newest first, and meta.next_cursor to fetch the next ones (shortened; the full answer is under GET /posts):
{
"data": [
{
"id": 1,
"title": "Council approves £48m plan to rebuild the old harbour",
"url": "https://news.example.com/politics/council-approves-ps48m-plan-to-rebuild-the-old-harbour",
"published_at": "2026-10-20T18:12:47+00:00",
"category": {
"name": "Politics"
},
"author": {
"name": "Amara Okafor"
},
"…": "…"
},
{
"id": 34,
"title": "Election night: results as they come in",
"url": "https://news.example.com/elections/election-night-results-as-they-come-in",
"published_at": "2026-10-20T17:13:24+00:00",
"category": {
"name": "Elections"
},
"author": {
"name": "Amara Okafor"
},
"…": "…"
}
],
"meta": {
"per_page": 2,
"next_cursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDI2LTEwLTIwIDE3OjEzOjI0IiwiaWQiOjM0LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
}
}
Without limit you get 20 articles; the most is 50. To get the next page, send the same request with &cursor= and the next_cursor value (Paging through lists).
If it doesn't work:
| What you see | What it means | What to do |
|---|---|---|
| A web page (HTML) instead of JSON, or "Not Found" | The base URL is wrong, for example /api/v1 is missing or doubled. |
Copy the API address from App → Mobile app in your admin. |
{"data": []} from /posts |
The API works, but the site has no published articles yet. | Publish an article, or install the demo content, and try again. |
| "Could not resolve host", or a certificate error | The address or its HTTPS certificate is wrong. | Open your site in a browser first. Use the address exactly as you gave it to the installer (APP_URL in .env). |
429 Too Many Requests |
Too many requests from your network this minute. | Wait for the number of seconds in Retry-After. See Rate limits. |
When both requests work, you're ready: Sign-in tokens shows how readers sign in, and the endpoints below list everything else. Building an app on the API is a complete example in Dart.
Your base URL ​
Every path on this page is added to your own base URL, which is your site's address followed by /api/v1:
| Your site | Your base URL | GET /site is then |
|---|---|---|
https://example.com |
https://example.com/api/v1 |
https://example.com/api/v1/site |
https://news.example.com (a subdomain) |
https://news.example.com/api/v1 |
https://news.example.com/api/v1/site |
To find yours:
- Sign in to your admin panel and open App → Mobile app.
- The API address at the top is your base URL, ready to copy. The NewsLoop app needs it too, as
api_urlinwhitelabel.yaml. - To check it, open the base URL followed by
/sitein your browser. You should see your site's name in JSON.
The site address is the one you gave the installer (APP_URL in .env). Use https://: phones refuse plain http:// outside development. In the examples below, the base URL is https://news.example.com/api/v1.
Your site also serves the full description at <base URL>/openapi.json (OpenAPI 3.1). A Postman collection is in the download's Documentation/api folder; set its base_url variable to your base URL.
How it fits together ​
The app, and any client you build, only talks to your own server, through this API. How NewsLoop fits together shows every part and connection:
For a complete client in Dart, from fetching articles to handling a 401, see Building an app on the API. To show an article's content_html, with its related articles, see Showing an article's text.
Two flows run through many endpoints. Read them first; the endpoint details below then make sense.
Sign-in tokens ​
Reading needs no account. For a reader's own things (their account, bookmarks and likes), the app gets a token once, keeps it, and sends it with each of those requests. A 401 means the token no longer works: sign in again.
Each endpoint below says whether it needs a signed-in reader, is open to everyone, or is open to everyone with a token optional (the answer is then for that reader). Sign-in tokens, from start to finish has every step in words.
Subscribers-only articles and the meter (X-NF-Meter) ​
Only GET /posts/{post} uses this, and only for articles marked subscribers-only (is_premium: true). With a metered paywall, readers without a membership get a few of them free each month. Each answer brings meta.meter with a token, and the app sends that token back in the X-NF-Meter header with the next article, so the count carries on.
Subscribers-only articles has the details, including the meter, request by request.
Trying the API in Postman ​
The download includes a ready-made Postman collection with every endpoint: Documentation/api/newsloop.postman_collection.json.
1. Import it. In Postman, click Import, choose the file, and open the new NewsLoop API collection.
2. Set the variables. Click the collection's name, then the Variables tab:
| Variable | What to put there |
|---|---|
base_url |
Required. Your base URL, such as https://news.example.com/api/v1 (see Your base URL). It comes set to https://news.example.com/api/v1, an example address. |
token |
Leave it empty. Signing in fills it by itself (step 3). You can also paste a token here. |
meter_token |
Leave it empty. Opening a subscribers-only article fills it by itself, for the metered paywall. |
Click Save after changing them.
3. Sign in, so the requests that need an account work.
- Open Accounts → Sign in with email and password.
- In the Body tab, put a reader's
emailandpassword(anydevice_name, such asPostman). - Click Send. The answer is
200, and the collection saves itsdata.tokenin thetokenvariable.
To make a new test reader instead, send Accounts → Create an account: it saves the token the same way.
Every request that needs a signed-in reader, such as Accounts → The signed-in reader (GET /me), already has Authorization → Bearer Token set to {{token}}, so it now works. Requests where a token is optional, such as Articles → A whole article, send it too, so you see what that reader sees.
4. Path and query values. Paths such as /posts/:post take their value from the request's Params tab (it starts at 1: use an ID from Articles → Articles by data source and filters). Optional query values are listed there switched off; tick one to send it.
5. Sign out with Accounts → Sign this device out: it deletes the token on the site and empties the token variable.
Troubleshooting in Postman:
- A
401from a signed-in request:tokenis empty or no longer works. Sign in again (step 3). Could not get any response, or an HTML page:base_urlis wrong. Open<base URL>/sitein your browser to check it.429: you reached the rate limit. Wait the seconds in theRetry-Afterheader.
To make a collection that already points at your own site, run php artisan newsloop:api:postman in the site's folder. It writes storage/app/newsloop.postman_collection.json, with base_url set to your site's address.
Troubleshooting ​
Rate limits (429 Too Many Requests) ​
The limits:
| Who | Limit |
|---|---|
| Readers without a token | 60 requests a minute, per network address. Change it with NEWSLOOP_API_GUEST_LIMIT (Changing the limits) |
| Signed-in readers (a valid token) | 120 requests a minute, per reader. Change it with NEWSLOOP_API_MEMBER_LIMIT |
POST /auth/token, /auth/register, /auth/social, /auth/forgot-password |
5 a minute per email and address, and 20 a minute per address |
How you can tell: every answer has X-RateLimit-Limit (the limit) and X-RateLimit-Remaining (what's left this minute). Over the limit, the API answers:
HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
Retry-After: 11
X-RateLimit-Reset: 1793084463
Content-Type: application/json
{"message": "Too Many Attempts."}
Retry-After is the number of seconds to wait. X-RateLimit-Reset is the same moment as a Unix time.
How to handle it:
- Wait for
Retry-After, then send the request again. Don't retry straight away: every attempt counts. - Retry only a couple of times. If it keeps happening, slow down. A complete example in Dart shows one way.
- Watch
X-RateLimit-Remainingand slow down background work (such as polling a live blog) when it gets low. - Send the reader's token when you have one: signed-in readers get twice the limit, counted per reader rather than per network.
- Reuse answers with
ETagandIf-None-Match(below). A304still counts as a request, but is much faster.
Changing the limits (NEWSLOOP_API_GUEST_LIMIT) ​
The two limits in the table are settings in your site's .env file:
| Setting | What it limits | Default |
|---|---|---|
NEWSLOOP_API_GUEST_LIMIT |
API requests a minute from one network address, for requests without a valid token (readers who aren't signed in) | 60 |
NEWSLOOP_API_MEMBER_LIMIT |
API requests a minute from one signed-in reader, wherever they are | 120 |
Why you might raise the guest limit: the limit is counted per network address, not per phone. Phones on one mobile network, or everyone on one office or hotel Wi-Fi, can reach your site from the same address, and then they share the 60 between them. Opening the app makes several requests (the layout, the site, and the articles for each block on the home screen), so readers who share an address use up the 60 together. If your readers report "Too many requests" in the app, raise it.
Example: to allow three times as many requests from each address, put this line in .env (or change the one that is there):
NEWSLOOP_API_GUEST_LIMIT=180
What changes when you set it:
- Readers who aren't signed in can make 180 API requests a minute from each network address, instead of 60. The 181st request in a minute gets
429 Too Many Requests, withRetry-Aftersaying how many seconds to wait. - Every API answer to them shows the new limit in
X-RateLimit-Limit: 180, andX-RateLimit-Remainingcounts down from 180.
What doesn't change: the website's pages and the admin (they don't use these limits), signed-in readers (they use NEWSLOOP_API_MEMBER_LIMIT), and the extra limits on the sign-in endpoints (5 a minute per email and address, 20 per address), which stay to stop password guessing.
Making it take effect: save .env. The next request uses the new value. If you, or your host, ran php artisan optimize or php artisan config:cache, run php artisan optimize again after the change, because a cached configuration ignores .env until it is made again. To check it worked, run curl -i https://news.example.com/api/v1/site and look for X-RateLimit-Limit: 180 in the headers at the top.
Choosing a value: raise it step by step (120, 180, 300) rather than switching it off. A higher limit lets one address ask more of your server, so a very high value gives less protection against scripts copying your articles. Any whole number from 1 up works.
Behind a proxy or CDN (such as Cloudflare): your server may see the proxy's address instead of each reader's, so many more readers share one limit. If app readers see "Too many requests" often while your site is behind a proxy, raise the limit further, or ask a developer to set up Laravel's trusted proxies so the server sees each reader's own address.
Paging through lists (cursor) ​
GET /posts, /posts/{post}/comments, /posts/{post}/live-updates and /me/bookmarks come in pages:
"meta": {
"per_page": 20,
"next_cursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDI2LTA5LTIzIDE0OjM4OjE0IiwiaWQiOjEwLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
"prev_cursor": null
}
To get the next page, send the same request again with cursor set to meta.next_cursor.
Edge cases:
- The last page has
next_cursor: null. Stop there. - Keep everything else the same. A cursor is a position in one particular list: the date and ID of the last item. Send it with exactly the same
source, filters (such ascategory) andsortas the page it came from. With a differentsortor filters, you get a wrong page.limitmay change between pages. - Don't build or edit cursors. Pass them back exactly as you got them; they're safe in a URL as they are.
- A damaged or unknown cursor is ignored, not refused. You get the first page again, with
200. So if a "next page" starts with articles you already have, check that the cursor reached the API unchanged. - New articles while paging appear at the top of the first page, never in the middle of later pages. Because a cursor marks a position rather than a page number, paging never repeats or skips an article when new ones are published. Pull to refresh: load the first page again, without
cursor. - Articles taken down while paging are simply not in the next page.
- Short ranked lists have no pages:
source=featured,trending,breakingandeditorsPicksalways havenext_cursor: null. - Search pages by number:
GET /searchtakespage=2,page=3and so on. When new articles come in, results can shift between pages, so drop duplicates byid. - Page size:
limitis 1 to 50 (20 if you leave it out). Over 50 answers422.
304 Not Modified and ETag ​
Every 200 answer to a GET has an ETag, such as W/"393f03e95386126b0f0ba69fa138a811". To check for changes cheaply:
- Keep the answer and its
ETagtogether, per address. The address includes the query and the language:/posts?category=4and/posts?category=4&lang=arhave different ETags. - Next time, send the
ETagback exactly as you got it, inIf-None-Match. 304 Not Modifiedhas no body. Nothing changed: show your saved copy and keep itsETag. Don't parse the empty body as JSON.200means something changed: replace your copy and itsETag.
Things to know:
- Answers for readers without a token may be kept for up to a minute by the phone and by caches on the way: they carry
Cache-Control: public, max-age=60, stale-while-revalidate=300. The site itself renews its copy as soon as something is published or changed. For the newest live blog entries, usesince(Live blogs). - Signed-in answers are
private. Keep them on the phone only, never in a shared cache. - Subscribers-only articles opened with the meter are
no-store, so they never answer304: each opening counts. - Your HTTP library may handle this already. Android's OkHttp with a cache, and iOS's
URLSession, can sendIf-None-Matchand turn a304into the saved200themselves. Dart'sHttpClientand thehttppackage don't, so do it yourself as above. - A
304counts towards the rate limit, like any request.
Other common answers ​
| Answer | Usually means |
|---|---|
401 on an endpoint that needs a signed-in reader |
No token, or it stopped working. Sign in again (Sign-in tokens). Endpoints where a token is optional never answer 401. |
404 |
The article, section or page doesn't exist, or isn't published (yet). Also for a wrong path: check your base URL. |
422 |
Something in the request isn't valid. errors lists each field's problem. Show message to the reader; don't match on its words, which can change and are translated. |
| An HTML page instead of JSON | The address doesn't reach the API: check the base URL, and send Accept: application/json. |
| Answers in the wrong language | Send ?lang= or Accept-Language. Content-Language says which language you got. |
Versioning and changes ​
The API's version is in the address: /api/v1. GET /site also answers api_version: 1, and the OpenAPI description has the release version in info.version.
Version 1 doesn't break. As long as it is /api/v1, nothing your app uses is removed, renamed, or given another type or meaning, and no new required field is added to a request.
Changes that can come in any update (they are not breaking, so your app must be ready for them):
- new fields in answers;
- new endpoints;
- new optional query parameters and request fields;
- new values in fields that have a fixed list, such as an article's
typeor a component inGET /app/config; - new headers;
- reworded
messagetexts.
How to be ready:
- Ignore fields you don't know. Don't fail on them, and don't use strict decoding that refuses them.
- Handle unknown values in fixed lists: skip the item, or show it in a neutral way. (The NewsLoop app skips layout components it doesn't know.)
- Don't depend on the order of fields, or on
messagetexts. Use the status code and the keys inerrors. - Read the Changelog when you update the site. It lists API additions.
Breaking changes need a new version. If a change can't be made without breaking v1, it comes as /api/v2. Then:
/api/v1keeps working alongside/api/v2for at least 12 months after the release that adds v2, and in every release during that time, so installed apps go on working while you publish an update of your app;- the changelog and Upgrading to a new version announce v2 and list every difference;
- after that, v1 is removed only in a release whose changelog announced it at least one release ahead. A site you don't update keeps the API it has;
- a field that is no longer useful in v1 is kept (with an empty or default value) and marked as deprecated in the OpenAPI description and the changelog. It is not removed from v1.
What a deprecated field looks like. NewsLoop 1.0 has no deprecated fields yet. If one is ever replaced, both stay in the answer. For example, if a later version replaced an article's audio_url with an audio object, GET /posts/{post} would answer:
{
"data": {
"id": 14,
"title": "City council approves plan to rebuild the old harbour",
"audio_url": "https://news.example.com/uploads/audio/harbour.mp3",
"audio": {
"url": "https://news.example.com/uploads/audio/harbour.mp3",
"duration": 312
}
}
}
audio_url keeps the same value as before. The OpenAPI description (<base URL>/openapi.json) marks it with deprecated and names its replacement:
"audio_url": {
"type": ["string", "null"],
"deprecated": true,
"description": "Deprecated since 1.4: use audio.url. Kept in v1 with the same value."
}
A forward-compatible parser reads the new field first and falls back to the old one, so it works with sites before and after the change:
final audio = json['audio'] as Map<String, dynamic>?;
final audioUrl = (audio?['url'] ?? json['audio_url']) as String?;
When a deprecated field can no longer carry a value, it is null (or an empty list or false, matching its type), never missing.
Updating the NewsLoop site never needs a new release of your app for v1. See also The mobile app in the upgrade guide.
Endpoints ​
The examples are real answers from a site with the demo content, at the address https://news.example.com. Long lists show their first two items and long texts end in "…"; every field is as the API sends it.
Errors ​
Every error answers with JSON. Its message says what went wrong in plain words; validation errors (422) also list each field's problem under errors.
Example: wrong password. A validation error. Every 422 answer has this shape.
POST /api/v1/auth/token
Content-Type: application/json
{
"email": "sam.reader@example.com",
"password": "not-the-password",
"device_name": "Pixel 8"
}
Answer (422):
{
"message": "These credentials do not match our records.",
"errors": {
"email": [
"These credentials do not match our records."
]
}
}
Example: no token. Signed-in endpoints answer 401 without a valid token.
GET /api/v1/me
Answer (401):
{
"message": "Unauthenticated."
}
Example: not found. Missing articles, sections and pages answer 404.
GET /api/v1/posts/999999
Answer (404):
{
"message": "Not found."
}
Example. With a valid Google or Apple ID token, the answer is the same as POST /auth/token. An invalid one answers 422:
POST /api/v1/auth/social
Content-Type: application/json
{
"provider": "google",
"id_token": "eyJhbGciOiJSUzI1NiJ9.not-a-real-token",
"device_name": "Pixel 8"
}
Answer (422):
{
"message": "Sign-in with Google is not set up on this site.",
"errors": {
"provider": [
"Sign-in with Google is not set up on this site."
]
}
}
Example: limit reached. A reader who already has 1,000 saved articles. Nothing is added or removed.
POST /api/v1/me/bookmarks/sync
Content-Type: application/json
{
"add": [
{
"post_id": 1001,
"saved_at": "2026-10-20T08:30:00+00:00"
}
],
"remove": []
}
Answer (422):
{
"message": "You can save up to 1000 articles. Remove some to save more.",
"errors": {
"post_id": [
"You can save up to 1000 articles. Remove some to save more."
]
}
}
Example: more than 500 changes. The request had 501 objects in add. Nothing is added or removed, not even the removals: send the changes in batches of up to 500.
POST /api/v1/me/bookmarks/sync
Answer (422):
{
"message": "The add field must not have more than 500 items.",
"errors": {
"add": [
"The add field must not have more than 500 items."
]
}
}
Site ​
GET /site ​
The site: name, logo, languages and features. Call when the app starts. The layout comes from GET /app/config.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: The site. The
datais Site. - 304: Not modified since the ETag sent.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/site
Example answer (200)
{
"data": {
"name": "The Harbour Herald",
"tagline": "Independent news from Port Aurel and the valley",
"url": "https://news.example.com",
"logo": null,
"logo_dark": null,
"icon": null,
"contact_email": "newsroom@example.com",
"timezone": "UTC",
"language": "en",
"default_language": "en",
"languages": [
{
"code": "en",
"name": "English",
"native_name": "English",
"direction": "ltr",
"is_default": true
}
],
"features": {
"comments": true,
"guest_comments": true,
"show_author": true,
"show_reading_time": true,
"sign_in_with_google": false,
"sign_in_with_apple": false,
"memberships": false,
"free_premium_articles": 0,
"newsletter": true,
"push": false,
"ai_disclosure": "This article was written with the help of AI tools and checked by our editors."
},
"ads": {
"in_article_after": 3
},
"links": {
"membership": "https://news.example.com/membership",
"account": "https://news.example.com/account",
"privacy": "https://news.example.com/privacy",
"forgot_password": "https://news.example.com/forgot-password",
"play_store": null,
"app_store": null
},
"social": {},
"app": {
"icon": null,
"splash_image": null,
"splash_background": "#FFFFFF"
},
"api_version": 1
}
}
GET /app/config ​
The published app layout. The ETag is the layout hash. Send it in If-None-Match to download the layout only when it changed.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: The layout, as defined by the app_config JSON Schema (packages/schema). The
datais an object. - 304: Not modified since the ETag sent.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/app/config
Example answer (200)
{
"data": {
"version": 1,
"hash": "901c9ab147188003e1dd959b786ce9e3068ad10eaf5ee00dc6a507e779393c9e",
"published_at": "2026-10-20T20:13:26+00:00",
"config": {
"schemaVersion": 1,
"configVersion": 1,
"defaultLocale": "en",
"locales": [
"en"
],
"theme": {
"light": {
"primary": "#E11D2E",
"secondary": "#1D4ED8",
"background": "#FFFFFF",
"surface": "#F1F2F4",
"text": "#111114",
"mutedText": "#6B6F76",
"accent": "#F59E0B"
},
"dark": {
"primary": "#FF4D5A",
"secondary": "#60A5FA",
"background": "#0E0E10",
"surface": "#1B1B1F",
"text": "#F5F5F6",
"mutedText": "#A1A1AA",
"accent": "#FBBF24"
},
"fontFamily": "Inter",
"headingFontFamily": "Inter",
"radius": 16,
"spacing": 8,
"defaultMode": "system",
"appBar": {
"logo": "twoTone",
"accentText": "Loop",
"actions": [
"search",
"notifications"
]
}
},
"navigation": {
"type": "bottomTabs",
"items": [
{
"screen": "home",
"icon": "home",
"label": {
"en": "Home",
"ar": "الرئيسية"
}
},
{
"screen": "sections",
"icon": "grid_view",
"label": {
"en": "Categories",
"ar": "الأقسام"
}
}
]
},
"screens": {
"home": {
"kind": "home",
"pullToRefresh": true,
"components": [
{
"id": "chips",
"type": "categoryChips",
"props": {
"leadingLabel": {
"en": "Trending",
"ar": "الأكثر رواجاً"
},
"showAllButton": true
}
},
{
"id": "top",
"type": "heroSlider",
"props": {
"data": {
"source": "featured",
"limit": 5
},
"style": "spotlight",
"autoPlay": true
}
}
]
},
"sections": {
"kind": "custom",
"title": {
"en": "Categories",
"ar": "الأقسام"
},
"largeTitle": true,
"components": [
{
"id": "all",
"type": "categoryGrid",
"props": {
"columns": 2
}
}
]
},
"category": {
"kind": "category",
"largeTitle": true,
"showContent": false,
"pullToRefresh": true,
"components": [
{
"id": "chips",
"type": "categoryChips",
"props": {
"from": "subsections",
"leadingLabel": {
"en": "All",
"ar": "الكل"
}
}
},
{
"id": "top",
"type": "heroSlider",
"props": {
"data": {
"source": "current",
"limit": 5
},
"style": "spotlight",
"autoPlay": true
}
}
]
},
"article": {
"kind": "article",
"article": {
"badge": true,
"galleryCount": true,
"tags": true,
"reactions": true,
"quoteStyle": "accent"
},
"components": [
{
"id": "related",
"type": "featuredCarousel",
"props": {
"title": {
"en": "Related News",
"ar": "أخبار ذات صلة"
},
"data": {
"source": "related",
"limit": 6
},
"style": "tiles",
"showSeeAll": true,
"headerStyle": "bar"
}
}
]
},
"videos": {
"kind": "video",
"title": {
"en": "Videos",
"ar": "فيديو"
},
"largeTitle": true,
"components": []
},
"bookmarks": {
"kind": "bookmarks",
"title": {
"en": "Bookmarks",
"ar": "المحفوظات"
},
"components": []
},
"profile": {
"kind": "profile",
"title": {
"en": "Profile",
"ar": "حسابي"
},
"components": [
{
"id": "links",
"type": "quickLinks",
"props": {
"items": [
{
"label": {
"en": "Settings",
"ar": "الإعدادات"
},
"icon": "settings",
"link": "screen:settings"
},
{
"label": {
"en": "Saved",
"ar": "المحفوظات"
},
"icon": "bookmark",
"link": "screen:bookmarks"
}
]
}
}
]
},
"settings": {
"kind": "settings",
"title": {
"en": "Settings",
"ar": "الإعدادات"
},
"components": []
}
},
"settings": {
"forceUpdate": {
"android": "1.0.0",
"ios": "1.0.0"
},
"maintenance": {
"enabled": false
},
"pushTopics": [
"breaking",
"all"
],
"rateAppAfterLaunches": 10
}
}
}
}
GET /resolve ​
What a website address shows, for deep links.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
url |
query | string | A full address on this site, or a path. |
Answers:
- 200: What to open. The
datais an object. - 404: Nothing the app can open; open the address in the browser.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/resolve?url=http%3A%2F%2Fnews.example.com%2Fpolitics%2Fcouncil-approves-ps48m-plan-to-rebuild-the-old-harbour
Answer (200):
{
"data": {
"type": "post",
"id": 1,
"language": "en"
}
}
GET /openapi.json ​
This description.
Open to everyone. No token needed.
Answers:
- 200: OpenAPI 3.1.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example. The answer is the whole OpenAPI 3.1 description of the API; only its first fields are shown here.
GET /api/v1/openapi.json
Answer (200):
{
"openapi": "3.1.0",
"info": {
"title": "NewsLoop API",
"version": "1.0.0",
"description": "The REST API the NewsLoop mobile app uses. Version 1 never breaks: fields may be added, never removed or changed.\n\n**Languages.** Send `?lang=` or Accept-Lan…"
}
}
Articles ​
GET /posts ​
Articles by data source and filters.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
source (optional) |
query | latest, featured, trending, breaking, editorsPicks, category, tag, author, series, video, live |
A data source from the app layout. Default latest. featured, trending, breaking and editorsPicks are one ranked list, without further pages. |
category (optional) |
query | integer | Section ID, including its subsections. Required for source=category. |
tag (optional) |
query | integer | Required for source=tag. |
author (optional) |
query | integer | Required for source=author. |
series (optional) |
query | integer | Required for source=series. |
type (optional) |
query | article, video, audio, gallery, live |
|
sort (optional) |
query | newest, oldest, popular |
popular gives the most read of the last week, as one list. |
limit (optional) |
query | integer | Default 20. |
cursor (optional) |
query | string | From meta.next_cursor of the previous page. |
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Article cards, newest first unless sorted otherwise. The
datais list of PostCard. - 304: Not modified since the ETag sent.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/posts?limit=2
Example answer (200)
{
"data": [
{
"id": 1,
"type": "article",
"language": "en",
"title": "Council approves £48m plan to rebuild the old harbour",
"subtitle": "Work on new sea walls, a ferry pier and 600 homes will start next spring after a close vote.",
"excerpt": "Councillors voted 27 to 22 in favour after a six-hour debate, ending two years of argument over the future of the waterfront.",
"url": "https://news.example.com/politics/council-approves-ps48m-plan-to-rebuild-the-old-harbour",
"published_at": "2026-10-20T18:12:47+00:00",
"updated_at": "2026-10-20T20:13:24+00:00",
"reading_time": 1,
"is_featured": true,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 1,
"name": "Politics",
"slug": "politics",
"color": "#c8102e",
"url": "https://news.example.com/politics"
},
"author": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"avatar_url": null
},
"image": {
"id": 1,
"url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"original_url": "https://news.example.com/uploads/1/nkzdmalk1j5gupo1.jpg",
"thumb_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-thumb.webp",
"medium_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-medium.webp",
"large_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a harbour with cranes, boats and the city behind",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
},
{
"id": 34,
"type": "live",
"language": "en",
"title": "Election night: results as they come in",
"subtitle": "Follow every count and every speech with our reporters at the count centres.",
"excerpt": "Live from the Exhibition Hall, where all nine wards of Port Aurel are being counted.",
"url": "https://news.example.com/elections/election-night-results-as-they-come-in",
"published_at": "2026-10-20T17:13:24+00:00",
"updated_at": "2026-10-20T17:13:24+00:00",
"reading_time": 1,
"is_featured": true,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 2,
"name": "Elections",
"slug": "elections",
"color": "#c8102e",
"url": "https://news.example.com/elections"
},
"author": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"avatar_url": null
},
"image": {
"id": 2,
"url": "https://news.example.com/uploads/2/conversions/fktfqvw5czsqu2xs-large.webp",
"original_url": "https://news.example.com/uploads/2/fktfqvw5czsqu2xs.jpg",
"thumb_url": "https://news.example.com/uploads/2/conversions/fktfqvw5czsqu2xs-thumb.webp",
"medium_url": "https://news.example.com/uploads/2/conversions/fktfqvw5czsqu2xs-medium.webp",
"large_url": "https://news.example.com/uploads/2/conversions/fktfqvw5czsqu2xs-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a town hall with columns and a dome",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://news.example.com/api/v1/posts?limit=2&cursor=eyJwdWJsaXNoZWRfYXQiOiIyMDI2LTEwLTIwIDE3OjEzOjI0IiwiaWQiOjM0LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"
},
"meta": {
"path": "https://news.example.com/api/v1/posts",
"per_page": 2,
"next_cursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDI2LTEwLTIwIDE3OjEzOjI0IiwiaWQiOjM0LCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9",
"prev_cursor": null
}
}
GET /posts/{post} ​
A whole article. Who can call it: anyone. Most articles come back in full to every caller, with no token. Only articles marked subscribers-only (is_premium: true) depend on who is asking:
- No token, or a reader without a membership: the opening only, with
locked: true. - A token of a reader with an active membership (or of a staff account): the full article, with
locked: false. When memberships are switched off on the site, any signed-in reader gets the full article. - A metered paywall (a few free subscribers-only articles a month): readers without access also get
meta.meterwithlimit,remainingand atoken. Send that token back in theX-NF-Meterheader with the next article to keep counting; while free articles are left,lockedisfalse. See the meter flow in the REST API guide.
An invalid or expired token is treated like no token: this endpoint never answers 401. So send the reader's token when you have one, and nothing when you don't.
Open to everyone; a token is optional. Without Authorization you get the public answer. With a valid Authorization: Bearer <token>, the answer is for that reader. An invalid or expired token is treated like no token here: it never causes a 401.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Article ID. |
X-NF-Meter (optional) |
header | string | The meter token from the last article answer. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: The article. The
datais Post. - 304: Not modified since the ETag sent.
- 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/posts/1
Example answer (200)
{
"data": {
"id": 1,
"type": "article",
"language": "en",
"title": "Council approves £48m plan to rebuild the old harbour",
"subtitle": "Work on new sea walls, a ferry pier and 600 homes will start next spring after a close vote.",
"excerpt": "Councillors voted 27 to 22 in favour after a six-hour debate, ending two years of argument over the future of the waterfront.",
"url": "https://news.example.com/politics/council-approves-ps48m-plan-to-rebuild-the-old-harbour",
"published_at": "2026-10-20T18:12:47+00:00",
"updated_at": "2026-10-20T20:13:24+00:00",
"reading_time": 1,
"is_featured": true,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 1,
"name": "Politics",
"slug": "politics",
"color": "#c8102e",
"url": "https://news.example.com/politics"
},
"author": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"avatar_url": null
},
"image": {
"id": 1,
"url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"original_url": "https://news.example.com/uploads/1/nkzdmalk1j5gupo1.jpg",
"thumb_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-thumb.webp",
"medium_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-medium.webp",
"large_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a harbour with cranes, boats and the city behind",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
},
"coauthors": [],
"content_html": "<p>Port Aurel city council has approved a £48 million plan to rebuild the old harbour, ending two years of argument over the future of the waterfront. Counci…",
"locked": false,
"word_count": 173,
"tags": [
{
"id": 1,
"name": "Housing",
"slug": "housing"
},
{
"id": 2,
"name": "Transport",
"slug": "transport"
}
],
"sections": [
{
"id": 1,
"name": "Politics",
"slug": "politics",
"color": "#c8102e",
"url": "https://news.example.com/politics"
}
],
"series": {
"id": 1,
"title": "The Harbour Project",
"slug": "the-harbour-project",
"position": 1,
"url": "https://news.example.com/series/the-harbour-project"
},
"source": null,
"audio_url": null,
"ai_assisted": false,
"ai_disclosure": null,
"comments": {
"open": true,
"guests": true,
"count": 2
},
"likes": {
"count": 0,
"liked": false
},
"translations": []
}
}
Example: not found. Missing articles, sections and pages answer 404.
GET /api/v1/posts/999999
Answer (404):
{
"message": "Not found."
}
GET /posts/{post}/related ​
Related articles.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Article ID. |
limit (optional) |
query | integer | Default 4. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Best matches first. The
datais list of PostCard. - 304: Not modified since the ETag sent.
- 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/posts/1/related?limit=2
Example answer (200)
{
"data": [
{
"id": 8,
"type": "article",
"language": "en",
"title": "Port traffic hits a record as new cranes come into use",
"subtitle": "The port handled 1.8 million containers last year, up 12 per cent.",
"excerpt": "Two new cranes have cut the time a ship spends at the quay by almost a third.",
"url": "https://news.example.com/business/port-traffic-hits-a-record-as-new-cranes-come-into-use",
"published_at": "2026-10-20T15:13:12+00:00",
"updated_at": "2026-10-20T15:13:12+00:00",
"reading_time": 1,
"is_featured": true,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 4,
"name": "Business",
"slug": "business",
"color": "#0f766e",
"url": "https://news.example.com/business"
},
"author": {
"id": 3,
"name": "Daniel Reyes",
"slug": "daniel-reyes",
"job_title": "Business reporter",
"avatar_url": null
},
"image": {
"id": 1,
"url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"original_url": "https://news.example.com/uploads/1/nkzdmalk1j5gupo1.jpg",
"thumb_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-thumb.webp",
"medium_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-medium.webp",
"large_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a harbour with cranes, boats and the city behind",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
},
{
"id": 11,
"type": "article",
"language": "en",
"title": "Central bank holds rates steady for a third month",
"subtitle": "Policymakers said inflation was falling, but not fast enough to cut.",
"excerpt": "Borrowing costs stay at 4.25 per cent. Most economists now expect the first cut in the spring.",
"url": "https://news.example.com/markets/central-bank-holds-rates-steady-for-a-third-month",
"published_at": "2026-10-19T04:13:14+00:00",
"updated_at": "2026-10-19T04:13:14+00:00",
"reading_time": 1,
"is_featured": false,
"is_breaking": false,
"is_premium": true,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 5,
"name": "Markets",
"slug": "markets",
"color": "#0f766e",
"url": "https://news.example.com/markets"
},
"author": {
"id": 3,
"name": "Daniel Reyes",
"slug": "daniel-reyes",
"job_title": "Business reporter",
"avatar_url": null
},
"image": {
"id": 5,
"url": "https://news.example.com/uploads/5/conversions/barjoisevbaoirwy-large.webp",
"original_url": "https://news.example.com/uploads/5/barjoisevbaoirwy.jpg",
"thumb_url": "https://news.example.com/uploads/5/conversions/barjoisevbaoirwy-thumb.webp",
"medium_url": "https://news.example.com/uploads/5/conversions/barjoisevbaoirwy-medium.webp",
"large_url": "https://news.example.com/uploads/5/conversions/barjoisevbaoirwy-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a rising bar chart",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
}
]
}
POST /posts/{post}/like ​
Like an article.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Article ID. |
Answers:
- 200: The new count. The
datais an object. - 401: Not signed in, or the token no longer works.
- 404: No published article has this ID.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/posts/1/like
Answer (200):
{
"data": {
"count": 1,
"liked": true
}
}
DELETE /posts/{post}/like ​
Take back a like.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Article ID. |
Answers:
- 200: The new count. The
datais an object. - 401: Not signed in, or the token no longer works.
- 404: No published article has this ID.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
DELETE /api/v1/posts/1/like
Answer (200):
{
"data": {
"count": 0,
"liked": false
}
}
GET /posts/{post}/live-updates ​
Entries of a live blog. Entries come newest first. Pinned entries have is_pinned: true: show them at the top. Open to everyone, no token needed.
Keeping a live blog up to date (polling):
- When the reader opens the live blog, load the first page without
since, and keepmeta.server_timefrom the answer. - While the live blog is on screen, ask again every 20 to 30 seconds with
sinceset to the lastmeta.server_time. The answer then holds only entries added or edited since, often none, and is small. The NewsLoop app asks every 30 seconds, and the website every 20 seconds. - Stop asking when the screen is closed or the app goes to the background, and ask once straight away when it comes back.
- Never ask more often than every 10 seconds: each reader counts towards the API's limit of 60 requests a minute without an account. Answers without
sinceare cached for 60 seconds, so asking for the first page more often gives the same answer. - To catch entries the newsroom deleted, reload the first page without
sincewhen the reader pulls to refresh.
Use cursor (from meta.next_cursor) to load older entries as the reader scrolls down.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Live blog ID. |
since (optional) |
query | string | Only entries added or changed after this time: meta.server_time of the last answer. |
limit (optional) |
query | integer | Default 30. |
cursor (optional) |
query | string | From meta.next_cursor of the previous page. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Newest first. The
datais list of LiveUpdate. - 304: Not modified since the ETag sent.
- 403: A subscribers-only live blog (
is_premium: true), and the reader can't read it: not a member, and noX-NF-Metertoken that already counts this article. Open the article withGET /posts/{post}first; once it isn't locked, send its meter token here. - 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/posts/34/live-updates?limit=2
Example answer (200)
{
"data": [
{
"id": 5,
"title": null,
"content_html": "<p>Candidates are arriving at the hall. The mood among the volunteers is tense but cheerful.</p>",
"is_pinned": false,
"is_key_event": false,
"author": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"avatar_url": null
},
"published_at": "2026-10-20T19:43:24+00:00",
"updated_at": "2026-10-20T20:13:24+00:00"
},
{
"id": 4,
"title": "Turnout at a record high",
"content_html": "<p>The returning officer confirms a turnout of 71 per cent, the highest since records began.</p>",
"is_pinned": true,
"is_key_event": false,
"author": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"avatar_url": null
},
"published_at": "2026-10-20T19:08:24+00:00",
"updated_at": "2026-10-20T20:13:24+00:00"
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": "https://news.example.com/api/v1/posts/34/live-updates?limit=2&cursor=eyJwdWJsaXNoZWRfYXQiOiIyMDI2LTEwLTIwIDE5OjA4OjI0IiwiaWQiOjQsIl9wb2ludHNUb05leHRJdGVtcyI6d…"
},
"meta": {
"path": "https://news.example.com/api/v1/posts/34/live-updates",
"per_page": 2,
"next_cursor": "eyJwdWJsaXNoZWRfYXQiOiIyMDI2LTEwLTIwIDE5OjA4OjI0IiwiaWQiOjQsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0",
"prev_cursor": null,
"server_time": "2026-10-21T07:40:54+00:00",
"post_updated_at": "2026-10-20T17:13:24+00:00"
}
}
POST /posts/{post}/views ​
Count a read.
Open to everyone; a token is optional. Without Authorization you get the public answer. With a valid Authorization: Bearer <token>, the answer is for that reader. An invalid or expired token is treated like no token here: it never causes a 401.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Article ID. |
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
source (optional) |
app, push, newsletter |
Answers:
- 202: Accepted. Repeated reads by the same reader within a while count once. The
datais an object. - 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/posts/1/views
Content-Type: application/json
{
"source": "app"
}
Answer (202):
{
"data": {
"counted": false
}
}
GET /trending ​
Most read articles.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
days (optional) |
query | 1, 7, 30 |
Default 7. |
limit (optional) |
query | integer | Default 10. |
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Most read first. The
datais list of PostCard. - 304: Not modified since the ETag sent.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/trending?limit=2
Example answer (200)
{
"data": [
{
"id": 3,
"type": "article",
"language": "en",
"title": "Mayor unveils plan for free buses on weekends",
"subtitle": "The six-month trial would cost £1.1m and start in the new year.",
"excerpt": "All council-run buses would be free on Saturdays and Sundays, to bring shoppers back to the city centre.",
"url": "https://news.example.com/politics/mayor-unveils-plan-for-free-buses-on-weekends",
"published_at": "2026-10-14T14:13:10+00:00",
"updated_at": "2026-10-14T14:13:10+00:00",
"reading_time": 1,
"is_featured": false,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 1,
"name": "Politics",
"slug": "politics",
"color": "#c8102e",
"url": "https://news.example.com/politics"
},
"author": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"avatar_url": null
},
"image": {
"id": 3,
"url": "https://news.example.com/uploads/3/conversions/3non05c9ieb3pbbd-large.webp",
"original_url": "https://news.example.com/uploads/3/3non05c9ieb3pbbd.jpg",
"thumb_url": "https://news.example.com/uploads/3/conversions/3non05c9ieb3pbbd-thumb.webp",
"medium_url": "https://news.example.com/uploads/3/conversions/3non05c9ieb3pbbd-medium.webp",
"large_url": "https://news.example.com/uploads/3/conversions/3non05c9ieb3pbbd-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of an electric bus passing the city",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
},
{
"id": 22,
"type": "article",
"language": "en",
"title": "Cricket side names new captain ahead of tour",
"subtitle": "All-rounder Sofia Mendes takes over from the long-serving Kenji Arai.",
"excerpt": "Mendes, 27, has been vice-captain for two seasons.",
"url": "https://news.example.com/cricket/cricket-side-names-new-captain-ahead-of-tour",
"published_at": "2026-10-18T23:13:21+00:00",
"updated_at": "2026-10-18T23:13:21+00:00",
"reading_time": 1,
"is_featured": false,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 10,
"name": "Cricket",
"slug": "cricket",
"color": "#15803d",
"url": "https://news.example.com/cricket"
},
"author": {
"id": 5,
"name": "Sam Carter",
"slug": "sam-carter",
"job_title": "Sport reporter",
"avatar_url": null
},
"image": {
"id": 9,
"url": "https://news.example.com/uploads/9/conversions/xiidfnczu9y4otok-large.webp",
"original_url": "https://news.example.com/uploads/9/xiidfnczu9y4otok.jpg",
"thumb_url": "https://news.example.com/uploads/9/conversions/xiidfnczu9y4otok-thumb.webp",
"medium_url": "https://news.example.com/uploads/9/conversions/xiidfnczu9y4otok-medium.webp",
"large_url": "https://news.example.com/uploads/9/conversions/xiidfnczu9y4otok-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a floodlit sports pitch",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
}
]
}
GET /search ​
Search articles.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
q |
query | string | |
page (optional) |
query | integer | |
limit (optional) |
query | integer | Default 20. |
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Best matches first. The
datais list of PostCard. - 304: Not modified since the ETag sent.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/search?q=harbour&limit=2
Example answer (200)
{
"data": [
{
"id": 28,
"type": "article",
"language": "en",
"title": "Choir of 300 voices to sing on the harbour wall",
"subtitle": "Singers from every school in the city will perform at dusk on Friday.",
"excerpt": "The concert marks the start of work on the new harbour.",
"url": "https://news.example.com/culture/choir-of-300-voices-to-sing-on-the-harbour-wall",
"published_at": "2026-09-29T14:13:23+00:00",
"updated_at": "2026-10-20T20:13:24+00:00",
"reading_time": 1,
"is_featured": false,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 11,
"name": "Culture",
"slug": "culture",
"color": "#a21caf",
"url": "https://news.example.com/culture"
},
"author": {
"id": 6,
"name": "Lena Ortiz",
"slug": "lena-ortiz",
"job_title": "Arts editor",
"avatar_url": null
},
"image": {
"id": 1,
"url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"original_url": "https://news.example.com/uploads/1/nkzdmalk1j5gupo1.jpg",
"thumb_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-thumb.webp",
"medium_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-medium.webp",
"large_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a harbour with cranes, boats and the city behind",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
},
{
"id": 1,
"type": "article",
"language": "en",
"title": "Council approves £48m plan to rebuild the old harbour",
"subtitle": "Work on new sea walls, a ferry pier and 600 homes will start next spring after a close vote.",
"excerpt": "Councillors voted 27 to 22 in favour after a six-hour debate, ending two years of argument over the future of the waterfront.",
"url": "https://news.example.com/politics/council-approves-ps48m-plan-to-rebuild-the-old-harbour",
"published_at": "2026-10-20T18:12:47+00:00",
"updated_at": "2026-10-20T20:13:24+00:00",
"reading_time": 1,
"is_featured": true,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 1,
"name": "Politics",
"slug": "politics",
"color": "#c8102e",
"url": "https://news.example.com/politics"
},
"author": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"avatar_url": null
},
"image": {
"id": 1,
"url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"original_url": "https://news.example.com/uploads/1/nkzdmalk1j5gupo1.jpg",
"thumb_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-thumb.webp",
"medium_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-medium.webp",
"large_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a harbour with cranes, boats and the city behind",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
}
],
"meta": {
"current_page": 1,
"last_page": 4,
"per_page": 2,
"total": 7,
"next_page": 2
}
}
Comments ​
GET /posts/{post}/comments ​
Approved comments with their replies.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Article ID. |
limit (optional) |
query | integer | Default 20. |
cursor (optional) |
query | string | From meta.next_cursor of the previous page. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Newest first. The
datais list of Comment. - 304: Not modified since the ETag sent.
- 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/posts/1/comments?limit=2
Answer (200):
{
"data": [
{
"id": 1,
"parent_id": null,
"author_name": "Priya S.",
"is_staff_reply": false,
"body": "Good to see this covered properly. The last plan fell apart because nobody explained the costs.",
"status": "approved",
"created_at": "2026-10-20T20:13:24+00:00",
"replies": [
{
"id": 2,
"parent_id": 1,
"author_name": "Omar H.",
"is_staff_reply": false,
"body": "Agreed. The six-monthly figures will be the real test.",
"status": "approved",
"created_at": "2026-10-20T20:13:24+00:00",
"replies": []
}
]
}
],
"links": {
"first": null,
"last": null,
"prev": null,
"next": null
},
"meta": {
"path": "https://news.example.com/api/v1/posts/1/comments",
"per_page": 2,
"next_cursor": null,
"prev_cursor": null
}
}
POST /posts/{post}/comments ​
Write a comment.
Open to everyone; a token is optional. Without Authorization you get the public answer. With a valid Authorization: Bearer <token>, the answer is for that reader. An invalid or expired token is treated like no token here: it never causes a 401.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Article ID. |
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
body |
string | |
name (optional) |
string | Required without an account. |
email (optional) |
string | |
parent_id (optional) |
integer | Reply to this comment. |
Answers:
- 201: Published. The
datais Comment. - 202: Waiting for a moderator. The
datais Comment. - 404: Not found.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/posts/1/comments
Content-Type: application/json
{
"body": "Great news for the harbour. When does the work start?"
}
Answer (202):
{
"data": {
"id": 20,
"parent_id": null,
"author_name": "Sam R.",
"is_staff_reply": false,
"body": "Great news for the harbour. When does the work start?",
"status": "pending",
"created_at": "2026-10-21T07:41:04+00:00",
"replies": []
}
}
Sections ​
GET /categories ​
Sections as a tree.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
flat (optional) |
query | boolean | One list with depth, instead of a tree. |
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Sections in their order. The
datais list of Category. - 304: Not modified since the ETag sent.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/categories
Example answer (200)
{
"data": [
{
"id": 1,
"parent_id": null,
"name": "Politics",
"slug": "politics",
"color": "#c8102e",
"depth": 0,
"url": "https://news.example.com/politics",
"children": [
{
"id": 2,
"parent_id": 1,
"name": "Elections",
"slug": "elections",
"color": "#c8102e",
"depth": 1,
"url": "https://news.example.com/elections",
"children": []
},
{
"id": 3,
"parent_id": 1,
"name": "Policy",
"slug": "policy",
"color": "#c8102e",
"depth": 1,
"url": "https://news.example.com/policy",
"children": []
}
]
},
{
"id": 4,
"parent_id": null,
"name": "Business",
"slug": "business",
"color": "#0f766e",
"depth": 0,
"url": "https://news.example.com/business",
"children": [
{
"id": 5,
"parent_id": 4,
"name": "Markets",
"slug": "markets",
"color": "#0f766e",
"depth": 1,
"url": "https://news.example.com/markets",
"children": []
},
{
"id": 6,
"parent_id": 4,
"name": "Startups",
"slug": "startups",
"color": "#0f766e",
"depth": 1,
"url": "https://news.example.com/startups",
"children": []
}
]
}
]
}
GET /categories/{category} ​
A section.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
category |
path | integer | Section ID. |
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: The section with its subsections. The
datais Category. - 304: Not modified since the ETag sent.
- 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/categories/1
Answer (200):
{
"data": {
"id": 1,
"parent_id": null,
"name": "Politics",
"slug": "politics",
"color": "#c8102e",
"depth": 0,
"url": "https://news.example.com/politics",
"children": [
{
"id": 2,
"parent_id": 1,
"name": "Elections",
"slug": "elections",
"color": "#c8102e",
"depth": 1,
"url": "https://news.example.com/elections",
"children": []
},
{
"id": 3,
"parent_id": 1,
"name": "Policy",
"slug": "policy",
"color": "#c8102e",
"depth": 1,
"url": "https://news.example.com/policy",
"children": []
}
]
}
}
GET /tags ​
Tags, most used first.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
q (optional) |
query | string | Part of the name. |
limit (optional) |
query | integer | Default 30. |
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Tags in the language. The
datais list of Tag. - 304: Not modified since the ETag sent.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/tags?limit=2
Answer (200):
{
"data": [
{
"id": 3,
"name": "Economy",
"slug": "economy",
"language": "en",
"post_count": 10,
"url": "https://news.example.com/tag/economy"
},
{
"id": 2,
"name": "Transport",
"slug": "transport",
"language": "en",
"post_count": 7,
"url": "https://news.example.com/tag/transport"
}
]
}
GET /tags/{tag} ​
A tag.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
tag |
path | integer | Tag ID. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: The tag. The
datais Tag. - 304: Not modified since the ETag sent.
- 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/tags/3
Answer (200):
{
"data": {
"id": 3,
"name": "Economy",
"slug": "economy",
"language": "en",
"post_count": 10,
"url": "https://news.example.com/tag/economy"
}
}
GET /authors/{author} ​
A writer's profile.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
author |
path | integer | User ID of the writer. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: The writer. Their articles come from GET /posts?source=author. The
datais Author. - 304: Not modified since the ETag sent.
- 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/authors/2
Answer (200):
{
"data": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"bio": "Amara has covered city hall and national politics for twelve years.",
"avatar": null,
"social_links": {},
"url": "https://news.example.com/author/amara-okafor"
}
}
GET /pages/{page} ​
A page such as About or Privacy.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
page |
path | string | Page ID, or its address in the language, such as "privacy". |
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: The page. The
datais Page. - 304: Not modified since the ETag sent.
- 404: Not found.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/pages/about
Answer (200):
{
"data": {
"id": 1,
"title": "About us",
"slug": "about",
"language": "en",
"content_html": "<p>The Harbour Herald is an independent newsroom covering Port Aurel and the valley around it. Our reporters live here, and our job is to explain what is hap…",
"url": "https://news.example.com/about",
"updated_at": "2026-10-20T20:13:24+00:00"
}
}
Memberships ​
GET /plans ​
Membership plans.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Active plans. Readers join on the website at meta.join_url. The
datais list of Plan. - 304: Not modified since the ETag sent.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/plans
Answer (200):
{
"data": [],
"meta": {
"memberships_enabled": false,
"join_url": "https://news.example.com/membership"
}
}
Notifications ​
GET /push/topics ​
Notification topics.
Open to everyone. No token needed.
| Parameter | In | Type | Meaning |
|---|---|---|---|
lang (optional) |
query | string | Language code, such as "ar". Otherwise Accept-Language, then the site default. |
If-None-Match (optional) |
header | string | The ETag of the copy the app has. Unchanged answers are 304 without a body. |
Answers:
- 200: Topics to subscribe to with Firebase. The
datais list of PushTopic. - 304: Not modified since the ETag sent.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/push/topics
Answer (200):
{
"data": [
{
"key": "all",
"name": "Everything",
"fcm_topic": "nf-all",
"fcm_language_topic": "nf-all-en"
},
{
"key": "breaking",
"name": "Breaking news",
"fcm_topic": "nf-breaking",
"fcm_language_topic": "nf-breaking-en"
}
],
"meta": {
"enabled": false
}
}
POST /devices ​
Register a phone for notifications.
Open to everyone; a token is optional. Without Authorization you get the public answer. With a valid Authorization: Bearer <token>, the answer is for that reader. An invalid or expired token is treated like no token here: it never causes a 401.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
token |
string | The Firebase registration token. |
platform |
android, ios |
|
topics (optional) |
list of string | |
language (optional) |
string |
Answers:
- 200: Updated. The
datais an object. - 201: Registered. The
datais an object. - 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/devices
Content-Type: application/json
{
"token": "fcm-device-token-from-firebase",
"platform": "android",
"topics": [
"breaking"
],
"language": "en"
}
Answer (201):
{
"data": {
"platform": "android",
"topics": [
"breaking"
],
"language": "en"
}
}
DELETE /devices ​
Stop notifications to a phone.
Open to everyone; a token is optional. Without Authorization you get the public answer. With a valid Authorization: Bearer <token>, the answer is for that reader. An invalid or expired token is treated like no token here: it never causes a 401.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
token |
string |
Answers:
- 204: Removed.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
DELETE /api/v1/devices
Content-Type: application/json
{
"token": "fcm-device-token-from-firebase"
}
Answer: 204, with no body.
Accounts ​
POST /auth/register ​
Create an account.
Open to everyone. No token needed.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
name |
string | |
email |
string | |
password |
string | |
password_confirmation |
string | |
device_name |
string |
Answers:
- 201: Signed in. The reader gets an email to confirm the address.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/auth/register
Content-Type: application/json
{
"name": "Sam Reader",
"email": "sam.reader@example.com",
"password": "Correct-Horse-42!",
"device_name": "Pixel 8",
"password_confirmation": "Correct-Horse-42!"
}
Answer (201):
{
"data": {
"token": "11|nf_CH94x1193eb5F42S6xIC72dOM4z8GFIv9nW0lYDV231c3407",
"token_type": "Bearer",
"user": {
"id": 12,
"name": "Sam Reader",
"email": "sam.reader@example.com",
"email_verified": false,
"has_password": true,
"is_staff": false,
"sign_in_providers": [],
"created_at": "2026-10-21T07:40:58+00:00",
"can_read_premium": true,
"ad_free": false,
"membership": null,
"newsletter": "pending"
}
}
}
POST /auth/token ​
Sign in with email and password.
Open to everyone. No token needed.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
email |
string | |
password |
string | |
device_name |
string | |
code (optional) |
string | Six-digit code, for accounts with two-step sign-in. |
recovery_code (optional) |
string |
Answers:
- 200: Signed in.
- 422: Wrong details, or
two_factor: truewhen the account needs a code from an authenticator app. - 429: Too many requests. Wait for the time in the Retry-After header.
Example: wrong password. A validation error. Every 422 answer has this shape.
POST /api/v1/auth/token
Content-Type: application/json
{
"email": "sam.reader@example.com",
"password": "not-the-password",
"device_name": "Pixel 8"
}
Answer (422):
{
"message": "These credentials do not match our records.",
"errors": {
"email": [
"These credentials do not match our records."
]
}
}
Example.
POST /api/v1/auth/token
Content-Type: application/json
{
"email": "sam.reader@example.com",
"password": "Correct-Horse-42!",
"device_name": "Pixel 8"
}
Answer (200):
{
"data": {
"token": "12|7xF3k9QmL2pRsT8vW1yZ4aB6cD0eG5hJ",
"token_type": "Bearer",
"user": {
"id": 12,
"name": "Sam Reader",
"email": "sam.reader@example.com",
"email_verified": false,
"has_password": true,
"is_staff": false,
"sign_in_providers": [],
"created_at": "2026-10-21T07:40:58+00:00",
"can_read_premium": true,
"ad_free": false,
"membership": null,
"newsletter": "pending"
}
}
}
DELETE /auth/token ​
Sign this device out.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
Answers:
- 204: Signed out.
- 401: Not signed in, or the token no longer works.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
DELETE /api/v1/auth/token
Answer: 204, with no body.
POST /auth/social ​
Sign in with Google or Apple.
Open to everyone. No token needed.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
provider |
google, apple |
|
id_token |
string | |
nonce (optional) |
string | The raw nonce the app used, if any. |
name (optional) |
string | Apple gives the name only on the first sign-in; pass it along. |
device_name |
string |
Answers:
- 200: Signed in. New readers get an account.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example. With a valid Google or Apple ID token, the answer is the same as POST /auth/token. An invalid one answers 422:
POST /api/v1/auth/social
Content-Type: application/json
{
"provider": "google",
"id_token": "eyJhbGciOiJSUzI1NiJ9.not-a-real-token",
"device_name": "Pixel 8"
}
Answer (422):
{
"message": "Sign-in with Google is not set up on this site.",
"errors": {
"provider": [
"Sign-in with Google is not set up on this site."
]
}
}
POST /auth/forgot-password ​
Email a link to set a new password.
Open to everyone. No token needed.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
email |
string |
Answers:
- 200: The same answer whether or not the address has an account.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/auth/forgot-password
Content-Type: application/json
{
"email": "sam.reader@example.com"
}
Answer (200):
{
"message": "If an account exists for this email, we sent a link to set a new password."
}
POST /auth/email/verification-notification ​
Send the confirmation email again.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
Answers:
- 200: Already confirmed.
- 202: Sent.
- 401: Not signed in, or the token no longer works.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/auth/email/verification-notification
Answer (202):
{
"message": "We sent you a new link to confirm your email address."
}
GET /me ​
The signed-in reader.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
Answers:
- 200: The account. The
datais Me. - 401: Not signed in, or the token no longer works.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/me
Answer (200):
{
"data": {
"id": 12,
"name": "Sam Reader",
"email": "sam.reader@example.com",
"email_verified": false,
"has_password": true,
"is_staff": false,
"sign_in_providers": [],
"created_at": "2026-10-21T07:40:58+00:00",
"can_read_premium": true,
"ad_free": false,
"membership": null,
"newsletter": "pending"
}
}
Example: no token. Signed-in endpoints answer 401 without a valid token.
GET /api/v1/me
Answer (401):
{
"message": "Unauthenticated."
}
PATCH /me ​
Change the name or newsletter.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
name (optional) |
string | |
newsletter (optional) |
boolean |
Answers:
- 200: The account. The
datais Me. - 401: Not signed in, or the token no longer works.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
PATCH /api/v1/me
Content-Type: application/json
{
"name": "Sam R.",
"newsletter": true
}
Answer (200):
{
"data": {
"id": 12,
"name": "Sam R.",
"email": "sam.reader@example.com",
"email_verified": false,
"has_password": true,
"is_staff": false,
"sign_in_providers": [],
"created_at": "2026-10-21T07:40:58+00:00",
"can_read_premium": true,
"ad_free": false,
"membership": null,
"newsletter": "pending"
}
}
DELETE /me ​
Delete the account. Staff accounts are removed by an administrator instead.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
password (optional) |
string | Required when the account has a password. |
confirm (optional) |
boolean | For accounts without a password: must be true. |
Answers:
- 204: Deleted. Memberships were stopped first.
- 401: Not signed in, or the token no longer works.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
DELETE /api/v1/me
Content-Type: application/json
{
"password": "Correct-Horse-42!"
}
Answer: 204, with no body.
Bookmarks ​
GET /me/bookmarks ​
Saved articles.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
| Parameter | In | Type | Meaning |
|---|---|---|---|
limit (optional) |
query | integer | Default 30. |
cursor (optional) |
query | string | From meta.next_cursor of the previous page. |
Answers:
- 200: Most recently saved first. The
datais list of object. - 401: Not signed in, or the token no longer works.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
GET /api/v1/me/bookmarks
Example answer (200)
{
"data": [
{
"post_id": 1,
"saved_at": "2026-10-21T07:41:02+00:00",
"post": {
"id": 1,
"type": "article",
"language": "en",
"title": "Council approves £48m plan to rebuild the old harbour",
"subtitle": "Work on new sea walls, a ferry pier and 600 homes will start next spring after a close vote.",
"excerpt": "Councillors voted 27 to 22 in favour after a six-hour debate, ending two years of argument over the future of the waterfront.",
"url": "https://news.example.com/politics/council-approves-ps48m-plan-to-rebuild-the-old-harbour",
"published_at": "2026-10-20T18:12:47+00:00",
"updated_at": "2026-10-20T20:13:24+00:00",
"reading_time": 1,
"is_featured": true,
"is_breaking": false,
"is_premium": false,
"sponsor_name": null,
"video_url": null,
"category": {
"id": 1,
"name": "Politics",
"slug": "politics",
"color": "#c8102e",
"url": "https://news.example.com/politics"
},
"author": {
"id": 2,
"name": "Amara Okafor",
"slug": "amara-okafor",
"job_title": "Political editor",
"avatar_url": null
},
"image": {
"id": 1,
"url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"original_url": "https://news.example.com/uploads/1/nkzdmalk1j5gupo1.jpg",
"thumb_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-thumb.webp",
"medium_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-medium.webp",
"large_url": "https://news.example.com/uploads/1/conversions/nkzdmalk1j5gupo1-large.webp",
"width": 1600,
"height": 1000,
"alt": "Illustration of a harbour with cranes, boats and the city behind",
"caption": null,
"credit": "NewsLoop demo illustration",
"focal_x": 0.5,
"focal_y": 0.5
}
}
}
],
"meta": {
"per_page": 30,
"next_cursor": null,
"prev_cursor": null
}
}
POST /me/bookmarks ​
Save an article.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
post_id |
integer |
Answers:
- 201: Saved. The
datais an object. - 401: Not signed in, or the token no longer works.
- 404: Not found.
- 422: The request is not valid.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/me/bookmarks
Content-Type: application/json
{
"post_id": 1
}
Answer (201):
{
"data": {
"post_id": 1,
"saved": true
}
}
DELETE /me/bookmarks/{post} ​
Remove a saved article.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
| Parameter | In | Type | Meaning |
|---|---|---|---|
post |
path | integer | Article ID. |
Answers:
- 204: Removed, or was not saved.
- 401: Not signed in, or the token no longer works.
- 429: Too many requests. Wait for the time in the Retry-After header.
Example.
DELETE /api/v1/me/bookmarks/1
Answer: 204, with no body.
POST /me/bookmarks/sync ​
Send changes made offline. Removals run first, then additions, in one transaction. Both lists are optional; an empty request just returns the saved list. A reader can save up to 1,000 articles: additions that would go over the limit are refused with 422, and nothing is changed.
Needs a signed-in reader (Authorization: Bearer <token>). Without a valid token it answers 401.
Request body (JSON):
| Field | Type | Meaning |
|---|---|---|
add (optional) |
list of object | Articles saved on the device since the last sync, up to 500 per request. One object per article. |
add[].post_id |
integer | The article's id, as in GET /posts. Articles that are not published (or no longer exist) are skipped without an error, and articles already saved are left as they are. |
add[].saved_at (optional) |
string | When the reader saved it on the device, in ISO 8601 with a time zone, such as 2026-10-21T08:30:00Z. It sets the article's place in the list, which is most recent first. Leave it out to use the time of the sync; a time in the future is replaced by the time of the sync. |
remove (optional) |
list of integer | IDs of articles removed from the saved list on the device, up to 500 per request. IDs that are not saved are ignored. |
Answers:
- 200: Every saved article ID, most recent first. The
datais an object. - 401: Not signed in, or the token no longer works.
- 422: The request is not valid: more than 500 items in
addorremove(errors.add,errors.remove; send the changes in batches, see "Saved articles" in the REST API guide), or the reader would go over 1,000 saved articles (errors.post_id). Nothing is changed. - 429: Too many requests. Wait for the time in the Retry-After header.
Example.
POST /api/v1/me/bookmarks/sync
Content-Type: application/json
{
"add": [
{
"post_id": 1,
"saved_at": "2026-10-20T08:30:00+00:00"
}
],
"remove": []
}
Answer (200):
{
"data": {
"post_ids": [
1
]
}
}
Example: limit reached. A reader who already has 1,000 saved articles. Nothing is added or removed.
POST /api/v1/me/bookmarks/sync
Content-Type: application/json
{
"add": [
{
"post_id": 1001,
"saved_at": "2026-10-20T08:30:00+00:00"
}
],
"remove": []
}
Answer (422):
{
"message": "You can save up to 1000 articles. Remove some to save more.",
"errors": {
"post_id": [
"You can save up to 1000 articles. Remove some to save more."
]
}
}
Example: more than 500 changes. The request had 501 objects in add. Nothing is added or removed, not even the removals: send the changes in batches of up to 500.
POST /api/v1/me/bookmarks/sync
Answer (422):
{
"message": "The add field must not have more than 500 items.",
"errors": {
"add": [
"The add field must not have more than 500 items."
]
}
}
Objects ​
The objects the answers are made of.
Error object ​
| Field | Type | Meaning |
|---|---|---|
message |
string | |
errors (optional) |
object | Field name to messages, for validation errors. |
Image object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
url |
string | The largest generated size, or the original. |
original_url |
string | |
thumb_url |
string or null | 480×360 crop around the focal point. |
medium_url |
string or null | Up to 960 px. |
large_url |
string or null | Up to 1920 px. |
width |
integer or null | |
height |
integer or null | |
alt |
string | |
caption |
string or null | |
credit |
string or null | |
focal_x |
number | |
focal_y |
number |
SectionRef object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
name |
string | |
slug |
string | |
color |
string or null | |
url |
string or null |
Person object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
name |
string | |
slug |
string or null | |
job_title |
string or null | |
avatar_url |
string or null |
PostCard object ​
An article in a list.
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
type |
article, video, audio, gallery, live |
|
language |
string | |
title |
string | |
subtitle |
string or null | |
excerpt |
string or null | |
url |
string | The article on the website, for sharing. |
published_at |
string or null | |
updated_at |
string or null | |
reading_time |
integer | Minutes. |
is_featured |
boolean | |
is_breaking |
boolean | |
is_premium |
boolean | Subscribers only. |
sponsor_name |
string or null | Show "Sponsored by …" when set. |
video_url |
string or null | |
category |
SectionRef or null | |
author |
Person or null | |
image |
Image or null |
Post object ​
A whole article.
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
type |
article, video, audio, gallery, live |
|
language |
string | |
title |
string | |
subtitle |
string or null | |
excerpt |
string or null | |
url |
string | The article on the website, for sharing. |
published_at |
string or null | |
updated_at |
string or null | |
reading_time |
integer | Minutes. |
is_featured |
boolean | |
is_breaking |
boolean | |
is_premium |
boolean | Subscribers only. |
sponsor_name |
string or null | Show "Sponsored by …" when set. |
video_url |
string or null | |
category |
SectionRef or null | |
author |
Person or null | |
image |
Image or null | |
coauthors |
list of Person | |
content_html |
string | Sanitized HTML, ready to show. Only the opening when locked is true. Ad blocks are a website feature and are left out; <aside class="nf-related" data-post-id="…"> holds a link to a related article, best replaced with a native card. Every element and what to do with it: "Showing an article's text" in the REST API guide. |
locked |
boolean | The reader needs a membership, or has used their free articles this month. |
word_count |
integer | |
tags |
list of object | |
tags[].id |
integer | |
tags[].name |
string | |
tags[].slug |
string | |
sections |
list of SectionRef | |
series |
object or null | |
source |
object or null | |
audio_url |
string or null | "Listen to this article", when there is audio. |
ai_assisted |
boolean | |
ai_disclosure |
string or null | Text to show when AI helped write the article and the site discloses it. |
comments |
object | |
likes |
object | Readers' likes. "liked" is true when the signed-in reader liked it. |
translations |
list of object | |
translations[].id |
integer | |
translations[].language |
string | |
translations[].title |
string |
Meter object ​
The metered paywall: free subscribers-only articles left this month.
| Field | Type | Meaning |
|---|---|---|
limit |
integer | |
remaining |
integer | |
token |
string | Send back in the X-NF-Meter header with the next article. |
CursorLinks object ​
| Field | Type | Meaning |
|---|---|---|
first |
string or null | |
last |
string or null | |
prev |
string or null | |
next |
string or null |
CursorMeta object ​
| Field | Type | Meaning |
|---|---|---|
path (optional) |
string | |
per_page |
integer | |
next_cursor |
string or null | |
prev_cursor |
string or null |
Category object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
parent_id |
integer or null | |
name |
string | |
slug |
string | |
color |
string or null | |
depth |
integer | |
url |
string or null | |
children |
list of Category |
Tag object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
name |
string | |
slug |
string | |
language |
string | |
post_count |
integer or null | |
url |
string |
Author object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
name |
string | |
slug |
string or null | |
job_title |
string or null | |
bio |
string or null | |
avatar |
Image or null | |
social_links |
object | website, x, facebook, instagram, linkedin |
url |
string or null |
Page object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
title |
string | |
slug |
string | |
language |
string | |
content_html |
string | |
url |
string | |
updated_at |
string or null |
Comment object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
parent_id |
integer or null | |
author_name |
string | |
is_staff_reply |
boolean | |
body |
string | Plain text. Escape it when showing it. |
status |
approved, pending |
"pending" waits for a moderator. |
created_at |
string or null | |
replies |
list of Comment |
LiveUpdate object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
title |
string or null | |
content_html |
string | |
is_pinned |
boolean | |
is_key_event |
boolean | |
author |
Person or null | |
published_at |
string or null | |
updated_at |
string or null |
Me object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
name |
string | |
email |
string | |
email_verified |
boolean | |
has_password |
boolean | False for accounts made with Google or Apple. |
is_staff |
boolean | |
sign_in_providers |
list of google, apple |
|
created_at |
string or null | |
can_read_premium |
boolean | |
ad_free |
boolean | |
membership |
object or null | |
newsletter |
subscribed, pending, none, null |
null when the site has no newsletter. |
Plan object ​
| Field | Type | Meaning |
|---|---|---|
id |
integer | |
name |
string | |
slug |
string | |
description |
string or null | |
features |
list of string | |
currency |
string | |
price_monthly |
integer or null | In the currency's smallest unit, such as cents. |
price_yearly |
integer or null | |
price_monthly_formatted |
string or null | |
price_yearly_formatted |
string or null | |
trial_days |
integer | |
removes_ads |
boolean |
PushTopic object ​
| Field | Type | Meaning |
|---|---|---|
key |
string | |
name |
string | |
fcm_topic |
string | |
fcm_language_topic |
string |
Language object ​
| Field | Type | Meaning |
|---|---|---|
code |
string | |
name |
string | |
native_name |
string | |
direction |
ltr, rtl |
|
is_default |
boolean |
Site object ​
| Field | Type | Meaning |
|---|---|---|
name |
string | |
tagline |
string | |
url |
string | |
logo |
Image or null | |
logo_dark |
Image or null | |
icon |
Image or null | |
contact_email |
string or null | |
timezone |
string | |
language |
string | |
default_language |
string | |
languages |
list of Language | |
features |
object | |
ads |
object | |
links |
object | |
social |
object | |
app |
object | Pictures for building the app (icon and splash), from Mobile app settings. |
api_version |
object |
TokenResponse object ​
| Field | Type | Meaning |
|---|---|---|
data |
object |
Message object ​
| Field | Type | Meaning |
|---|---|---|
message |
string |