# 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/settings/integrations).

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