API endpoint · v1

List editions

Returns each edition you own, oldest first. An edition is what the dashboard calls a domain - the API keeps its original name. Start here: the slug in this response is the id every other endpoint takes in its path.

GET/v1/editions

On this page

When to use it

As your integration's first call. It gives you the id of each domain, and every other endpoint needs one.
To tell your domains apart by name, language and country before you pull from one.
To see how many draft and published articles each domain holds.

Request

curl https://api.mastheads.app/v1/editions \
  -H "Authorization: Bearer mh_live_your_key_here"

Response

200 OK

{
  "editions": [
    {
      "slug": "3f9c1e84-2b7a-4d6e-9c15-8a0d7e6b4f21",
      "name": "The Bristol Ledger",
      "publisher_target": "wordpress",
      "language_code": "en",
      "country_code": "GB",
      "timezone": "UTC",
      "created_at": "2026-06-01T09:00:00",
      "article_counts": { "draft": 12, "published": 130 }
    }
  ]
}

article_counts covers the two public statuses. An article still being written, delayed or failed is not counted, and does not appear on /v1 at all.

Field	Type	Notes
slug	string	The edition UUID. v5 has no separate slug column, so this is what the other endpoints take in their path.
name	string	The edition's display name.
publisher_target	string	Where the domain publishes - the connected platform, such as wordpress or ghost. "draft" when nothing is connected.
language_code	string	The edition's writing language.
country_code	string	The country it covers.
timezone	string	Always "UTC". v5 stores every timestamp in UTC and has no per-edition clock.
created_at	string	Naive ISO-8601, UTC, no offset.
article_counts	object	Counts for the two public statuses only: draft and published.

Errors

Status	Code	When
401	invalid_key	Missing, invalid, or revoked API key.
429	rate_limited	Over 120 requests/minute on this key. Retry-After: 60.
503	unavailable	The data store could not be reached.

Every request needs a key - Authentication. The error shape and the full status table are on Rate limits & errors.