> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rumorly.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Base URL, authentication, idempotency, pagination and errors.

The Rumorly API is plain JSON over HTTPS. Every page in this tab has a playground: paste a secret key and send a real request.

## Base URL

```text theme={null}
https://api.rumorly.io
```

When running Rumorly locally, the API listens on `http://localhost:4100`; pick it from the server menu in the playground.

## Authentication

Send a key as a bearer token:

```bash theme={null}
curl https://api.rumorly.io/v1/health \
  -H "Authorization: Bearer sk_live_…"
```

| Key | Prefix | Where | Can |
| - | - | - | - |
| Secret | `sk_live_` / `sk_test_` | Your server only | Every `/v1` endpoint |
| Publishable | `pk_live_` / `pk_test_` | The browser (the [snippet](/collect/snippet)) | `POST /v1/responses` and `GET /v1/widget/config`, only from allow-listed origins |

Create and revoke keys in **Settings → API keys**. A key is shown once, when you create it; Rumorly stores only a hash. Revoking a key takes effect on the next request. Key-authenticated calls need the Growth plan or higher (the signup trial includes it), except erasure, which works on every plan.

## Conventions

* **JSON is snake\_case**, in requests and responses.
* **Money** is an integer in minor units in your reporting currency: `mrr_cents: 190000` is \$1,900.00. `currency` says which.
* **Timestamps** are ISO 8601 in UTC. Date-only query parameters (`from`, `to`) are `YYYY-MM-DD`.
* **Ids** are UUIDs. An id from another workspace returns `404`, never `403`.

## Idempotency

`POST /v1/responses` accepts an `Idempotency-Key` header (up to 200 characters). The first request with a key creates the response and returns `202`; any later request with the same key returns that same response with `200` and creates nothing. Use something stable per answer, such as your signup id.

## Pagination

`GET /v1/responses` returns `{ "data": [...], "next_cursor": "…" }`. Pass `next_cursor` back as `cursor` until it's `null`. `limit` is 1–200 (default 50). With `updated_since`, results are ordered oldest change first, which makes incremental syncs easy.

## Rate limits

Publishable keys can submit 10 responses in a burst, then one every 6 seconds, per key and visitor IP. Past that, you get `429` with a `Retry-After` header. Secret keys aren't rate-limited; they're bounded by your monthly allowance.

## Errors

Errors are JSON with a human-readable `error`, and a machine-readable `code` where one helps:

```json theme={null}
{
  "error": "invalid body",
  "issues": [{ "path": ["answer"], "message": "String must contain at least 1 character(s)" }]
}
```

| Status | When | `code` |
| - | - | - |
| `400` | The body or query failed validation; `issues` lists each field. Also an unknown `channel` or entity on a correction. | `unknown_channel`, `unknown_entity` |
| `401` | Missing, invalid or revoked key. | |
| `402` | This month's allowance is used up. | `quota_exceeded` |
| `402` | Your plan doesn't include this; the body adds `feature` and `required_plan`. | `plan_required` |
| `403` | A publishable key tried to read, or its `Origin` isn't allow-listed. | |
| `404` | No such response or channel in your workspace. | |
| `429` | A publishable key went over its rate limit. | `rate_limited` |

## OpenAPI

The machine-readable spec is served at [`/v1/openapi.json`](https://api.rumorly.io/v1/openapi.json). It's generated from the same schemas the API validates with.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.