# Search Commune

**GET /search**

Full text search across newsletters, articles, people and chat, ranked
by relevance.

Results obey the same gates as the resource operations do. An article
stamped with an audience, an article dated in the future, and a thread
that is not public are not returned to a key that could not read them
directly, so search cannot be used to see around a permission.

A query shorter than two characters returns an empty page rather than an
error, so a caller can send it on every keystroke.



## 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`.



### Query parameters

- **q** (string)
  The query. Shorter than two characters returns an empty page.

- **type** (string)
  Return only results of this kind. Repeat the parameter to accept
  several. Omit for all kinds.

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

- **limit** (integer)
  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.

- **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
A page of results, most relevant first.

#### Body: application/json (object)
- **object** (string)
  Always `list`, so a response is self describing.

- **data** (array)
  This page of items, in the order the operation documents.

- **pagination** (object)
  Cursor pagination state. Commune never exposes an offset or a page
  number: a collection is a moving window, and an offset silently skips or
  repeats items when the window shifts between two requests.


### 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)


### 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)