# Retrieve a message

**GET /messages/{message}**

Read one reply. A message inherits the visibility of the thread it sits
in, so this answers `404` whenever the thread would.



## Servers
- Production. There is no separate sandbox host.
: https://api.usecommune.com (Production. There is no separate sandbox host.
)


## Authentication methods
- Api key


## Parameters
### Headers

- **Commune-Version** (string(date))
  The contract version this request is written against, as a release date
  (`YYYY-MM-DD`). Omitting the header pins the request to the version that
  was current when the API key was issued, so an integration keeps working
  when a newer version ships. An unknown value answers `400` with
  `invalid_version`.


### Path parameters

- **message** (string)
  The message's `id` (a UUID) or its `short_id`.


### Query parameters

- **expand** (string)
  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`.

  One accepted path is not a relationship. `?expand=content` on
  `GET /articles/{article}` adds the Markdown rendition of the body
  beside the HTML one. It is the same trade the parameter always offers,
  a fuller response for a larger one, over a property that has more than
  one representation rather than over a reference.

- **fields** (string)
  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`.

  A trimmed body is a subset of the schema this operation declares, and a
  property that schema marks required is absent when it was not asked for.
  That is the point of the parameter, so a client that validates responses
  against the schema either sends no `fields` or relaxes `required`.



## Responses
### 200
The message.

#### Body: application/json (object)
- **object** (string)
  Always `message`.

- **id** (string(uuid))
  Stable identifier.

- **short_id** (string | null)
  Eight character base62 identifier used by the message's permalink.
  Null for a row that predates short ids.

- **thread** (object | null)
  The thread this reply belongs to. A `Ref` unless `thread` is named
  in `?expand=`.

- **newsletter** (object | null)
  The community the thread lives in, denormalised so a client does not
  have to walk up to it. A `Ref` unless `newsletter` is named in
  `?expand=`.

- **author** (object | null)
  Who wrote the reply. A `Ref` unless `author` is named in `?expand=`.

- **parent** (object | null)
  The message this one replies to, or `null` when it replies to the
  thread itself. A `Ref` unless `parent` is named in `?expand=`.

- **quoted** (object | null)
  The message this one quotes, when the author quoted rather than
  replied. `null` otherwise. A `Ref` unless `quoted` is named in
  `?expand=`.

- **depth** (integer)
  `1` for a reply to the thread, `2` for a reply to a reply. Commune
  does not nest deeper, so a client can render the tree with a fixed
  two level layout.

- **content** (string)
  The message body as HTML. Treat it as untrusted markup and render it
  in a sandboxed context.

- **media** (array[object])
  Attachments on the message.

- **highlight** (object | null)
  The passage of an article this reply is anchored to, when the reader
  wrote it from a highlight. `null` otherwise. A `Ref` unless
  `highlight` is named in `?expand=`.

- **created_at** (string(date-time))
  When the reply was written.

- **updated_at** (string(date-time))
  When the row last changed for any reason.

- **edited_at** (string(date-time) | null)
  When the author last edited the text or attachments. Not touched by
  reactions or other side effects, so it is a faithful edited marker.


### 400
The request was malformed: an unknown query parameter, an unparseable
cursor, an unknown `expand` path, or an unrecognised `Commune-Version`.


#### Body: application/json (object)
- **error** (object)


### 401
No API key was presented, or the key is unknown, revoked or expired.

All four answer identically, down to the wording. Saying that a key was
revoked rather than never issued confirms to whoever is holding the
string that it was once real, which a legitimate caller does not need
and a thief should not get.

#### Headers

- **WWW-Authenticate** (string)
  The authentication scheme this API accepts. Always
  `Bearer realm="Commune API"`; there is no second scheme and no
  query-parameter fallback, because a credential that can travel in a
  URL ends up in access logs and referer headers.


#### Body: application/json (object)
- **error** (object)


### 404
No such resource, or the key is not allowed to know that it exists.
Commune answers `404` rather than `403` where distinguishing the two
would leak the existence of private content.


#### Body: application/json (object)
- **error** (object)


### 429
Too many requests. Back off and retry after the interval named by the
`Retry-After` response header.

#### Headers

- **Retry-After** (integer)
  Seconds to wait before retrying.


#### Body: application/json (object)
- **error** (object)


### 500
Something failed inside Commune. The request may be retried.

#### Body: application/json (object)
- **error** (object)



[Powered by Bump.sh](https://bump.sh)