List a newsletter's website domains
The creator's own hostnames attached to this newsletter, each saying which Commune website origin answers for it. Needs settings: read.
What this returns has been described more narrowly than it behaved. It used to say "the domains pointed at this newsletter's Commune site", and that was the same set only while a hostname could serve nothing else. A hostname can now serve the creator's own pages instead, this collection has always returned every row of the table, and mode on each entry is what makes "every row" readable rather than misleading. Use ?mode=app for the old reading of this list, and nothing filters unless you ask.
Two independent things have to be true for a hostname to work, and they are reported separately. verification_status says whether ownership was proved and a certificate issued. routing_ok says whether the hostname actually resolves to Commune, which a certificate says nothing about.
Request
- Base URL: https://api.usecommune.com
- URL: https://api.usecommune.com/newsletters/{newsletter}/domains
- Auth: one of:
- HTTP bearer
- OAuth 2 (authorization code, authorization URL https://usecommune.com/api/oauth/authorize, token URL https://usecommune.com/api/oauth/token, scopes: settings:read)
Query parameters
The pagination.next_cursor value from the previous page. Omit it to read the first page. A cursor is opaque, is only valid for the same operation with the same filters, and is not a durable identifier.
How many items to return in this page. This is a page size, not an offset. Fewer items than requested may come back and that does not mean the collection is exhausted, only an absent next_cursor does.
Comma-separated list of relationship paths to inline in the response. Unexpanded relationships are returned as a reference object carrying only id and object. Each operation documents the paths it accepts, and an unknown path answers 400. Nested paths use a dot, for example article.newsletter.
Comma-separated allow-list of top level properties to return on each object, so a client can trim a response it does not need in full. id and object are always returned. An unknown property name answers 400. Properties omitted by an operation, such as content on any article list, cannot be brought back with fields.
What a hostname serves.
app is the Commune newsletter page, with sessions: readers sign in, chat and highlight there, and it is the mode every hostname starts on. site is the creator's own pages, served from an origin that never carries a Commune session.
One host can carry a session or run creator JavaScript, never both, because the origin is the only security boundary a browser has: code running on an origin that holds a session can call Commune with the visitor's cookie. So a hostname is one or the other, and a newsletter holds at most one of each.
Return only hostnames serving this. Omit for all of them.
Response
A page of website domains.
Example response
{
"pagination": {
"next_cursor": "Y3Vyc29yOjE3NTY0MjM2MDAwMDA6MDE5MmM4"
},
"data": [
{
"newsletter": {
"object": "newsletter",
"id": "9a4c1c6e-0f2b-4f47-9d3f-6d1b1a2c3d4e"
},
"domain": "blog.example.org",
"verification_records": [
{
"type": "CNAME",
"name": "mail._domainkey.example.org"
}
]
}
]
}Changes
No recorded changes to this operation across all 1 revision of this API.