API

Developers

Build against the NewsletterIdea API with a clear path from API key setup to run creation, findings retrieval, webhooks, usage, and error recovery.

Last updated June 29, 2026

Start here

Use Scalar for endpoint details and this page for the operating path. Create an API key in the customer API key page, send it with the X-Api-Key header, and store the key securely because it is displayed only once.

  1. 1. Create a keyLog in, create a scoped API key, and copy it once.
  2. 2. Make a safe requestUse idempotency keys for retry-safe POST workflows.
  3. 3. Handle outcomesPlan for Problem Details, rate limits, webhooks, and async run states.
Open API docs Create API key OpenAPI JSON Endpoint catalog Developer metadata Findings schema Error reference Webhook guide

Authentication, idempotency, and retries

Send X-Api-Key on authenticated requests. Send Idempotency-Key on retry-safe POST workflows such as run creation, purchases, withdrawals, and webhook changes. Reuse the same idempotency key only for the same logical operation and request body.

using var request = new HttpRequestMessage(HttpMethod.Get, "https://newsletteridea.com/v1/account");
request.Headers.Add("X-Api-Key", "YOUR_API_KEY");
using var response = await httpClient.SendAsync(request, cancellationToken).ConfigureAwait(false);
curl https://newsletteridea.com/v1/usage \
  -H "X-Api-Key: YOUR_API_KEY"

Run lifecycle and SDK readiness

Typical integrations create a run, poll /v1/runs/{id}, download /v1/runs/{id}/findings, validate against /v1/findings-schema, and request a dossier from /v1/runs/{id}/dossier. API clients should handle Problem Details, 401, 403, 404, 409, 429, 503, and retryable 5xx responses.

SDK generation should use /openapi/v1.json and the endpoint catalogue so auth, idempotency, async-run, usage, account metadata, webhooks, and withdrawal endpoints stay aligned.

Webhook setup and signing guidance lives at /developers/webhooks. Error guidance lives at /developers/errors.

Create API key Manage webhooks