BYTETOOLS

Flathub API

Fetch Linux desktop app metadata, screenshots and release notes from Flathub as JSON with no API key. Verified example plus the epoch-as-string gotcha.

No API key requiredCORS enabledHTTPSFree tier

Endpoint tested and returned HTTP 200 on 2026-08-21

What is the Flathub API?

Flathub, the main Flatpak repository for Linux desktop applications, has a public JSON API. `GET https://flathub.org/api/v2/appstream/{app_id}` returns an application's AppStream metadata including its releases, descriptions and screenshots. No API key is required.

Flathub's API is a JSON projection of AppStream, the freedesktop metadata standard, so what comes back is not a bespoke schema but the same data a Linux software centre renders. That makes it a good source for anything that needs to describe Linux applications: release notes, screenshots, licences and categories are all present, keyed by the reverse-DNS application id such as `org.gimp.GIMP`.

The AppStream heritage explains the shape's quirks. Release descriptions are HTML fragments, complete with `<p>` and `<ul>` markup, so they need sanitising before display. `timestamp` on each release is Unix epoch seconds delivered as a string, while `date` is frequently null, which means the string field is the one you actually sort on after casting. Getting that pair wrong is the usual cause of release lists that appear in random order.

Quick facts

Base URL
https://flathub.org/api/v2
Authentication
No key or account. The API backs the Flathub website itself.
Rate limit
Not published. Application metadata changes only on release, so cache per app id.
Pricing
Free and open source.
CORS
Enabled — callable directly from browser JavaScript
Official docs
Read the docs

How to use the Flathub API

Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.

1. Fetch AppStream metadata for a Flatpak application

GET https://flathub.org/api/v2/appstream/org.gimp.GIMP

curl
curl 'https://flathub.org/api/v2/appstream/org.gimp.GIMP'
JavaScript (fetch)
const res = await fetch("https://flathub.org/api/v2/appstream/org.gimp.GIMP");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);
Python (requests)
import requests

res = requests.get("https://flathub.org/api/v2/appstream/org.gimp.GIMP", timeout=20)
res.raise_for_status()
print(res.json())
Response — HTTP 200 (truncated)
{
  "releases": [
    {
      "url": "https://www.gimp.org/release/3.2.4/",
      "type": "stable",
      "description": "<p>\n        The second bugfix release of the GIMP 3.2 series brings it to quite a stable state again as bugs reports are slowing down.\n        </p>\n          <ul>\n            <li>Bug fixed where GIMP would fail to open some XCF</li>\n            <li>When moving a floating layer or selection with a selection tool, marching ants are now disabled</li>\n            <li>Improved Text tool, especially regarding prioritizing global actions</li>\n            <li>Better temporary folder handling</li>\n            <li>Fill actions now behave accordingly to the target item type</li>\n            <li>Various file formats support improved</li>\n            <li>A new function and a deprecation in the libgimp API for plug-ins</li>\n          </ul>\n        ",
      "urgency": null,
      "version": "3.2.4",
      "date_eol": null,
      "date": null,
      "timestamp": "1776384000"
    },
    {
      "url": "https://www.gimp.org/release/3.2.2/",
      "type": "stable",
      "description": "<p>\n        Here we go! The first bugfix release for the GIMP 3.2 series is here.\n        </p>\n          <ul>\n            <li>A bug when group layers became invisible in some conditions when children had effects got fixed</li>\n            <li>More fixes, especially for the new vector and link layer types, as well as non-destructive effects</li>\n            <li>Various file formats support improved</li>\n            <li>Themes fixes and improvements</li>\n            <li>Su

Parameters

ParameterTypeRequiredDescription
{app_id}pathRequiredReverse-DNS application id exactly as published, including capitalisation. org.gimp.GIMP
/api/v2/appstreampathOptionalEndpoint listing every application id in the repository. /api/v2/appstream
/api/v2/statspathOptionalRepository-wide download statistics endpoint. /api/v2/stats

Response fields

releasesarray
Release history, newest first. Each entry carries `version`, `type`, `description`, `url` and `timestamp`.
releases[].descriptionstring
HTML fragment of release notes, including `<p>` and `<ul>` markup. Sanitise before rendering; it is not plain text and not Markdown.
releases[].timestampstring
Unix epoch seconds as a STRING. Cast to an integer before converting to a date, and use this rather than `date`, which is often null.
releases[].typestring
`stable` or `development`. Filter on it if you only want shipping versions.
releases[].date_eolstring or null
End-of-life date for that release when the publisher declares one, otherwise null.
(top level) name / summary / descriptionstring
Application name, one-line summary and full description, again as AppStream markup.

What you can build with the Flathub API

  • Show the latest version and release notes of a Linux app on a download page
  • Check whether a Flatpak dependency has shipped a security update
  • Build a software catalogue or comparison site for Linux desktop applications
  • Pull screenshots and descriptions for an app store front end
  • Monitor a set of applications for new stable releases

Common errors and how to fix them

404

The application id is wrong. Ids are case-sensitive reverse-DNS strings.

Fix: `org.gimp.GIMP` is not `org.gimp.gimp`. Fetch the full id list from `/api/v2/appstream` to confirm.

Releases appear unsorted

You sorted on `date`, which is frequently null.

Fix: Cast `timestamp` from string to integer and sort on that instead.

Broken layout from release notes

`description` contains raw HTML.

Fix: Sanitise it through an allowlist before injecting it into a page, or strip tags if you only need text.

Flathub API — frequently asked questions

Is the Flathub API free to use?

Yes, with no key or account. It is the same API that powers the Flathub website.

How do I find an application's id?

Ids are reverse-DNS strings shown on each app's Flathub page, such as `org.gimp.GIMP`. The `/api/v2/appstream` endpoint returns the complete list.

Are release notes plain text?

No. They are AppStream HTML fragments with paragraph and list markup, so sanitise them before rendering and do not expect Markdown.

Can I get download statistics?

Yes, `/api/v2/stats` exposes repository-wide and per-application download figures, though they are aggregated rather than real-time.

Tools that pair with this API

Flathub is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.