# Races

## Race actions

## Get list of finished races.

<mark style="color:blue;">`GET`</mark> `https://api.derace.com/api/v2/races/results`

Retrieves a list of latest finished races. Returns 10 results

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| x-api-key<mark style="color:red;">\*</mark>    | String | App's API key    |
| content-type<mark style="color:red;">\*</mark> | String | application/json |

#### Request Body

| Name              | Type   | Description                                                                                                                      |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------- |
| tier              | Number | Tier ID of requested races. **Defaults to 5 (Omega)**                                                                            |
| start\_time\_from | Number | Start time to look for races from. Results will not include race if it starts at this exact time. **Defaults to time of search** |

{% tabs %}
{% tab title="200 Data returned" %}
```javascript
[
    {
        "main_race_id": 129864,
        "start_time": 1669047660000,
        "registration_deadline": 1669047360000,
        "type": "best_time", /* alternatively "worst_time" */
        "length": 6,
        "v2": true,
        "no_equipment": false,
        "entry_fee": 2000000000000000000,
        "prizes": [
            50,
            30,
            15
        ],
        "tier": "Omega",
        "info": {
            "name": "Omega Race #129864",
            "hippodrome_type": "sakura",
            "hippodrome_name": "Sakura Path",
            "turf": "Turf"
        },
        "places": 12,
        "min_level": 1,
        "max_level": 80,
        "participants": [
            {
                "number": 821,
                "total": 72646,
                "lane": 1
            },
            {
                "number": 831,
                "total": 73699,
                "lane": 2
            },
            {
                "number": 817,
                "total": 73919,
                "lane": 3
            },
            {
                "number": 839,
                "total": 76073,
                "lane": 4
            },
            {
                "number": 844,
                "total": 74200,
                "lane": 5
            },
            {
                "number": 840,
                "total": 75379,
                "lane": 6
            }
        ],
        "status": "",
        "final_order": [
            0,
            1,
            2,
            4,
            5,
            3
        ],
        "winners": [
            0,
            1,
            2
        ]
    }
]
```
{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}
{% endtabs %}

## Get list of open races.

<mark style="color:blue;">`GET`</mark> `https://api.derace.com/api/v1/races/open`

Retrieves a list of all currently open races.

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| x-api-key<mark style="color:red;">\*</mark>    | String | App's API key    |
| content-type<mark style="color:red;">\*</mark> |        | application/json |

{% tabs %}
{% tab title="200 Data returned" %}
```javascript
[
    {
        "_id": "pAbgW33LsoqL9sFQu",
        "main_race_id": 131624,
        "start_time": 1669737900000,
        "registration_deadline": 1669737600000,
        "type": "best_time", /* alternatively "worst_time" */
        "length": 6,
        "v2": true,
        "no_equipment": false,
        "entry_fee": 30000000000000000000,
        "prizes": [
            50,
            30,
            15
        ],
        "tier": "Omega",
        "info": {
            "name": "High Roller Race #131624",
            "hippodrome_type": "sakura",
            "hippodrome_name": "Sakura Path",
            "turf": "Turf"
        },
        "places": 12,
        "participants": [],
        "status": "In progress",
        "min_level": 1,
        "max_level": 80,
    }
]
```
{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}
{% endtabs %}

## Get information about a specific race

<mark style="color:blue;">`GET`</mark> `https://api.derace.com/api/v1/races/:raceId`

Pass race id and retrieve information about that race

#### Query Parameters

| Name                                     | Type   | Description |
| ---------------------------------------- | ------ | ----------- |
| raceId<mark style="color:red;">\*</mark> | Number |             |

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| x-api-key<mark style="color:red;">\*</mark>    | String | App's API key    |
| content-type<mark style="color:red;">\*</mark> |        | application/json |

{% tabs %}
{% tab title="200 Data returned" %}
```javascript
[
    {
        "_id": "pAbgW33LsoqL9sFQu",
        "main_race_id": 131624,
        "start_time": 1669737900000,
        "registration_deadline": 1669737600000,
        "type": "best_time", /* alternatively "worst_time" */
        "length": 6,
        "v2": true,
        "no_equipment": false,
        "entry_fee": 30000000000000000000,
        "prizes": [
            50,
            30,
            15
        ],
        "tier": "Omega",
        "info": {
            "name": "High Roller Race #131624",
            "hippodrome_type": "sakura",
            "hippodrome_name": "Sakura Path",
            "turf": "Turf"
        },
        "places": 12,
        "participants": [],
        "status": "In progress",
        "min_level": 1,
        "max_level": 80,
    }
]
```
{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}
{% endtabs %}

## Register horse to a race

<mark style="color:green;">`POST`</mark> `https://api.derace.com/api/v1/races/register`

Attempts to register a selected horse into the selected race

#### Headers

| Name                                           | Type   | Description      |
| ---------------------------------------------- | ------ | ---------------- |
| x-api-key<mark style="color:red;">\*</mark>    | String | App's API key    |
| content-type<mark style="color:red;">\*</mark> | String | application/json |

#### Request Body

| Name                                             | Type   | Description                         |
| ------------------------------------------------ | ------ | ----------------------------------- |
| horse\_number<mark style="color:red;">\*</mark>  | Number | Number of horse asset               |
| user\_key<mark style="color:red;">\*</mark>      | String | API Key of the user (horse owner)   |
| main\_race\_id<mark style="color:red;">\*</mark> | Number | Main race id of the designated race |

{% tabs %}
{% tab title="200 Registration successful" %}

{% endtab %}

{% tab title="401 Permission denied" %}

{% endtab %}

{% tab title="403: Forbidden Access forbidden. Returned if user_key is invalid" %}

{% endtab %}

{% tab title="400: Bad Request Request errored out with an error code" %}
```
- user_withdraw_lock - user's account is on a participation lock;
- invalid_horse - horse cannot be found;
- horse_on_cooldown - horse on race cooldown
- horse_already_registered - horse already registered in another pending race;
- race_invalid - race cannot be found;
- insufficient_balance - user does not have enough to participate in this race;
- race_full - race full;
```
{% endtab %}
{% endtabs %}

