API v3

API v3

SparkLoop's v3 API is organized around your publications: most resources are scoped to a publication (/v3/publications/:publication_uuid/...), while a few — your account, payouts, and webhooks — are scoped to the whole account.

The v3 API returns richer, self-describing payloads. Related objects are referenced by UUID and can be inlined on demand with expand, and most performance figures are available inline via expand=stats.

Building with an LLM or AI agent? A plain-text index of the entire v3 API — every endpoint with a one-line description and a direct link — is published at api.sparkloop.app/llms.txt, following the llms.txt convention. Point your tooling there for a compact map of the whole API surface.

Base URL

https://api.sparkloop.app/v3

Authentication

Send your API key in the x-api-key header on every request. All requests act as the team that owns the key.

curl https://api.sparkloop.app/v3/account \
  -H "x-api-key: YOUR_API_KEY"

Status	Body	When
401	{ "error": "API key is missing!" }	No x-api-key header.
401	{ "error": "Account not found!" }	Unknown API key.
401	{ "error": "API key is invalid!" }	Invalidated API key.

Pagination

List endpoints are paginated and return a meta block alongside the results.

Parameter	In	Type	Description
page	query	integer	Page number. Defaults to 1.
per_page	query	integer	Results per page. Defaults to 50, capped at 200.

The meta block, where total_<resource> is named after the listed resource (e.g. total_publications, total_surveys):

{
  "meta": {
    "per_page": 50,
    "page": 1,
    "total_pages": 4,
    "total_<resource>": 187
  }
}

Expanding objects

Related objects are returned as a UUID string by default. Pass expand with a comma-separated list of fields to inline the full object instead.

Parameter	In	Type	Description
expand	query	string	Comma-separated fields to expand, e.g. expand=recommended_publication,stats.

Each endpoint lists the fields it supports expanding.

Stats & date range

Performance metrics are opt-in via expand=stats. When requested, they cover a date window you control:

Parameter	In	Type	Description
from	query	string	Start date (YYYY-MM-DD). Defaults to 30 days ago.
to	query	string	End date (YYYY-MM-DD). Defaults to today.

from/to only narrow the stats window, so they require expand=stats — passing them without it returns 400.

Rate limits

Each API key may make 120 requests per minute. The limit is shared by every request sent with the same key, whatever the endpoint.

Once you go over it, requests return 429 until the window resets. Successful responses carry no rate-limit headers; the 429 response does:

Header	Meaning
ratelimit-limit	Requests allowed per minute (120).
ratelimit-remaining	Always 0 on a 429.
ratelimit-reset	Unix timestamp (seconds) at which the window resets.
retry-after	Seconds to wait before retrying.

The 429 body is plain text rather than the JSON error shape used elsewhere:

You have been rate limited. Please try again in 60 seconds.

Wait for retry-after seconds before retrying, and spread requests out instead of sending them in bursts.

Errors

Every error except 429 uses the same shape:

{ "error": "Resource not found." }

Status	Meaning
400	Bad request — an unsupported or malformed parameter.
401	Authentication failed — missing, unknown, or invalid API key.
404	The resource doesn't exist, or isn't visible to your team.
422	The request was understood but couldn't be processed.
429	Rate limit exceeded — wait retry-after seconds, then retry. See Rate limits.