# Weir

> Public Reddit and X data for developers and AI agents, over a REST API and a remote MCP server.
> Each platform returns its own fields. Monitors run a saved query on a schedule and deliver signed
> webhooks when something new appears.

Reddit posts and X posts have different shapes, on purpose. A Reddit post has `subreddit`,
`selftext`, `author` (a username string), `score`, `upvoteRatio`, and `numComments`. An X post has
`text`, `author` (an object with `username` and `name`), `likeCount`, `retweetCount`, `replyCount`,
and `viewCount`. Nothing is renamed into a shared vocabulary and nothing is dropped to make the
shapes match. The only fields both carry are `id`, `url`, and `createdAt`.

Each platform has its own endpoints. There is no combined search: querying both is two calls, and
they can be issued in parallel.

## Connect

- MCP (preferred): `https://api.weirapp.io/mcp`, Streamable HTTP. Clients that can open a browser
  sign in with OAuth and need no key, for example
  `claude mcp add --transport http weir https://api.weirapp.io/mcp`. Clients that cannot (CI,
  `claude -p`, model APIs, agent frameworks) send `Authorization: Bearer <api key>` to the same URL:
  `claude mcp add --transport http weir https://api.weirapp.io/mcp --header "Authorization: Bearer $WEIR_API_KEY"`.
- Skill: fetch https://weirapp.io/SKILL.md, or tell your agent `set up https://weirapp.io/SKILL.md`.
- REST: create a key at https://weirapp.io/dashboard/keys, then send `Authorization: Bearer <key>`.

To check a connection, call the free `get_usage` tool or `GET /v1/whoami`.

<!-- generated:mcp-tools -->
MCP tools on every connection: `search_reddit`, `get_reddit_post`, `get_subreddit`, `search_subreddit`, `get_reddit_comments`, `get_subreddit_posts`, `get_subreddit_comments`, `search_subreddits`, `get_reddit_user`, `get_reddit_user_posts`, `get_reddit_user_comments`, `lookup_reddit`, `search_x`, `get_x_posts`, `get_x_post`, `get_x_replies`, `get_x_thread`, `get_x_quotes`, `get_x_retweeters`, `get_x_post_edits`, `get_x_users`, `search_x_users`, `get_x_user`, `get_x_user_about`, `get_x_user_posts`, `get_x_user_replies`, `get_x_user_media`, `get_x_user_highlights`, `get_x_user_followers`, `get_x_user_following`, `get_x_user_affiliates`, `get_x_user_subscriptions`, `get_x_list`, `get_x_list_members`, `get_x_list_posts`, `get_x_space`, `get_usage`, `get_limits`, `get_identity`.

Only on connections granted monitor or webhook access: `list_monitors`, `create_monitor`, `get_monitor`, `update_monitor`, `delete_monitor`, `list_monitor_results`, `list_monitor_runs`, `run_monitor`, `list_webhooks`, `create_webhook`, `update_webhook`, `delete_webhook`, `test_webhook`, `list_webhook_deliveries`.
<!-- /generated:mcp-tools -->

## Credits

- Prepaid. Purchased credits never expire. Every account gets 5,000 free credits a month, which
  reset monthly and do not roll over.
- Charged per **returned result**: 1 credit per successful call, plus 3 per Reddit post or comment
  and 1 per X post. A request that fails, is refused, or reaches a dead upstream costs nothing.
- `limit` applies **per call**. Two platforms at `limit: 100` can return and bill 200 results.
- Every response reports what it charged in the `x-credits-charged` header, and every endpoint's
  price is in the contract's `x-weir-billing` extension.
- `x-credits-remaining` is what the workspace can still spend after the call. Credits are prepaid;
  there is no reset to wait for.
- Out of credits returns **402** and is not retryable. Never retry a 402. Only a person can clear it,
  by adding credits at https://weirapp.io/dashboard/billing. Retrying never will. With
  `details.reason: "billing_hold"`, spending is paused for a refund or dispute, and the user must
  contact support@weirapp.io.
- Rate limiting returns **429** and is retryable: wait for `Retry-After`, then retry. With
  `details.reason: "credits_held"`, the account's last credits are held by its own in-flight calls,
  and it clears within seconds. 402 and 429 are separate codes because they need opposite responses.
- Limits follow the tier, which follows lifetime purchases net of refunds. Free: 30 requests a
  minute, 1 monitor, 1 webhook, no hourly monitors. $5 or more bought: 120 a minute, 10 monitors, 5
  webhooks, hourly monitors. $100 or more: 300, 50, 25. $500 or more: 600, 200, 100.
  `GET /v1/limits` returns the exact numbers for an account.

## Endpoints

Credits are the per-call charge plus the per-result charge.

<!-- generated:endpoints -->
### Reddit

- `POST /v1/reddit/search`: Search public Reddit posts. Credits: 1 + 3 per Reddit post.
- `GET /v1/reddit/posts/{id}`: Get one public Reddit post. Credits: 1 + 3 per Reddit post.
- `GET /v1/reddit/subreddits/{name}`: Get information about a public subreddit. Credits: 1 + 1 per subreddit.
- `POST /v1/reddit/subreddits/{name}/search`: Search posts within one subreddit. Credits: 1 + 3 per Reddit post.
- `GET /v1/reddit/posts/{id}/comments`: Get a Reddit comment tree as a flat list, page by page. Credits: 1 + 3 per Reddit comment.
- `GET /v1/reddit/subreddits/{name}/posts`: List a community's posts: hot, new, rising, top, or controversial. Credits: 1 + 3 per Reddit post.
- `GET /v1/reddit/subreddits/{name}/comments`: Read a community's newest comments, across every post. Credits: 1 + 3 per Reddit comment.
- `POST /v1/reddit/search/subreddits`: Find communities by name or topic. Credits: 1 + 1 per subreddit.
- `GET /v1/reddit/users/{username}`: Get a Reddit account's public profile. Credits: 1 + 1 per Reddit user.
- `GET /v1/reddit/users/{username}/posts`: List the posts an account has submitted. Credits: 1 + 3 per Reddit post.
- `GET /v1/reddit/users/{username}/comments`: List the comments an account has made. Credits: 1 + 3 per Reddit comment.
- `POST /v1/reddit/lookup`: Fetch up to 100 posts and comments, and 100 communities, in one call. Credits: 1 + 3 per Reddit post + 3 per Reddit comment + 1 per subreddit.

### X

- `POST /v1/x/search`: Search public X posts with composable filters. Credits: 1 + 1 per X post.
- `GET /v1/x/posts`: Get up to 100 public X posts by id. Credits: 1 + 1 per X post.
- `GET /v1/x/posts/{id}`: Get one public X post. Credits: 1 + 1 per X post.
- `GET /v1/x/posts/{id}/replies`: Get replies to an X post. Credits: 1 + 1 per X post.
- `GET /v1/x/posts/{id}/thread`: Get the author's thread containing a post. Credits: 1 + 1 per X post.
- `GET /v1/x/posts/{id}/quotes`: Get posts quoting an X post. Credits: 1 + 1 per X post.
- `GET /v1/x/posts/{id}/retweeters`: Get accounts that reposted an X post. Credits: 1 + 1 per X user result.
- `GET /v1/x/posts/{id}/edits`: Get the edit history of an X post. Credits: 1 + 1 per X post.
- `GET /v1/x/users`: Get up to 100 public X profiles by id. Credits: 1 + 2 per X profile.
- `POST /v1/x/users/search`: Search X accounts. Credits: 1 + 1 per X user result.
- `GET /v1/x/users/{user}`: Get a public X profile. Credits: 1 + 2 per X profile.
- `GET /v1/x/users/{user}/about`: Get an X account's "About this account" details. Credits: 1 + 2 per X profile.
- `GET /v1/x/users/{user}/posts`: Get a public X user timeline. Credits: 1 + 2 per X profile + 1 per X post.
- `GET /v1/x/users/{user}/replies`: Get an X account's posts and replies. Credits: 1 + 2 per X profile + 1 per X post.
- `GET /v1/x/users/{user}/media`: Get an X account's posts with media. Credits: 1 + 2 per X profile + 1 per X post.
- `GET /v1/x/users/{user}/highlights`: Get the posts an X account highlights. Credits: 1 + 2 per X profile + 1 per X post.
- `GET /v1/x/users/{user}/followers`: Get an X account's followers. Credits: 1 + 2 per X profile + 1 per X user result.
- `GET /v1/x/users/{user}/following`: Get the accounts an X account follows. Credits: 1 + 2 per X profile + 1 per X user result.
- `GET /v1/x/users/{user}/affiliates`: Get an organisation's affiliated X accounts. Credits: 1 + 2 per X profile + 1 per X user result.
- `GET /v1/x/users/{user}/subscriptions`: Get the creators an X account subscribes to. Credits: 1 + 2 per X profile + 1 per X user result.
- `GET /v1/x/lists/{id}`: Get a public X List. Credits: 1 + 2 per X list.
- `GET /v1/x/lists/{id}/members`: Get the members of a public X List. Credits: 1 + 1 per X user result.
- `GET /v1/x/lists/{id}/posts`: Get the timeline of a public X List. Credits: 1 + 1 per X post.
- `GET /v1/x/spaces/{id}`: Get an X Space. Credits: 1 + 2 per X space.

### Monitors

- `GET /v1/monitors`: List monitors. Credits: Free.
- `POST /v1/monitors`: Create a monitor. Credits: Free.
- `GET /v1/monitors/{id}`: Get one monitor. Credits: Free.
- `PATCH /v1/monitors/{id}`: Update a monitor. Credits: Free.
- `DELETE /v1/monitors/{id}`: Delete a monitor. Credits: Free.
- `GET /v1/monitors/{id}/results`: List deduplicated results a monitor has found. Credits: Free.
- `GET /v1/monitors/{id}/runs`: List a monitor's execution history. Credits: Free.
- `POST /v1/monitors/{id}/run`: Queue a monitor run immediately. Credits: Free.

### Webhooks

- `GET /v1/webhooks`: List webhooks. Credits: Free.
- `POST /v1/webhooks`: Create a webhook. Credits: Free.
- `PATCH /v1/webhooks/{id}`: Update a webhook. Credits: Free.
- `DELETE /v1/webhooks/{id}`: Delete a webhook. Credits: Free.
- `POST /v1/webhooks/{id}/test`: Queue a test delivery. Credits: Free.
- `GET /v1/webhook-deliveries`: List recent delivery attempts. Credits: Free.

### Account

- `GET /v1/usage`: Credit balance, holds, and this month's free grant. Credits: Free.
- `GET /v1/limits`: Ceilings imposed by the account's tier. Credits: Free.
- `GET /v1/whoami`: Identify the account and scopes behind this key. Credits: Free.
<!-- /generated:endpoints -->

## Links

- Skill manifest: https://weirapp.io/SKILL.md
- Everything in one file: https://weirapp.io/llms-full.txt
- OpenAPI contract: https://api.weirapp.io/openapi.json
- Interactive reference: https://api.weirapp.io/reference
- Pricing: https://weirapp.io/pricing