> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pullrule.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

The PullRule API is organised around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has
predicatable resource-oriented URLs, accepts [form-encoded](https://en.wikipedia.org/wiki/POST_\(HTTP\)#Use_for_submitting_web_forms)
request bodies, returns [JSON-encoded](http://www.json.org/) responses, and uses standard HTTP response codes,
authentication, and verbs.

## Authentication

The PullRule API uses \[Bearer tokens] to authenticate requests. Go to [Settings > Administration > API](https://pullrule.com/app/settings/api) to view and manage your API keys.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly
accessible areas such as GitHub, client-side code, and so forth. If you believe your API key has been compromised, you
should revoke it immediately.

All API requests must be made over [HTTPS](http://en.wikipedia.org/wiki/HTTP_Secure). Calls made over plain HTTP
will fail. API requests without authentication will also fail.

## Responses

The PullRule API will always respond with a HTTP status code. The code informs you about the outcome of the API call.
The API can return the following HTTP status codes:

| Status Code               | Description                                                                       |
| ------------------------- | --------------------------------------------------------------------------------- |
| 200 OK                    | The request was successful.                                                       |
| 201 Created               | The resource was successfully created.                                            |
| 204 No Content            | The resource was successfully deleted.                                            |
| 400 Bad Request           | The request was invalid or cannot be otherwise served.                            |
| 401 Unauthorized          | Authentication credentials were missing or incorrect.                             |
| 403 Forbidden             | The request is understood, but it has been refused or access is not allowed.      |
| 404 Not Found             | The URI requested is invalid or the resource does not exist.                      |
| 422 Unprocessable Entity  | The request was well-formed but was unable to be followed due to semantic errors. |
| 429 Too Many Requests     | The request was rate limited.                                                     |
| 500 Internal Server Error | An error occurred on the server.                                                  |

After reading the HTTP status code, you can determine if the request body should be parsed. The body is in JSON format.
Most non-success error codes provide extra details in the body. Make sure to process this body, because they will
provide valuable information while debugging your application.

## Pagination

Most API endpoints return a paginated list of resources. The default page size is 20 items, and you can specify the
`page[size]` query parameter to change the page size. The maximum page size is 100 items.

The API uses cursor-based pagination. The response will include a `links` object with `next` and `prev` links to navigate
through the pages. The `next` link will be `null` if there are no more pages.

## Rate Limiting

The PullRule API uses rate limiting to ensure fair usage and prevent abuse. The default rate limit is 60 requests per
minute per authenticated request. If you exceed the rate limit, you will receive a `429 Too Many Requests` response with a
`Retry-After` header indicating when you can retry the request.