# ClickMagick API

> ClickMagick is an ad tracking and conversion attribution platform. Its REST API lets you automate work in your ClickMagick account: managing Projects, Smart Links, Rotators, Custom Domains and Groups, retrieving stats, and reading conversion logs.

**Before writing any code, fetch and read the complete API reference at https://api.clickmagick.com/docs/openapi.yaml (OpenAPI 3.0). It defines every endpoint, parameter and response. This file covers only what that reference doesn't.**

**If you write code that calls this API, build the rules in this file (error checking, polling and rate limiting) into that code.**

## Getting started

- To create an API key, log in to ClickMagick, select Integrations from the account menu, click API in the upper-right corner, then click Generate API Key.

## Checking for errors

Most errors are returned with HTTP status 200, not a 4xx code. Always check the `status` field of the response body, which is `OK` or `Error`.

Some errors use a non-2xx status instead, such as rate limiting (429, see below), an unknown endpoint (404) or a server error (5xx). Their body may not include `status`.

## Stats reports

Stats are generated in the background. A request to create a stats report, such as `POST /campaigns/projects/{project_id}/stats`, returns a report `id` and a `url`. Poll that `url` to get the results:

- `202` means the report is still being generated. The body shows its progress.
- `200` means the report is ready. The body contains the stats.

Most reports are ready in well under a second. Poll on this schedule:

1. Wait 250 milliseconds after creating the report, then check it.
2. If it isn't ready, wait 500 milliseconds and check again.
3. After that, check once a second.
4. If it still isn't ready after 30 seconds, check every 5 seconds.

Don't create the same report again while you wait. Sending the same request again returns the same report.

## Rate limiting

Rate limiting is dynamic. It's based on how much work your requests cause on our servers over the past 5 minutes, not on a fixed number of requests per second.

- Most requests, such as creating a Smart Link, will never be rate limited.
- Requests that do a lot of work are the ones that get limited: retrieving conversion data, generating stats, and resetting or deleting lots of data. Fetching weeks or months of conversion data in a short time will almost certainly be rate limited.
- If you need conversion logs regularly, fetch small amounts often (for example every hour or every day) rather than large ranges at once.
- Send requests one at a time rather than in parallel.
- When rate limited you get HTTP status 429. Wait the number of seconds in the `Retry-After` header before sending any more requests, and never assume a fixed value. If `Retry-After` is missing or empty, wait 60 seconds. The body of a 429 may not be JSON.

## Docs

- [OpenAPI spec](https://api.clickmagick.com/docs/openapi.yaml): the complete machine-readable API reference (OpenAPI 3.0, YAML)
- [API documentation](https://api.clickmagick.com/docs): the same reference as a human-readable web page