# Endpoints

{% hint style="info" %}
All endpoints require your dsc.gg API token in the Authorization header

You can get an API token at <https://dsc.gg/developers/dashboard>
{% endhint %}

## Response Codes Cheatsheet

These are all the possible response codes and what they mean

| Code                | Status | What this code means                            |
| ------------------- | ------ | ----------------------------------------------- |
| payload\_received   | 200    | The content was successfully returned           |
| rate\_limit         | 429    | You have hit a rate limit                       |
| invalid\_key        | 401    | The API key you provided is invalid or missing  |
| not\_found          | 404    | The content was not found or returned blank     |
| owner\_blacklisted  | 403    | The owner is blacklisted so nothing is returned |
| version\_deprecated | 410    | The version of the API is no longer available   |
| bad\_request        | 400    | Something in the request is not valid           |
| link\_taken         | 400    | The link is not available, it is taken          |
| link\_created       | 201    | Link was created successfully                   |
| owner\_mismatch     | 403    | You are not the owner so you can't do it        |
| link\_updated       | 200    | The link was updated successfully               |
| link\_deleted       | 200    | The link was deleted successfully               |
| whitelist\_only     | 403    | The action is for whitelisted apps only         |

## Get Link

<mark style="color:blue;">`GET`</mark> `https://api.dsc.gg/v2/link/:slug`

This endpoint allows you to get the publicly viewable information regarding the link\
\
Rate limit: 100 requests per 10 seconds\
Whitelist-only: no

#### Path Parameters

| Name | Type   | Description                                          |
| ---- | ------ | ---------------------------------------------------- |
| slug | string | Slug of the link (dsc.gg/example would be "example") |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

{% tabs %}
{% tab title="200 Link successfully retrieved." %}

```
{
    "success": true,
    "code": "payload_received",
    "payload": {
        "id": "the link id",
        "owner": "the link Discord owner id",
        "redirect": "the link redirect",
        "domain": "the link domain",
        "type": "server, bot, or template",
        "created_at": timestamp the link was created,
        "bumped_at": timestamp the link was bumped,
        "unlisted": true or false,
        "disabled": true or false,
        "meta": {
            "title": "the meta title",
            "saying": "the meta saying",
            "description": "the meta description",
            "color": "the meta color",
            "image": "the meta image"
        }
    }
}
```

{% endtab %}
{% endtabs %}

## Create Link

<mark style="color:green;">`POST`</mark> `https://api.dsc.gg/v2/link/:slug`

This endpoint allows you to create a link under the owner of the developer application\
\
Rate limit: 3 requests per 60 seconds\
Whitelist-only: no

#### Path Parameters

| Name | Type   | Description                                          |
| ---- | ------ | ---------------------------------------------------- |
| slug | string | Slug of the link (dsc.gg/example would be "example") |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

#### Request Body

| Name             | Type    | Description                                                                                                 |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| meta.image       | string  | link to the image for the                                                                                   |
| meta.description | string  | description for the embed                                                                                   |
| meta.title       | string  | title for the embed                                                                                         |
| unlisted         | boolean | defaults to False. set to True to make the link unsearchable, and have it not show up on the top links page |
| password         | string  | the password to add to the link.  (don't specify for no password)                                           |
| type             | string  | Either 'server', 'bot', or 'template'                                                                       |
| redirect         | string  | the link to redirect to (must conform to type)                                                              |

{% tabs %}
{% tab title="201 Link was created" %}

```
{
    "success": true,
    "code": "link_created",
    "message": "Link has been created successfully"
}
```

{% endtab %}
{% endtabs %}

## Update Link

<mark style="color:purple;">`PATCH`</mark> `https://api.dsc.gg/v2/link/:slug`

This endpoint allows you to update a link under the owner of the developer application\
\
Rate limit: 8 requests per 10 seconds\
Whitelist-only: no

#### Path Parameters

| Name | Type   | Description                                          |
| ---- | ------ | ---------------------------------------------------- |
| slug | string | Slug of the link (dsc.gg/example would be "example") |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

#### Request Body

| Name             | Type    | Description                                                                                                 |
| ---------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| type             | string  | Either 'server', 'bot' or 'template'                                                                        |
| meta.color       | string  | color for the embed (in hex)                                                                                |
| meta.image       | string  | link to the image for the embed (premium only)                                                              |
| meta.description | string  | description for the embed                                                                                   |
| meta.title       | string  | title for the embed                                                                                         |
| unlisted         | boolean | defaults to False. set to True to make the link unsearchable, and have it not show up on the top links page |
| password         | string  | the password to add to the link.  (don't specify for no password)                                           |
| redirect         | string  | the link to redirect to (must conform to type)                                                              |

{% tabs %}
{% tab title="200 The link was updated" %}

```
{
    "success": true,
    "code": "link_updated",
    "message": "Link has been updated successfully"
}
```

{% endtab %}
{% endtabs %}

## Delete Link

<mark style="color:red;">`DELETE`</mark> `https://api.dsc.gg/v2/link/:slug`

This endpoint allows you to delete a link belonging to the owner of the application\
\
Rate limit: 4 requests per 10 seconds\
Whitelist-only: no

#### Path Parameters

| Name | Type   | Description                                          |
| ---- | ------ | ---------------------------------------------------- |
| slug | string | Slug of the link (dsc.gg/example would be "example") |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

{% tabs %}
{% tab title="200 The link was deleted" %}

```
{
    "success": true,
    "code": "link_deleted",
    "message": "This link has been deleted successfully"
}
```

{% endtab %}
{% endtabs %}

## Get User

<mark style="color:blue;">`GET`</mark> `https://api.dsc.gg/v2/user/:id`

This endpoint allows you to get information on a specified user\
\
Rate limit: 50 requests per 10 seconds\
Whitelist-only: no

#### Path Parameters

| Name | Type   | Description                      |
| ---- | ------ | -------------------------------- |
| id   | string | The Discord user id of the user. |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

{% tabs %}
{% tab title="200 Returns the user " %}

```
{
    "success": true,
    "code": "payload_received",
    "payload": {
        "id": "users ID",
        "verified": true or false,
        "premium": true or false,
        "joined_at": timestamp that the user registered,
        "blacklisted": true or false
    }
}
```

{% endtab %}
{% endtabs %}

## Get Users Links

<mark style="color:blue;">`GET`</mark> `https://api.dsc.gg/v2/user/:id/links`

This endpoint allows you to get an array of a users links\
\
Rate limit: 50 requests per 10 seconds\
Whitelist-only: yes

#### Path Parameters

| Name | Type   | Description                      |
| ---- | ------ | -------------------------------- |
| id   | string | The Discord user id of the user. |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

{% tabs %}
{% tab title="200 Returns the users links" %}

```
{
    "success": true,
    "code": "payload_received",
    "payload": [
        An array of links will be here
        ]
}
```

{% endtab %}
{% endtabs %}

## Get Users Apps

<mark style="color:blue;">`GET`</mark> `https://api.dsc.gg/v2/user/:id/apps`

This endpoint allows you to get a users apps from dsc.gg/developer\
\
Rate limit: 50 requests per 10 seconds\
Whitelist-only: yes

#### Path Parameters

| Name | Type   | Description                      |
| ---- | ------ | -------------------------------- |
| id   | string | The Discord user id of the user. |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

{% tabs %}
{% tab title="200 Returns the users apps " %}

```
{
    "success": true,
    "code": "payload_received",
    "payload": [
        An array of apps will be here
        ]
}
```

{% endtab %}
{% endtabs %}

## Get a Developer App

<mark style="color:blue;">`GET`</mark> `https://api.dsc.gg/v2/app/:id`

This endpoint allows you to get information on an app. **The app API key will only be returned if you own the application. Otherwise only public information will be returned.**\
\
Rate limit: 20 requests per 10 seconds\
Whitelist-only: no

#### Path Parameters

| Name | Type   | Description          |
| ---- | ------ | -------------------- |
| id   | string | The app id to fetch. |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

{% tabs %}
{% tab title="200 Returns the application " %}

```
{
    "success": true,
    "code": "payload_received",
    "payload": {
        "id": "the app id",
        "owner": "the app owner Discord id",
        "created_at": timestamp it was created,
        "verified": true or false (aka. whitelisted),
        "key": "app key - will only return if you own the app"
    }
}
```

{% endtab %}
{% endtabs %}

## Get the Top Links

<mark style="color:blue;">`GET`</mark> `https://api.dsc.gg/v2/top`

This endpoint allows you to search for specific links based on a query\
\
Rate limit: 20 requests per 10 seconds\
Whitelist-only: no

#### Path Parameters

| Name | Type   | Description                                                                        |
| ---- | ------ | ---------------------------------------------------------------------------------- |
| type | string | If you want to limit them to only a specific type. Can be bot, server, or template |

{% tabs %}
{% tab title="200 The top links are returned" %}

```
{
    "success": true,
    "code": "payload_received",
    "payload": [
        an array with all top links will be here
    ]
}
```

{% endtab %}
{% endtabs %}

## Search Links

<mark style="color:blue;">`GET`</mark> `https://api.dsc.gg/v2/search`

This endpoint allows you to search for specific links based on a query\
\
Rate limit: 90 requests per 10 seconds\
Whitelist-only: yes

#### Path Parameters

| Name  | Type   | Description                                                                       |
| ----- | ------ | --------------------------------------------------------------------------------- |
| limit | string | If you want to limit the # of results. i.e: ?limit=10 for max of 10 results       |
| type  | string | If you want to narrow results, include ?type=bot, ?type=server, or ?type=template |
| q     | string | The query to search                                                               |

#### Headers

| Name          | Type   | Description                                                           |
| ------------- | ------ | --------------------------------------------------------------------- |
| Authorization | string | API token associated with your account (obtained at dsc.gg/developer) |

{% tabs %}
{% tab title="200 Returns the search results" %}

```
{
    "success": true,
    "code": "payload_received",
    "payload": [
        an array of all the returned link results
    ]
}
```

{% endtab %}
{% endtabs %}