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.
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 'https://flathub.org/api/v2/appstream/org.gimp.GIMP'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);import requests
res = requests.get("https://flathub.org/api/v2/appstream/org.gimp.GIMP", timeout=20)
res.raise_for_status()
print(res.json()){
"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>SuParameters
| Parameter | Type | Required | Description |
|---|---|---|---|
{app_id} | path | Required | Reverse-DNS application id exactly as published, including capitalisation. org.gimp.GIMP |
/api/v2/appstream | path | Optional | Endpoint listing every application id in the repository. /api/v2/appstream |
/api/v2/stats | path | Optional | Repository-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
JSON Formatter
Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.
Timestamp Converter
Convert timestamps to human-readable dates and dates back to timestamps. Auto-detects seconds vs milliseconds, shows local, UTC and ISO 8601 formats.
Strip HTML Tags
Remove all HTML tags and convert markup to clean plain text. Decode HTML entities and keep line breaks for block elements like paragraphs and headings.
HTML to Markdown Converter
Convert HTML to clean Markdown — headings, emphasis, links, images, nested lists, code blocks, tables and blockquotes — privately in your browser.
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.