Find communities by name or topic

POST /v1/reddit/search/subreddits

Communities whose name or description matches the query, with member counts. Use it to find where a topic is discussed before reading or watching those communities. To search posts inside one community, use POST /v1/reddit/subreddits/{name}/search instead.

Price: 1 credit per call, plus 1 credit per subreddit returned. Failed and refused calls cost nothing.

Rate limit: Counts as 2 requests against your per-minute rate limit.

MCP tool: search_subreddits, on every MCP connection.

Requires an API key, sent as Authorization: Bearer <key>.

Request

curl --request POST \
  --url https://api.weirapp.io/v1/reddit/search/subreddits \
  --header "Authorization: Bearer $WEIR_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"query":"payment failures"}'

Body

Field	Type	Required	Notes
`query`	string	yes	Words to match against community names and descriptions. · 1–500 chars
`sort`	string	no	`activity` favours communities that are busy right now. · `relevance`, `activity`, default `"relevance"`
`includeNsfw`	boolean	no	Include results marked NSFW. Off by default; what it removes is reported in `meta.omittedNsfw`. · default `false`
`limit`	integer	no	1–100, default `25`
`cursor`	string	no	`meta.nextCursor` from the previous page, unchanged. Opaque, signed, and bound to the other parameters: change any of them and start again without a cursor. · 1–4096 chars

Response

Communities, in Reddit's own field names.

`200`

Field	Type	Required	Notes
`data`	array of object	yes
`data[].id`	string	yes	Reddit's fullname for the community, `t5_` included.
`data[].name`	string	yes	Community name without the `r/` prefix.
`data[].title`	string	yes
`data[].description`	string or null	yes	The short public description. Null if unset.
`data[].url`	string	yes
`data[].subscribers`	integer	yes	min 0
`data[].over18`	boolean	yes	The whole community is marked NSFW.
`data[].createdUtc`	number	yes
`data[].createdAt`	string (date-time)	yes
`data[].subredditType`	string	yes	`public`, `restricted`, `private`, `archived`, `gold_restricted`, or `user`.
`data[].submissionType`	string or null	yes	What may be posted: `any`, `link`, or `self`.
`data[].lang`	string or null	yes	The community's declared language, such as `en`.
`data[].quarantine`	boolean	yes	Quarantined by Reddit: hidden from search and listings.
`data[].communityIcon`	string or null	yes	URL of the community icon. Null if unset.
`data[].bannerImg`	string or null	yes	URL of the banner image. Null if unset.
`meta`	object	yes
`meta.requestId`	string	yes
`meta.nextCursor`	string or null	no
`meta.omittedNsfw`	integer	no	Items removed from this page because they are marked NSFW and `includeNsfw` is false. Absent when nothing was removed. A page can be short, or even empty with a non-null `nextCursor`, because of it. · min 0

Errors

Status	Meaning	What to do
`400`	The request failed validation.	The request was malformed. The `details` object names the field.
`401`	The API key is missing, malformed, expired, or revoked.	The key is missing, malformed, revoked, or expired.
`402`	The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes.	Out of credits. Never retry. Only a person can clear it, by adding credits at https://weirapp.io/dashboard/billing. Retrying never will.
`403`	The API key does not carry the scope this route requires.	The key is valid but lacks the scope this operation needs.
`404`	The requested resource does not exist.	No such resource, or it is not public.
`429`	The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again.	Rate limited. Retryable: wait for `Retry-After`, then try again.
`500`	An unexpected error occurred.	Something failed on our side. Retryable with backoff.
`503`	The source is temporarily unavailable. The request is safe to retry.	A source was unreachable. Retryable with backoff.