# Horses

## User actions

## Get horse information

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

Retrieves information about a horse

#### Query Parameters

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| horse\_number<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> | String | application/json |

{% tabs %}
{% tab title="200 " %}
```json
{
    "name": "Guro Legge",
    "image": "https://d19z9f49qtk8r2.cloudfront.net/120_0.png",
    "external_url": "https://derace.com/horse/120",
    "number": 120,
    "gender": "Stallion",
    "height": 16.5,
    "weight": 529,
    "level": 1,
    "appearance": [
        {
            "trait_type": "body_type",
            "value": "Medium"
        },
        {
            "trait_type": "base_color",
            "value": "Charcoal"
        },
        {
            "trait_type": "base_pattern_type",
            "value": "Regular"
        },
        {
            "trait_type": "base_pattern_color",
            "value": "White"
        },
        {
            "trait_type": "muzzle_pattern_type",
            "value": "Regular"
        },
        {
            "trait_type": "muzzle_pattern_color",
            "value": "Dawn"
        },
        {
            "trait_type": "ear_type",
            "value": "Regular"
        },
        {
            "trait_type": "eye_type",
            "value": "Mocha"
        },
        {
            "trait_type": "mane_type",
            "value": "Both sides"
        },
        {
            "trait_type": "mane_color",
            "value": "Coffee"
        },
        {
            "trait_type": "tail_type",
            "value": "Half-braided"
        },
        {
            "trait_type": "tail_color",
            "value": "Coffee"
        },
        {
            "trait_type": "hoof_color",
            "value": "Black"
        },
        {
            "trait_type": "head_type",
            "value": "Regular"
        },
        {
            "trait_type": "head_pattern_type",
            "value": "Drop"
        },
        {
            "trait_type": "head_pattern_color",
            "value": "White"
        },
        {
            "trait_type": "leg_pattern_type",
            "value": "Stock"
        },
        {
            "trait_type": "leg_pattern_color",
            "value": "White"
        },
        {
            "trait_type": "thigh_mark",
            "value": "None"
        }
    ],
    "breeding_cooldown": null,
    "breed": "Thoroughbred",
    "generation": 0,
    "tier": "Beta"
}
```
{% endtab %}

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

{% endtab %}
{% endtabs %}

## Get horse information

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

Retrieves list of horses that belong to user whose allowance is used.

#### 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    |
| ------------------------------------------- | ------ | -------------- |
| user\_key<mark style="color:red;">\*</mark> | String | User's API key |

{% tabs %}
{% tab title="200 " %}
```json
[
    {
        "name": "Ben Winance",
        "image": "https://d19z9f49qtk8r2.cloudfront.net/120_0.png",
        "external_url": "https://derace.com/horse/120",
        "number": 120,
        "gender": "Stallion",
        "height": 16.5,
        "weight": 529,
        "level": 1,
        "appearance": [
            {
                "trait_type": "body_type",
                "value": "Medium"
            },
            {
                "trait_type": "base_color",
                "value": "Charcoal"
            },
            {
                "trait_type": "base_pattern_type",
                "value": "Regular"
            },
            {
                "trait_type": "base_pattern_color",
                "value": "White"
            },
            {
                "trait_type": "muzzle_pattern_type",
                "value": "Regular"
            },
            {
                "trait_type": "muzzle_pattern_color",
                "value": "Dawn"
            },
            {
                "trait_type": "ear_type",
                "value": "Regular"
            },
            {
                "trait_type": "eye_type",
                "value": "Mocha"
            },
            {
                "trait_type": "mane_type",
                "value": "Both sides"
            },
            {
                "trait_type": "mane_color",
                "value": "Coffee"
            },
            {
                "trait_type": "tail_type",
                "value": "Half-braided"
            },
            {
                "trait_type": "tail_color",
                "value": "Coffee"
            },
            {
                "trait_type": "hoof_color",
                "value": "Black"
            },
            {
                "trait_type": "head_type",
                "value": "Regular"
            },
            {
                "trait_type": "head_pattern_type",
                "value": "Drop"
            },
            {
                "trait_type": "head_pattern_color",
                "value": "White"
            },
            {
                "trait_type": "leg_pattern_type",
                "value": "Stock"
            },
            {
                "trait_type": "leg_pattern_color",
                "value": "White"
            },
            {
                "trait_type": "thigh_mark",
                "value": "None"
            }
        ],
        "breeding_cooldown": "2022-03-29T14:48:24.547Z",
        "breed": "Thoroughbred",
        "generation": 0,
        "tier": "Beta"
    },
]
```
{% endtab %}

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

{% endtab %}
{% endtabs %}

## Get horse's missions

<mark style="color:blue;">`GET`</mark> `https://api.derace.com/api/v1/horses/missions/:horse_number`

#### Query Parameters

| Name                                            | Type   | Description |
| ----------------------------------------------- | ------ | ----------- |
| horse\_number<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> | String | application/json |

{% tabs %}
{% tab title="200 " %}
```json
{
    "number": 120,
    "missions": [
        {
            "type": "monthly",
            "mission": "all_weekly",
            "count": 4,
            "reward_xp": 3000,
            "reward_sugar": 300,
            "progress": [],
            "processed": false,
            "completed": false,
            "name": "Complete all weekly tasks"
        },
        {
            "progress": [],
            "type": "monthly",
            "mission": "take_prize_place_in_x_races",
            "count": 23,
            "place": 3,
            "reward_xp": 4059,
            "reward_sugar": 399,
            "processed": false,
            "completed": false,
            "name": "Take X prize places on any hippodrome"
        },
        {
            "progress": [],
            "type": "monthly",
            "mission": "run_x_races",
            "count": 87,
            "reward_xp": 3034,
            "reward_sugar": 320,
            "processed": false,
            "completed": false,
            "name": "Run X races"
        },
        {
            "type": "weekly",
            "mission": "all_daily",
            "count": 5,
            "reward_xp": 750,
            "reward_sugar": 75,
            "progress": [],
            "processed": false,
            "completed": false,
            "name": "Complete all daily tasks"
        },
        {
            "progress": [],
            "type": "weekly",
            "mission": "run_x_races",
            "count": 37,
            "reward_xp": 842,
            "reward_sugar": 62,
            "processed": false,
            "completed": false,
            "name": "Run X races"
        },
        {
            "progress": [],
            "type": "weekly",
            "mission": "run_all_on_z_hippodrome",
            "count": 6,
            "hippodrome": 0,
            "reward_xp": 815,
            "reward_sugar": 81,
            "processed": false,
            "completed": false,
            "name": "Run every furlong race on X surface"
        },
        {
            "progress": [],
            "type": "daily",
            "mission": "run_x_races",
            "count": 10,
            "reward_xp": 206,
            "reward_sugar": 20,
            "processed": false,
            "completed": false,
            "name": "Run X races"
        },
        {
            "progress": [],
            "type": "daily",
            "mission": "run_x_furlong_race",
            "count": 1,
            "reward_xp": 116,
            "reward_sugar": 11,
            "furlongs": 12,
            "processed": false,
            "completed": false,
            "name": "Run single X furlongs race"
        },
        {
            "progress": [],
            "type": "daily",
            "mission": "run_x_races_y_furlong",
            "count": 5,
            "furlongs": 4,
            "reward_xp": 136,
            "reward_sugar": 14,
            "processed": false,
            "completed": false,
            "name": "Run X races of Y furlongs"
        }
    ]
}
```
{% endtab %}

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

{% endtab %}
{% endtabs %}

## Get horses that are available for breeding

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



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

{% tabs %}
{% tab title="200 " %}
```json
[
    {
        "name": "Stromald Ivory",
        "number": 2570,
        "gender": "Stallion",
        "wins_first_count": 3,
        "wins_second_count": 7,
        "wins_third_count": 6,
        "total_race_count": 60,
        "price": 60,
        "generation": 0,
        "tier": "Omega"
    },
    ...
]
```
{% endtab %}

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

{% endtab %}
{% endtabs %}

