NewsLoopVersion 1.0.0 · offline copyGuides

The mobile app API ​

NewsLoop has a REST API that the NewsLoop app uses. You can also use it for your own apps and integrations.

Building your own app? Start with Building an app on the API: a walkthrough in Dart: a complete, runnable client that fetches articles, shows their text, signs in, and handles a 401. How NewsLoop fits together shows where the API sits among NewsLoop's parts.

Your base URL ​

Every API address starts with your base URL: your site's address followed by /api/v1. For a site at https://news.example.com, it is https://news.example.com/api/v1, and the site's details are at https://news.example.com/api/v1/site.

To find yours, sign in to the admin and open App → Mobile app: the API address at the top is your base URL, ready to copy (see Setting up the app). Open it with /site added in your browser to check it: you should see your site's name. Use https://.

In these pages, paths such as GET /posts are added to your base URL.

Setting up the app ​

Go to App → Mobile app in the admin.

The Mobile app screen: the API address, Google and Apple sign-in, and links that open in the app

  1. API address. Copy it into api_url in the app's whitelabel.yaml (see Building the app).
  2. Sign in with Google (optional). In Google Cloud, create OAuth client IDs for your Android app, your iOS app and a web client. Paste all of them, one per line. Leave the box empty to hide the Google button.
  3. Sign in with Apple (optional, but Apple requires it on iOS if you offer Google). In your Apple developer account, turn on Sign in with Apple for your app ID. Paste the bundle ID, such as com.example.news.
  4. Open links in the app. Fill in the Android package name and the SHA-256 fingerprint from Google Play Console → Setup → App signing, and the iOS app ID (team ID, a dot, then the bundle ID). The site then publishes /.well-known/assetlinks.json and /.well-known/apple-app-site-association, which phones check before opening your links in the app.
  5. Store pages. Links to your Google Play and App Store pages, shown on the site and in the app.

The app's screens, colours and menus come from the app builder. Until you publish a layout there, the app uses a built-in one in your site's languages.

Basics ​

Language Add ?lang=ar, or send Accept-Language. Answers say which language they are in, in Content-Language.
Signing in POST /auth/token (email and password), /auth/register or /auth/social (Google or Apple) return a token. Send it as Authorization: Bearer <token>. Reading needs no account. See Sign-in tokens, from start to finish.
Pages Lists return meta.next_cursor. Send it back as cursor for the next page. Search uses page. Edge cases: Paging through lists.
Caching Every answer to a GET has an ETag. Send it back in If-None-Match, and an unchanged answer comes back as 304 with no body. See 304 Not Modified and ETag.
Limits 60 requests a minute without an account, 120 with one, 5 sign-in attempts a minute. Over the limit you get 429 with Retry-After. See Rate limits; site owners change the limits with NEWSLOOP_API_GUEST_LIMIT and NEWSLOOP_API_MEMBER_LIMIT (Changing the limits).
Errors JSON with a message. Validation errors (422) also have errors, per field.
Stability Version 1 never breaks. New fields may appear, so ignore fields you do not know. See Versioning and changes.

Endpoints ​

Area Endpoints
Site GET /site (name, logo, languages, features, links, app icon and splash), GET /app/config (the app layout), GET /resolve?url= (what a website address shows)
Articles GET /posts by source and filters, GET /posts/{id}, /related, /live-updates, POST /posts/{id}/views, POST and DELETE /posts/{id}/like, GET /trending, GET /search?q=
Comments GET and POST /posts/{id}/comments
Sections GET /categories, /categories/{id}, /tags, /tags/{id}, /authors/{id}, /pages/{id or address}
Memberships GET /plans
Notifications GET /push/topics, POST and DELETE /devices
Accounts POST /auth/register, /auth/token, /auth/social, /auth/forgot-password, /auth/email/verification-notification, DELETE /auth/token, GET, PATCH and DELETE /me
Bookmarks GET and POST /me/bookmarks, DELETE /me/bookmarks/{id}, POST /me/bookmarks/sync

Article lists ​

GET /posts?source=… takes the same data sources as the app builder: latest, featured, trending, breaking, editorsPicks, category, tag, author, series, video and live. Filters combine, for example ?source=video&category=4. sort=oldest or sort=popular changes the order.

featured, trending, breaking and editorsPicks are short ranked lists without further pages. Editor's picks are the articles in the website's Editor's picks block, so you choose them once for both.

Showing an article's text (content_html) ​

content_html in GET /posts/{post} is the article's text as safe HTML, ready to show. The site has already removed scripts, styles and anything unsafe, so you can show it with an HTML widget (such as flutter_widget_from_html) or a web view. It is the same HTML as on the website, with two differences made for apps:

Every element it can contain, and what to do with each:

Element What it is In your app
<p>, <h2> to <h4>, <ul>, <ol>, <blockquote>, <pre><code>, <hr>, <strong>, <em>, <a> Ordinary text Show as it is.
<figure class="nf-figure nf-figure--normal"> (or --wide, --full, --small), with an <img> that has srcset, and a <figcaption> with the caption and <span class="nf-credit"> A picture Show as it is. Pick a size from srcset for the screen.
<div class="nf-gallery"> with <figure class="nf-gallery__item"> items A gallery Show as it is, or as a native swipeable gallery.
<div class="nf-table"><table> A table Show as it is, scrolling sideways when wide.
<aside class="nf-callout nf-callout--info"> (or --warning, --success, --note), with an optional <p class="nf-callout__title"> A highlighted box in the text Show as it is, styled by its kind. It is not a related article.
<figure class="nf-pullquote"> with a <blockquote> and a <figcaption> A pull quote Show as it is, or styled larger.
<figure class="nf-embed nf-embed--youtube"> (or vimeo, spotify, soundcloud), with an <iframe> A video or audio player Show it in a web view, or as a button that opens it. The NewsLoop app shows a button.
<blockquote class="nf-social-embed" data-provider="x"> (or instagram, facebook, tiktok), with a link A social media post Show as it is: a link to the post.
<p class="nf-embed-link"> with a link A link to something that can't be embedded Show as it is.
<aside class="nf-related" data-post-id="12"><a href="…">Title</a></aside> A related article the editor placed in the text Replace with a native card that opens GET /posts/12 (the ID is in data-post-id). Showing it as it is also works: it is a link, which the app can open itself with GET /resolve?url=. Related articles that aren't published are already removed.

Notes:

Subscribers-only articles ​

GET /posts/{post} is open to everyone, and a token is optional. Most articles come back in full to every caller. Only articles marked subscribers-only (is_premium: true) depend on who asks:

Who asks What they get
No token, or a signed-in reader without a membership The opening only, with locked: true. With a metered paywall, the meter decides (below).
A signed-in reader with an active membership, or a staff account The whole article, with locked: false.
Any signed-in reader, when memberships are switched off on the site The whole article.

An invalid or expired token is treated like no token: this endpoint never answers 401. So send the reader's token whenever you have one, and nothing when you don't. Don't make readers sign in just to read.

The metered paywall (X-NF-Meter). If the site gives a few free subscribers-only articles a month (Free subscribers-only articles per month under Money → Memberships, see Ads and memberships), readers without a membership get meta.meter with every subscribers-only article:

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

  1. The first answer has meta.meter: { "limit": 3, "remaining": 2, "token": "…" }, and locked: false while free articles are left.
  2. Keep the token, and send it in the X-NF-Meter header with the next article. Every answer brings a new token: always keep the newest.
  3. An article already counted this month opens again for free.
  4. When none are left, the answer has locked: true and remaining: 0. Show the opening and a "Become a member" button that opens meta.join_url of GET /plans.
  5. The count starts again each month. The token is signed, so it can't be edited: a damaged or missing token starts a new count, as for a new reader. To stop endless fresh starts, the site also counts per network address, up to five times the monthly allowance.

Articles that aren't subscribers-only never have meta.meter and never count. Readers become members on the website; the app never handles card details.

The meter, request by request ​

An example with 3 free articles a month, for a reader without a membership. Our automated tests run this exact sequence, so it shows what the API really answers:

# Request X-NF-Meter sent Answer Why
1 GET /posts/101 none locked: false, remaining: 2, token T1 No token yet: a new count starts.
2 GET /posts/102 T1 locked: false, remaining: 1, token T2 The newest token: the count carries on.
3 GET /posts/101 T2 locked: false, remaining: 1, token T3 Already counted this month: free.
4 GET /posts/103 not-a-real-token locked: false, remaining: 2, a new token Malformed (or edited) tokens are ignored, as if none were sent. Still 200, never an error.
5 GET /posts/104 T3 locked: false, remaining: 0, token T5 Back to the newest good token: the last free article.
6 GET /posts/105 T5 locked: true, remaining: 0, token T6 None left: the opening only. A new token still comes.
7 GET /posts/105 last month's token locked: false, remaining: 2, a new token A token from an earlier month has run out: this month's count starts afresh.
8 GET /posts/7 (not subscribers-only) anything locked: false, no meta.meter Ordinary articles never count.

How your app should handle it:

Live blogs ​

Live blogs (type: live) get new entries while they run. Keep one up to date by polling GET /posts/{post}/live-updates:

  1. When the reader opens the live blog, load the first page and keep meta.server_time from the answer.
  2. While it is on screen, ask again every 20 to 30 seconds, with since set to the last meta.server_time. You get only the entries added or edited since, often none. The NewsLoop app asks every 30 seconds, and the website every 20.
  3. Stop while the screen is closed or the app is in the background, and ask once straight away when the reader comes back.
  4. Don't ask more often than every 10 seconds. Each reader counts towards the limit of 60 requests a minute without an account, and the first page is cached for 60 seconds anyway.
  5. Reload the first page (without since) when the reader pulls to refresh. That also drops entries the newsroom deleted.

How caching affects the delay. With the steps above, a new entry reaches the app within one polling interval (30 seconds in the NewsLoop app), plus the time the request takes:

Subscribers-only live blogs (is_premium: true) keep their entries for readers who can read the article: members (send the token), or readers whose meter token already counts it. Open the article with GET /posts/{post} first, then send its meter token in X-NF-Meter with each request. Anyone else gets 403. These answers are never cached.

Sign-in tokens, from start to finish ​

Reading needs no account. For a reader's own things (their account, bookmarks and likes), the app needs a token:

Sequence diagram: 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" on each request, signs in again after a 401, and signs out with DELETE /auth/token

  1. Get a token in one of three ways. Each answers { "data": { "token": "…", "token_type": "Bearer", "user": { … } } }:
    • register: POST /auth/register with name, email, password, password_confirmation and device_name (201);
    • sign in: POST /auth/token with email, password and device_name (200). With two-step sign-in on, see Two-step sign-in;
    • Google or Apple: sign in with the provider's SDK, then send its ID token to POST /auth/social (200; see Google and Apple).
  2. Keep it safe. The token is shown only this once; the site stores only a hash of it. Keep it in the phone's secure storage (the NewsLoop app uses the iOS Keychain and the Android Keystore), never in plain files or logs.
  3. Use it. Send Authorization: Bearer <token> with every request that needs an account, such as GET /me or POST /me/bookmarks.
    • Tokens don't expire with time.
    • Each device has its own token, named by device_name. A reader keeps the newest 20; signing in on a 21st device ends the oldest.
  4. When it stops working, any request answers 401. Forget the token and sign in again. A token stops working:
    • when the reader changes their password (every device is signed out);
    • when the account is deleted;
    • after signing out on that device;
    • after 20 newer sign-ins.
  5. Sign out with DELETE /auth/token, sending the token. It answers 204 and deletes only this device's token, so the reader's other devices stay signed in. Then delete the token from the phone.

A complete example in Dart ​

Building an app on the API: a walkthrough in Dart is a complete, runnable Dart program, explained step by step. It fetches article lists page by page, opens an article and splits its content_html into native parts, signs in and keeps the token, handles a 401 by getting a new token (one shared sign-in, then a retry), and signs out. It needs only the Dart SDK, and is in your download as Documentation/api/examples/newsloop_client.dart.

Two-step sign-in ​

If an account has two-step sign-in, POST /auth/token first answers 422 with two_factor: true. Ask for the code from the authenticator app and send the same request again with code, or recovery_code.

Google and Apple ​

Sign in with the provider's own SDK in the app, then send its ID token to POST /auth/social with provider (google or apple). If you used a nonce, send the raw nonce too. Apple sends the reader's name only the first time, so pass it as name.

New readers get an account with a confirmed email. Existing reader accounts with the same confirmed email are connected. Staff accounts and accounts with two-step sign-in are not: they sign in with their password.

Deleting an account ​

DELETE /me with the password. Accounts made with Google or Apple have no password; they send confirm: true. Any membership is stopped at the payment company first. Staff accounts cannot be deleted from the app.

Notifications ​

The app subscribes to Firebase topics itself. GET /push/topics lists them. Subscribe to both fcm_topic and fcm_language_topic: notifications for one language go to the second, those for everyone to the first. POST /devices records the phone's token and topics, which links it to the reader when signed in.

Layout sources that depend on the screen ​

The app layout (GET /app/config) may use two data sources that GET /posts does not take, because their meaning depends on the page:

Likes ​

GET /posts/{id} has likes: {count, liked}; liked is true when the signed-in reader liked it. Signed-in readers like with POST /posts/{id}/like and take it back with DELETE. Both answer with the new count. Guests see the count only, and it can be a few minutes old, as answers for guests are cached.

Saved articles ​

Save with POST /me/bookmarks, remove with DELETE /me/bookmarks/{id}. After working offline, send everything saved and removed to POST /me/bookmarks/sync. It answers with every saved article ID. A reader can save up to 1,000 articles.

Syncing more than 500 changes. One sync request takes up to 500 items in add and up to 500 in remove. More than that answers 422 (errors.add or errors.remove), and nothing is changed. To send more, split them into batches:

  1. Send the removals first, in batches of up to 500 ({"remove": [...]}). They make room under the 1,000-article limit.
  2. Then the additions, in batches of up to 500 ({"add": [...]}), oldest first.
  3. One request at a time, in order. Wait for each answer before sending the next.
  4. After each 200, mark that batch as done on the phone. The answer's post_ids is the reader's whole saved list at that moment: after the last batch, make the phone's list match it exactly.
  5. If a request fails (no connection, 429, 5xx), send the same batch again later. Sync is safe to repeat: saving an article that is already saved, or removing one that isn't, changes nothing. Each request is applied completely or not at all.
  6. A 422 with errors.post_id means the reader would go over 1,000 saved articles. Stop, keep the rest on the phone, and ask the reader to remove some. Articles that are no longer published are skipped without an error.

The limit-reached answer is under POST /me/bookmarks/sync in the API reference.

Trying it ​

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

curl -X POST https://news.example.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email":"reader@example.com","password":"…","device_name":"curl"}'

curl https://news.example.com/api/v1/me -H "Authorization: Bearer 1|nf_…"