Website domains

Retrieve a website domain

Read one of the creator's hostnames: which Commune website origin answers for it, the records to publish, and the last reachability probe. Needs settings: read.

Resolves whatever the hostname serves. mode says which, and a hostname serving the creator's own pages resolves here exactly as one serving the Commune newsletter page does: this is the operation that answers "what is this hostname doing", and an answer that omitted half the hostnames would be the wrong one.

get/domains/{domain}

Request

  • Base URL: https://api.usecommune.com
  • URL: https://api.usecommune.com/domains/{domain}
  • 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

expandstring

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.

fieldsstring

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.

Response

The website domain.

object'domain' required

Always domain.

idstring uuid required

Stable identifier.

domainstring required

The hostname, unique across Commune.

mode'app' | 'site' required

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.

verification_status'pending' | 'active' | 'failed' required

Whether ownership of the domain was proved and a certificate issued. active does not by itself mean the site is reachable, see routing_ok.

ssl_statusstring nullable

Where the certificate stands, as reported by the provider that issues it. Free text rather than an enum, because the vocabulary is the provider's and Commune passes it through.

dns_targetstring nullable

What the creator must point the hostname at.

verification_errorstring nullable

Why verification last failed. Null when it has not failed.

routing_okboolean nullable

Whether the domain actually resolves to Commune, from an end to end request rather than from certificate state. Null before the first probe. This is the field that catches a domain whose certificate is fine but whose DNS points somewhere else.

routing_checked_atstring date-time nullable

When that probe last ran.

verified_atstring date-time nullable

When ownership was first proved. Null if it never was.

last_checked_atstring date-time nullable

When Commune last reconciled the domain with its provider.

created_atstring date-time required

When the domain was added.

Example response

{
  "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.