# Overview

In order to use r4nkt, you will need to use our Application Programming Interface, or API. The API allows you to configure your application. This use of the API is optional. The alternative is to use our [Laravel Nova](https://nova.laravel.com/)-based administration panel. The API also allows you to do things like record player activity and get leaderboard data. This is required in order to properly and fully use r4nkt.

Everything you see in the administration panel can be controlled with the API.

There are only a couple of things you will need in order to start using the API:

1. Learn about our API [authentication](/api/authentication.md)
2. Generate an API token

You may now go about using the API. Optionally, we provide a [PHP SDK package](/php-sdk/overview.md) to help get you started.

## API Endpoints

The base for all r4nkt API endpoints is `https://api.r4nkt.com/v1`. The rest of the endpoint is based on the type of resource you're interested in and the method that you would like the API to perform.

Here are the API methods, or verbs, that the r4nkt API uses and a brief description of what they mean:

* `POST`: this indicates that you would like to create a resource.
* `GET`: this indicates that you would like to retrieve information for a specific resource (a specific badge or a specific leaderboard, etc) or a resource type (badges, leaderboards, etc). Requests that use `GET` are considered *idempotent*, which means that no data is modified.
* `PUT`: this indicates that a specific resource is to be updated or modified.
* `DELETE`: this indicates that a specific resource is to be deleted.

To be clear, requests that use the `GET` method will *not* modify your resources while requests that use the other methods will modify them.

## Headers

In addition to the `Authorization` header for [authentication](/api/authentication.md), you should also include the following headers in all requests:

* `Accept: application/json`
* `Content-Type: application/json`

## Response Data

All r4nkt API endpoint responses are JSON-formatted. Here's a sample response from the `/criteria` endpoint, that lists all criteria:

```javascript
{
  "data": [
    {
      "custom_id": "onetedtpvjwcdgplqnjr",
      "name": "afpjycybpmuimrcuuwdj",
      "description": "Repellendus quibusdam consequatur provident.",
      "type": "simple",
      "rule": "gte:sum,1",
      "created_at": "2020-01-18 23:38:07",
      "updated_at": "2020-01-18 23:38:07",
      "custom_action_id": "wodgmtysxugytbmqzbll"
    },
    {
      "custom_id": "gexbxdctpkpebgmwvkql",
      "name": "ysgrjcpuqmdudrvrjbxe",
      "description": "Id voluptatum nihil tempore.",
      "type": "simple",
      "rule": "gte:sum,1",
      "created_at": "2020-01-18 23:38:07",
      "updated_at": "2020-01-18 23:38:07",
      "custom_action_id": "wodgmtysxugytbmqzbll"
    }
  ]
}
```

Each endpoint returns different data, reflecting the resource type and operation that is being formed. More information on each endpoint can be found in the documentation specific to each endpoint.

## Rate limiting

Our API requests are rate limited. This is done in large part to prevent abuse and ensure service stability. A rate limit sets the maximum number of API calls that can be made in a given period of time.

Currently, we have only one kind of rate limit:

* number of requests per day

The exact limit is determined by the subscription tier to which the call is tied.  That is, when an API request is made, a game ID is passed along.  This game ID indicates a specific game which, in turn, belongs to a specific subscription tier.  This tier determines the actual limit.

## Pagination

Almost every resource index endpoint supports pagination. Our API [expects](https://jsonapi.org/examples/#pagination) you to use the [json:api spec](https://jsonapi.org) for pagination. The default page number is always 1 and the default page size is currently set to 30. The maximum allowable page size is currently set to 100.


---

# 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://docs.r4nkt.com/api/overview.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.