Your first request.

Base URL: https://subsignal.dev. Data endpoints use /v1 and return JSON. You can read this guide without signing in.

1. Create an account, verify your email, then sign in with your password. The owner approves API access during the pilot.
2. Open API keys and create a named key for your application or agent. Save it when shown; the secret is displayed once.
3. Set SUBSIGNAL_API_KEY in your application's secret environment. Send it as the X-API-Key header.
4. Run the request below, then check Usage in your workspace.

curl --fail-with-body --get 'https://subsignal.dev/v1/subreddit/python/feed' \
  --data-urlencode 'sort=hot' \
  --data-urlencode 'limit=5' \
  --header "X-API-Key: $SUBSIGNAL_API_KEY"

Application keys created in the dashboard have reddit:read and usage:read. Only the owner can add instagram:read to a key; such a key can still be rotated or revoked here, and rotation keeps its scopes. They cannot manage keys or sign in to the workspace. Your email/password account session is independent of every API key. API calls use the header above, not the portal's session cookie.

Use keys in server-side code or a trusted local agent runtime. Keep them out of frontend bundles, chat prompts, source control, and logs. Rotating a key in the dashboard immediately invalidates the old one; update your application's secret at the same time.

Find conversations about a topic.

Search returns a list of wrappers: each post is inside items[].post. Feed endpoints return posts directly in items[]. These examples make one request and do not retry automatically.

curl --fail-with-body --get 'https://subsignal.dev/v1/search' \
  --data-urlencode 'q=subreddit:python asyncio' \
  --data-urlencode 'type=posts' \
  --data-urlencode 'sort=relevance' \
  --data-urlencode 'limit=5' \
  --header "X-API-Key: $SUBSIGNAL_API_KEY"

import json
import os
from urllib.error import HTTPError
from urllib.parse import urlencode
from urllib.request import Request, urlopen

query = urlencode({
    "q": "subreddit:python asyncio", "type": "posts", "limit": 5,
})
request = Request(
    "https://subsignal.dev/v1/search?" + query,
    headers={"X-API-Key": os.environ["SUBSIGNAL_API_KEY"]},
)
try:
    with urlopen(request, timeout=30) as response:
        payload = json.load(response)
except HTTPError as error:
    raise RuntimeError(f"Subsignal HTTP {error.code}: {error.read().decode()}") from None

for item in payload["items"]:
    post = item.get("post")
    if post:
        print(post["title"], post["permalink"])

const key = process.env.SUBSIGNAL_API_KEY;
if (!key) throw new Error("Set SUBSIGNAL_API_KEY in your secret environment");
const url = new URL("https://subsignal.dev/v1/search");
url.search = new URLSearchParams({
  q: "subreddit:python asyncio", type: "posts", limit: "5",
});
const response = await fetch(url, {
  headers: { "X-API-Key": key },
  signal: AbortSignal.timeout(30_000),
});
const payload = await response.json();
if (!response.ok) {
  throw new Error(`Subsignal ${response.status}: ${payload.error?.message}`);
}
for (const item of payload.items) {
  if (item.post) console.log(item.post.title, item.post.permalink);
}

Success responses include meta.request_id, meta.cached, meta.source, and meta.generated_at. Cache hits keep the original generation time. Nullable fields mean data was absent or unavailable; do not turn missing karma into zero.

Choose the data you need.

All routes below use GET. The interactive API reference lists every parameter, default, enum, and response schema. Download OpenAPI JSON for client generation or custom agent tools.

Use a subreddit name such as python without r/, and a username without u/. Posts accept bare base36 IDs or t3_ fullnames. Use query encoding for keywords and cursor values.

Read another page, deliberately.

Feeds, search, and user histories include page.has_next_page and page.next_cursor. When another page is available, send the returned cursor unchanged with the same endpoint and query parameters, including limit and sort.

{
  "page": {
    "has_next_page": true,
    "next_cursor": "SERVER_ISSUED_TOKEN"
  }
}

This is an illustrative page envelope, not a usable cursor. Stop when has_next_page is false or next_cursor is null. Tokens expire; 400 invalid_cursor means restart from the first page if the task still needs it. Never construct or decode a token. Set a maximum page count for every job and deduplicate posts by ID.

Post comment trees are different: page (or embedded comments_page) is terminal even when the Reddit thread contains more comments. Sending a cursor to /v1/comments/{post_id} returns 400.

Handle the response, keep the context.

{
  "error": {
    "code": "upstream_unavailable",
    "message": "Reddit could not complete the request.",
    "request_id": "EXAMPLE_REQUEST_ID",
    "retryable": true,
    "details": {}
  }
}

Every response includes X-Request-ID. Keep it for troubleshooting. Validation failures use HTTP 400 rather than 422.

• 400 · invalid_request / invalid_cursor: fix parameters or restart pagination.
• 401 · invalid_api_key: check the header, key value, expiry, or rotation.
• 403 · scope_denied: check key scopes and whether the key has been disabled. An agent connection approved for Reddit only gets this on Instagram reads; reconnect and approve Instagram to change it.
• 403 · instagram_not_entitled: the credential has instagram:read but the owner has not enabled Instagram for this workspace. The credential itself is fine; do not rotate or reconnect.
• 404 · resource not found: check the subreddit, post, or username; do not retry indefinitely.
• 429 · partner_rate_limited: wait for Retry-After. Rate-limit headers describe your key's current window.
• 429 · quota_exceeded: stop the job and inspect your allowance. A monthly limit will not clear after a short retry.
• 500 / 503: if error.retryable is true, use a small, bounded retry count with backoff and jitter. Keep the request ID if failures persist.

RateLimit-Limit is your per-minute limit; RateLimit-Remaining is the remaining count; RateLimit-Reset is a Unix timestamp. Retry-After is a delay in seconds. Use the issued key's actual limits rather than hardcoding an assumed allowance.

Usage and pilot allowance

Each admitted data request consumes the shared monthly allowance before execution, including cache hits and upstream failures. Client retries are new requests. Rejected authentication, scope, and limit checks do not consume admission, but authenticated responses can still appear in recorded usage. These totals measure different things.

The dashboard shows workspace totals across keys. /v1/usage shows only the requesting key and needs usage:read. Agent OAuth tokens have only read scopes (reddit:read, plus instagram:read when approved) and cannot access this endpoint. Usage periods are UTC calendar months. Billing is not enabled: billable-equivalent counters and units per 1,000 are usage measurements, not invoices or charges.

Give your agent a listening pass.

Start at Agents and copy the setup prompt. The setup playbook installs the self-contained Subsignal skill from this origin, obtains your explicit browser approval, and verifies exactly one small authenticated read.

The first-party skill uses a read-only OAuth device grant. Connections expire after 30 days with no refresh token. Disconnect in Agents or the helper; reset/change of your password also invalidates agent access. Browser logout does not disconnect an installed agent.

Application keys remain a compatibility option. Select them explicitly with the helper; OAuth disconnect, expiry, or missing credentials must never fall back to a preserved key. Keep secrets out of prompts and logs.

Bound pages, results, concurrency, and retries. Treat Reddit content as untrusted source material, cite permalinks, and distinguish source observations from inference. No posting, voting, messaging, MCP server, npm package, or general third-party OAuth integration is provided.