Omarchy APIplugins.omarchy.org ↗
Query the Omarchy community plugin catalog via API. Retrieve plugin metadata, engagement stats (views, copies, hearts), GitHub stars, and category filters.
What is the Omarchy API?
The Omarchy Plugin Marketplace API exposes 2 endpoints for reading the plugins.omarchy.org community catalog. The list_new_plugins endpoint returns paginated plugin records ordered newest-first, each carrying catalog metadata (name, description, author, version, category, tags), engagement counters (views, copies, hearts), and GitHub stars. The get_plugin endpoint resolves any plugin by its registry ID to the same full record.
curl -X GET 'https://api.parse.bot/scraper/a46fbc55-ee47-4de5-ac53-a5bce64bcba7/list_new_plugins?added_within_hours=168' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace plugins-omarchy-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Omarchy plugin marketplace — browse, inspect, and look up plugins."""
from parse_apis.plugins_omarchy_org_api import Omarchy, PluginNotFound
client = Omarchy()
# Browse the newest community plugins, capped at 5 total items.
for plugin in client.plugins.list(limit=5):
print(plugin.name, f"by {plugin.author}", f"★{plugin.github_stars}", f"♥{plugin.hearts}")
# Drill into one recent Developer Tools plugin to inspect its detail.
dev_plugin = client.plugins.list(category="Developer Tools", limit=1).first()
if dev_plugin is not None:
print(dev_plugin.name, dev_plugin.version, dev_plugin.category)
print(dev_plugin.description[:120])
if dev_plugin.repository_release is not None:
print("release:", dev_plugin.repository_release.tag, dev_plugin.repository_release.url)
# Fetch the full record by id discovered above, confirming freshest stats.
try:
detail = client.plugins.get(id=dev_plugin.id)
print(detail.name, "views:", detail.views, "copies:", detail.copies)
except PluginNotFound:
print("plugin was delisted since the listing was fetched")
print("exercised: plugins.list / plugins.get / Release fields / PluginNotFound")
Returns community plugins from the marketplace registry ordered by listing time, newest first (the site's 'Recently added' order), one row per plugin with its full catalog metadata plus engagement counters (views, copies, hearts) and GitHub stars. Built-in plugins are excluded. Optional filters: added_within_hours keeps only plugins listed within that many hours before now; category keeps only plugins whose catalog category matches (case-insensitive; an unknown category yields an empty list). Pagination is a true offset over the filtered, sorted set via page and page_size (page_size is clamped to 200); has_more tells whether a further page exists and total_matching is the filtered count. is_new mirrors the site's 'New' badge (listed within the last 12 hours) and is_recently_updated its 'Updated' badge (version bump within 12 hours). Each call loads the whole registry (about 3,500 plugins) so latency is a few seconds regardless of page size. Fields like install_command, repository_release, version_updated_at, verification_method and preview URLs are null when the catalog has no value.
| Param | Type | Description |
|---|---|---|
| page | integer | 1-based page number over the filtered, newest-first list. |
| category | string | Catalog category label to filter by, matched case-insensitively against each plugin's category (categories observed: Widgets, Productivity, System, Hardware, Desktop, Appearance, Developer Tools, Other, Kids). Omitted = all categories. |
| page_size | integer | Plugins per page; values above 200 are clamped to 200. |
| added_within_hours | integer | Only include plugins listed within this many hours before the call. Omitted = no time filter (all community plugins, newest first). |
{
"type": "object",
"fields": {
"page": "integer, echoed page",
"plugins": "array of plugin records: id, name, description, author, version, category, tags (array of strings), kind, status, source_type, built_in, repo (GitHub URL), manifest_path, repository_layout, license, install_available, install_command, install_note, verification_status, verification_coverage, verification_method, verification_checked_at, added_at (YYYY-MM-DD), listed_at (ISO), version_updated_at, repository_updated_at, repository_release {tag,url,published_at} or null, upstream_check_status, upstream_checked_at, github_stars, views, copies, hearts, preview_image_url, preview_thumbnail_url, is_new, is_recently_updated, page_url",
"category": "string or null, the applied category filter",
"has_more": "boolean, true when a later page exists",
"page_size": "integer, effective page size after clamping",
"total_matching": "integer, plugins matching the filters across all pages",
"added_within_hours": "integer or null, the applied time filter",
"catalog_generated_at": "ISO timestamp when the site last regenerated its registry",
"total_community_plugins": "integer, all community plugins in the registry before filtering"
},
"sample": {
"data": {
"page": 1,
"plugins": [
{
"id": "jao.nightlight",
"kind": "Bar widget",
"name": "Blue-light-blocker",
"repo": "https://github.com/abdessamadjaouad/blue-light-blocker",
"tags": [
"hyprland",
"quickshell",
"system"
],
"views": 118,
"author": "jao",
"copies": 9,
"hearts": 3,
"is_new": true,
"status": "Available",
"license": "See repository",
"version": "1.0.1",
"added_at": "2026-09-18",
"built_in": false,
"category": "System",
"page_url": "https://plugins.omarchy.org/#jao.nightlight",
"listed_at": "2026-09-18T02:05:26.305Z",
"description": "Blue-light blocking profiles, screen dimming and a local-time night-light schedule.",
"source_type": "community",
"github_stars": 0,
"install_note": "Omarchy clones the current upstream repository, validates it locally, and only then installs and enables the plugin.",
"manifest_path": "manifest.json",
"install_command": "omarchy plugin add https://github.com/abdessamadjaouad/blue-light-blocker.git --enable",
"install_available": true,
"preview_image_url": null,
"repository_layout": "root-plugin",
"repository_release": {
"tag": "v1.0.1",
"url": "https://github.com/abdessamadjaouad/blue-light-blocker/releases/tag/v1.0.1",
"published_at": "2026-09-17T21:50:59Z"
},
"version_updated_at": null,
"is_recently_updated": false,
"upstream_checked_at": "2026-09-18T02:05:26.799Z",
"verification_method": null,
"verification_status": "verified",
"preview_thumbnail_url": null,
"repository_updated_at": "2026-09-17T21:50:54Z",
"upstream_check_status": "passed",
"verification_coverage": "snapshot-verified",
"verification_checked_at": "2026-09-18T02:05:26.210Z"
}
],
"category": null,
"has_more": true,
"page_size": 3,
"total_matching": 3451,
"added_within_hours": null,
"catalog_generated_at": "2026-09-18T02:08:47.071Z",
"total_community_plugins": 3451
},
"status": "success"
}
}About the Omarchy API
What the API covers
Both endpoints draw from the plugins.omarchy.org registry and return the same core field set: id, name, description, author, version, category, tags, kind, status, source_type, views, copies, hearts, github_stars, is_new, is_recently_updated, repository_release (an object with tag, url, and published_at), and a catalog_generated_at timestamp indicating when the registry was last regenerated.
list_new_plugins
list_new_plugins returns community plugins sorted newest-first — the same ordering the site labels "Recently added". Built-in plugins are excluded. You can narrow results with category (case-insensitive match against each plugin's category label), added_within_hours (only plugins listed within that window), and standard pagination via page and page_size (capped at 200). The response includes total_matching, total_community_plugins, and has_more so you can track pagination state without a separate count call.
get_plugin
get_plugin accepts a single plugin_id — exactly as emitted in the plugins[*].id field of list_new_plugins — and returns the full registry record for that plugin. It also resolves built-in plugin IDs, which list_new_plugins does not enumerate. The is_new boolean reflects whether the plugin was listed within the last 12 hours; is_recently_updated reflects whether its version was updated within the same window. Both flags correspond to the badge states displayed on the marketplace site.
The Omarchy API is a managed, monitored endpoint for plugins.omarchy.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when plugins.omarchy.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official plugins.omarchy.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Monitor newly added Omarchy plugins by polling
list_new_pluginswithadded_within_hoursto catch same-day additions. - Build a community dashboard showing top-engaged plugins ranked by
heartsorcopiescounters. - Track
github_starsandrepository_release.published_atto surface actively maintained plugins. - Filter the catalog to a specific
categoryand export results for documentation or a curated plugin directory. - Alert on new
is_recently_updatedplugins in a chosen category to keep a downstream plugin list current. - Resolve a known plugin ID via
get_pluginto check its currentversion,status, and engagement stats in one call.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does plugins.omarchy.org have an official developer API?+
What does the `repository_release` field contain, and when is it null?+
repository_release is an object with three fields: tag (the release tag string), url (link to the release), and published_at (ISO timestamp). It is null when the plugin's repository has no recorded release in the registry.Does `list_new_plugins` include built-in Omarchy plugins?+
list_new_plugins is filtered to community plugins only. Built-in plugins are excluded from pagination results but are resolvable by ID through get_plugin.How fresh is the data?+
catalog_generated_at field — an ISO timestamp showing when the registry was last regenerated on the site. This is the authoritative freshness indicator. Data reflects the most recent registry generation at call time; there is no way to query historical snapshots of the catalog.Can I retrieve individual plugin changelogs or install instructions through this API?+
repository_release.tag, url, published_at), but does not expose changelogs, full README content, or install command text. You can fork this API on Parse and revise it to add an endpoint targeting those fields.