# Skin Shade Detection API

{% hint style="info" %}
**Good to know:** We only offer cloud APIs and our methods are kept up to date automatically with changes to the API. 
{% endhint %}

## Endpoints

### GET /api/generatekey

Generates a new API key. This endpoint is rate-limited to 1 request per month for the free tier.

#### Response

A JSON object containing the generated API key.

```json
{
  "roboKey": "your-api-key"
}
```

### POST /api/skinshade

Detects the skin shade from an image based on the tone and undertones.

{% tabs %}
{% tab title="Parameters" %}

```
x-api-key (header): Your API key.
```

{% code overflow="wrap" %}

```
file (form-data): The image file. Should be of type png, jpg, jpeg, or heic.
```

{% endcode %}
{% endtab %}

{% tab title="Response" %}
A JSON object containing the detected skin shade and tone range.

```json
{
  "skinShade": "#hex-color",
  "toneRange": "tone-range"
}

```

{% endtab %}
{% endtabs %}

### GET /api/skinshade-health

Check the application's health, the AI model, and the database. 

#### Response

A JSON object containing the following fields:

{% code overflow="wrap" %}

```json
- `status`: A string that indicates the overall health of the API. It can be either "healthy" or "unhealthy".
- `details`: A dictionary containing each component's status. The keys are the names of the components ("app", "model", "database"), and the values are strings describing the status of the component.
```

{% endcode %}

#### Status Codes

```json
- `200 OK`: The API is healthy.
- `503 Service Unavailable`: The API is unhealthy.
```

#### Example Response

```json
{
    "status": "healthy",
    "details": {
        "app": "App is running",
        "model": "AI model is loaded",
        "database": "Database is connected"
    }
}
```

{% hint style="info" %}
**Good to know:** The health check endpoint is useful for monitoring the health of the API and quickly identifying any issues with the application, the AI model, or the database.
{% endhint %}

***

## Error Codes

* **403**: Missing or invalid API key.
* **429**: API key exceeded request limit.
* **400**: No file part, selected file, or invalid file type.

## Authentication

To authenticate your requests, include your API key in the `x-api-key` header.

## Request Limit

The `generatekey` endpoint is rate-limited to 1 request per month for the free tier. The `skinshade` endpoint is rate-limited to 100 requests per month per API key for the free tier.

## Acceptable Image Files

The `skinshade` endpoint accepts image files of type png, jpg, jpeg, and heic. The maximum file size is 5MB.