NewsLoopVersion 1.0.0 · offline copyGuides

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.

bash
curl https://news.example.com/api/v1/site

In Windows PowerShell:

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

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

bash
curl "https://news.example.com/api/v1/posts?limit=2"

In Windows PowerShell:

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

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

  1. Sign in to your admin panel and open App → Mobile app.
  2. The API address at the top is your base URL, ready to copy. The NewsLoop app needs it too, as api_url in whitelabel.yaml.
  3. To check it, open the base URL followed by /site in 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:

Architecture diagram: website readers, your team and app readers reach the web server on your hosting, which shares the database and files with the background work and talks to outside services with your own accounts

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.

Sequence diagram of the token lifecycle: the app gets a token from POST /auth/register, POST /auth/token or POST /auth/social, keeps it in secure storage, sends it as "Authorization: Bearer", signs in again after a 401, and signs out with DELETE /auth/token

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.

Sequence diagram of the meter handshake: the first subscribers-only article answers with meta.meter and a token; the app sends it back in X-NF-Meter with the next article; when the free articles are used up the answer is locked; members skip the meter

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.

  1. Open Accounts → Sign in with email and password.
  2. In the Body tab, put a reader's email and password (any device_name, such as Postman).
  3. Click Send. The answer is 200, and the collection saves its data.token in the token variable.

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:

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

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

ini
NEWSLOOP_API_GUEST_LIMIT=180

What changes when you set it:

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:

json
"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:

304 Not Modified and ETag ​

Every 200 answer to a GET has an ETag, such as W/"393f03e95386126b0f0ba69fa138a811". To check for changes cheaply:

  1. Keep the answer and its ETag together, per address. The address includes the query and the language: /posts?category=4 and /posts?category=4&lang=ar have different ETags.
  2. Next time, send the ETag back exactly as you got it, in If-None-Match.
  3. 304 Not Modified has no body. Nothing changed: show your saved copy and keep its ETag. Don't parse the empty body as JSON.
  4. 200 means something changed: replace your copy and its ETag.

Things to know:

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

How to be ready:

Breaking changes need a new version. If a change can't be made without breaking v1, it comes as /api/v2. Then:

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:

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

json
"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:

dart
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.

http
POST /api/v1/auth/token
Content-Type: application/json

{
  "email": "sam.reader@example.com",
  "password": "not-the-password",
  "device_name": "Pixel 8"
}

Answer (422):

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

http
GET /api/v1/me

Answer (401):

json
{
  "message": "Unauthenticated."
}

Example: not found. Missing articles, sections and pages answer 404.

http
GET /api/v1/posts/999999

Answer (404):

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

http
POST /api/v1/auth/social
Content-Type: application/json

{
  "provider": "google",
  "id_token": "eyJhbGciOiJSUzI1NiJ9.not-a-real-token",
  "device_name": "Pixel 8"
}

Answer (422):

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

http
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):

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

http
POST /api/v1/me/bookmarks/sync

Answer (422):

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

Example.

http
GET /api/v1/site
Example answer (200)
json
{
  "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:

Example.

http
GET /api/v1/app/config
Example answer (200)
json
{
  "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:

Example.

http
GET /api/v1/resolve?url=http%3A%2F%2Fnews.example.com%2Fpolitics%2Fcouncil-approves-ps48m-plan-to-rebuild-the-old-harbour

Answer (200):

json
{
  "data": {
    "type": "post",
    "id": 1,
    "language": "en"
  }
}

GET /openapi.json ​

This description.

Open to everyone. No token needed.

Answers:

Example. The answer is the whole OpenAPI 3.1 description of the API; only its first fields are shown here.

http
GET /api/v1/openapi.json

Answer (200):

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

Example.

http
GET /api/v1/posts?limit=2
Example answer (200)
json
{
  "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:

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:

Example.

http
GET /api/v1/posts/1
Example answer (200)
json
{
  "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.

http
GET /api/v1/posts/999999

Answer (404):

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

Example.

http
GET /api/v1/posts/1/related?limit=2
Example answer (200)
json
{
  "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:

Example.

http
POST /api/v1/posts/1/like

Answer (200):

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

Example.

http
DELETE /api/v1/posts/1/like

Answer (200):

json
{
  "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):

  1. When the reader opens the live blog, load the first page without since, and keep meta.server_time from the answer.
  2. While the live blog is on screen, ask again every 20 to 30 seconds with since set to the last meta.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.
  3. Stop asking when the screen is closed or the app goes to the background, and ask once straight away when it comes back.
  4. 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 since are cached for 60 seconds, so asking for the first page more often gives the same answer.
  5. To catch entries the newsroom deleted, reload the first page without since when 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:

Example.

http
GET /api/v1/posts/34/live-updates?limit=2
Example answer (200)
json
{
  "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:

Example.

http
POST /api/v1/posts/1/views
Content-Type: application/json

{
  "source": "app"
}

Answer (202):

json
{
  "data": {
    "counted": false
  }
}

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:

Example.

http
GET /api/v1/trending?limit=2
Example answer (200)
json
{
  "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
      }
    }
  ]
}

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:

Example.

http
GET /api/v1/search?q=harbour&limit=2
Example answer (200)
json
{
  "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:

Example.

http
GET /api/v1/posts/1/comments?limit=2

Answer (200):

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

Example.

http
POST /api/v1/posts/1/comments
Content-Type: application/json

{
  "body": "Great news for the harbour. When does the work start?"
}

Answer (202):

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

Example.

http
GET /api/v1/categories
Example answer (200)
json
{
  "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:

Example.

http
GET /api/v1/categories/1

Answer (200):

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

Example.

http
GET /api/v1/tags?limit=2

Answer (200):

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

Example.

http
GET /api/v1/tags/3

Answer (200):

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

Example.

http
GET /api/v1/authors/2

Answer (200):

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

Example.

http
GET /api/v1/pages/about

Answer (200):

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

Example.

http
GET /api/v1/plans

Answer (200):

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

Example.

http
GET /api/v1/push/topics

Answer (200):

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

Example.

http
POST /api/v1/devices
Content-Type: application/json

{
  "token": "fcm-device-token-from-firebase",
  "platform": "android",
  "topics": [
    "breaking"
  ],
  "language": "en"
}

Answer (201):

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

Example.

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

Example.

http
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):

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

Example: wrong password. A validation error. Every 422 answer has this shape.

http
POST /api/v1/auth/token
Content-Type: application/json

{
  "email": "sam.reader@example.com",
  "password": "not-the-password",
  "device_name": "Pixel 8"
}

Answer (422):

json
{
  "message": "These credentials do not match our records.",
  "errors": {
    "email": [
      "These credentials do not match our records."
    ]
  }
}

Example.

http
POST /api/v1/auth/token
Content-Type: application/json

{
  "email": "sam.reader@example.com",
  "password": "Correct-Horse-42!",
  "device_name": "Pixel 8"
}

Answer (200):

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

Example.

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

Example. With a valid Google or Apple ID token, the answer is the same as POST /auth/token. An invalid one answers 422:

http
POST /api/v1/auth/social
Content-Type: application/json

{
  "provider": "google",
  "id_token": "eyJhbGciOiJSUzI1NiJ9.not-a-real-token",
  "device_name": "Pixel 8"
}

Answer (422):

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

Example.

http
POST /api/v1/auth/forgot-password
Content-Type: application/json

{
  "email": "sam.reader@example.com"
}

Answer (200):

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

Example.

http
POST /api/v1/auth/email/verification-notification

Answer (202):

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

Example.

http
GET /api/v1/me

Answer (200):

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

http
GET /api/v1/me

Answer (401):

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

Example.

http
PATCH /api/v1/me
Content-Type: application/json

{
  "name": "Sam R.",
  "newsletter": true
}

Answer (200):

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

Example.

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

Example.

http
GET /api/v1/me/bookmarks
Example answer (200)
json
{
  "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:

Example.

http
POST /api/v1/me/bookmarks
Content-Type: application/json

{
  "post_id": 1
}

Answer (201):

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

Example.

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

Example.

http
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):

json
{
  "data": {
    "post_ids": [
      1
    ]
  }
}

Example: limit reached. A reader who already has 1,000 saved articles. Nothing is added or removed.

http
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):

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

http
POST /api/v1/me/bookmarks/sync

Answer (422):

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