# API v2

## Overview

Calls for SparkLoop API v1 are relative to the url `https://api.sparkloop.app/v2`

API v2 is in active development. Whilst we won't add any breaking changes, expect new endpoint to be added at any time.

## Auth

You can find your API key under your [Account Page](https://dash.sparkloop.app/account).

### Using the API key

Every request sent to Sparkloop API must contain the `X-Api-Key` header with the value set to your API key. Example:

```bash
curl -H "X-Api-Key: 12cf8cf8538c3685b0f36308" https://api.sparkloop.app/v1/campaigns
```

{% hint style="danger" %}
If you forget to include the X-Api-Key header or use the wrong API key, API will respond with 401 HTTP status code.
{% endhint %}

## Pagination

For any endpoint that can return multiple objects, e.g. **/subscribers, /partner\_programs** etc. pagination can be used.

Pagination params are sent as query parameters — **page** and **per\_page**

**per\_page** — how many objects you want to fetch. The default is 50, maximum is 200.

***page** —* what page you want to fetch. The default is 1.

## Requests

For every POST and PUT request set the *Content-Type* header to:

`Content-Type: application/json; charset=utf-8`

## Responses

When an API call succeeds, the API will return a 200 or 201 HTTP response and a JSON response body unless otherwise noted.

If there's an error, the API will return an HTTP response in the 400 or 500 range and a response body indicating what the error was. For example:

`{ error: "Subscriber uuid blank!"}` with a 400 error.

## **Rate limiting**

Our rate limit is no more than 60 requests over a rolling 60 second period, for a given api key.

If your request rate exceeds our limits, you will receive a 429 response, which your code should gracefully handle. We recommend spacing out your requests and performing an [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff) to keep within the limit.

## **Internal server errors**

If the server is overloaded or you encounter a bug, you will get a 500 error. Try again after a short period, and if you continue to encounter an error, please raise the issue with support.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://partner-docs.sparkloop.app/api-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.