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

# REST API

> Send answers from your server with a secret key.

If your signup form already asks "how did you hear about us?", send the answer from your signup handler. Classification happens in the background, usually within seconds; the call returns `202` right away.

> [!NOTE]
>
> The REST API needs the Growth plan or higher. The 14-day signup trial includes it.

## 1. Create a secret key

In **Settings → API keys**, create a key of type **Secret**. It's shown once, so store it in your secrets manager. Secret keys (`sk_live_…`) belong on your server only.

## 2. Send the answer

```bash curl theme={null}
curl https://api.rumorly.io/v1/responses \
  -H "Authorization: Bearer $RUMORLY_SECRET_KEY" \
  -H "Idempotency-Key: signup_8f2c91" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "emily@acmeanalytics.com",
    "external_id": "8f2c91",
    "name": "Emily Carter",
    "answer": "Heard Jake on Lenny'\''s Podcast",
    "metadata": { "utm_source": "podcast" }
  }'
```

```javascript JavaScript theme={null}
await fetch("https://api.rumorly.io/v1/responses", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.RUMORLY_SECRET_KEY}`,
    "Idempotency-Key": `signup_${user.id}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: user.email,
    external_id: String(user.id),
    name: user.name,
    answer: form.howDidYouHear,
    metadata: { utm_source: signup.utmSource },
  }),
});
```

```json Response (202) theme={null}
{ "id": "3f6c0a2e-5d1b-4f7a-9c2e-0b8d4e6a1f23", "status": "pending" }
```

The example values above are illustrative.

* **`answer`** is required (1–2,000 characters). Everything else is optional, but send `email` or `external_id` so the answer can be matched to revenue.
* **`Idempotency-Key`**: send one per answer (your signup id works). A retry with the same key returns the original response with `200` instead of creating a second one.
* **`answered_at`**: an ISO 8601 timestamp if the answer is older than the request (for backfills).
* **`metadata`**: UTM parameters, `referrer` and `landing_page` feed the first-touch comparison; any other string, number or boolean keys are stored as-is.

## 3. Read the results

`GET /v1/responses` lists answers newest first with their classification and the customer's monthly revenue. To sync results into your own systems, pass `updated_since` and follow `next_cursor`:

```bash theme={null}
curl "https://api.rumorly.io/v1/responses?updated_since=2026-10-01T00:00:00Z&limit=100" \
  -H "Authorization: Bearer $RUMORLY_SECRET_KEY"
```

Correct a classification with `PATCH /v1/responses/{id}`. See the [API reference](/api-reference/overview) for every field and error.


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