# Introduction

Get to know the dsc.gg API! If you need any help, refer to our dedicated #api-discussion channel in our support server.

## Important Notes

{% hint style="info" %}
All endpoints require your dsc.gg API token in the Authorization header. More on that under the "Endpoints" section.
{% endhint %}

## API Wrappers:

**Javascript wrapper:** [**https://npm.im/dsc.js**](https://npm.im/dsc.js)\
\
**Python wrapper:** [**https://pypi.org/project/dsc.py**](https://pypi.org/project/dsc.py)\
\
**Java wrapper:** [**https://github.com/dsc-gg/dsc.java**](https://github.com/dsc-gg/dsc.java)

## FAQ

**Where can I find the API endpoints?** \
Find them here: [https://docs.dsc.gg/endpoints](https://docs.dsc.gg/endpoints-v2)

**I got a 429! What can I do?** \
This means you have hit the rate limit. If you need an extended rate limit, refer to our whitelisting program.

**Are there any requirements for whitelisting?** \
We don't have a set "requirement" of anything to get whitelisted. We will whitelist you if you provide a valid reason why you need to get whitelisted, if you follow all our guidelines, and if your application is fairly large (smaller ones shouldn't need whitelisting)

**How do I get whitelisted?** \
You can apply by pinging a mod in #support or #api-discussion for instructions on what you need to provide to us. We won't be whitelisting random applications without a good reason why whitelisting is needed.

**I can't access the endpoint \[Insert endpoint here]!** \
Chances are this means the endpoint is for whitelisted apps only. Refer to the "How do I get whitelisted?" question for more information on this.

**\[Insert something] doesn't make sense!** \
If you need help with something, refer to our quick start guide or ask for help in #api-discussion.

**I need help with something not listed here!** \
For other questions or general discussion, use #api-discussion

## **Getting Started**

Step 1: Registering your application\
\
**Step 1: Registering your application** \
1\) Head over to <https://dsc.gg/developers/dashboard> and click on the "Create New" button \
2\) Fill out all the required fields with information on the app you want to use the dsc.gg API with \
3\) Hit "Create App" and make note of the generated API key

**Step 2: Finding your library** \
We have a few options for API libraries you can use. You can choose one of the below or use the raw API.

Javascript Library: Dsc.js - <https://npm.im/dsc.js> \
Python Library: Dsc.py - <https://pypi.org/project/dsc.py> \
Java Library: Dsc.java - <https://github.com/dsc-gg/dsc.java>

**Step 3: Start developing** \
Depending on the API library you choose, you can learn how to use it via the corresponding docs. \
*If you are directly using our API, you can continue with the raw endpoints at:* <https://docs.dsc.gg/endpoints>.


# Endpoints

All the official API endpoints for the dsc.gg API

{% 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 %}


# Widgets

All-new widgets to embed your dsc.gg link along with its stats directlyon your website page!

There are 2 methods to using the dsc.gg widget on your site. **You can use whichever you prefer, although we recommend using the Javascript widget to collect analytics, keep everything automatically updated and to utilize a cleaner implementation.**

### Method 1: Using the Javascript Widget (Recommended)

The first thing you should do when using the JS widget is include the required script on any pages you want to use the widget on. **Be sure to include the "defer" in the script tag to ensure the script only loads when the page is ready.**

```markup
<script src="https://api.dsc.gg/widget.js" defer></script>
```

Once you have added that, you will be able to implement the simple HTML tag as shown below to display your widget:

```markup
<dscgg-widget link="link_ending" type="widget_size"></dscgg-widget>
```

You can do this as many times as you want, wherever you want your widget to show up. Be sure to replace `link_ending` with the ending of your link (i.e: if your link was dsc.gg/example, the ending would be "example"). Also, replace `widget_size` with the size you want. Currently, we offer the sizes "small" and "large". \
\
\
Once that is done, refresh your page and the widget should appear as shown below:

###

### Method 2: Manually loading the SVG widget

This method is intended for locations where you can not load an external script, or do not want to do so.

#### Webpage Implementation

You should use this method if you are working with a webpage where you can load an \<img> tag. Be sure to replace `:link_ending` in the img tag and link tag to your link ending (i.e: if your link was dsc.gg/example, the ending would be "example").

```markup
<a href="https://dsc.gg/:link_ending"><img src="https://api.dsc.gg/v2/widget/:link_ending" /></a>
```

#### Implementation for non-webpages

You should use this method if you are only looking to load the image url, and not use it as a page element. (i.e: in a Discord bot embed). Be sure to replace `:link_ending` in the img tag and link tag to your link ending (i.e: if your link was dsc.gg/example, the ending would be "example").&#x20;

```
https://api.dsc.gg/v2/widget/:link_ending
```

### Widget References

#### Type/Design choices

We offer 2 designs for how your widget will look, "small" and "large". You can get an idea of what they look like below:

![Example of the small widget style](/files/-MS92Vu_tAtEt4dexgvu)

![Example of the large widge style](/files/-MS92sRyIhOkkj8lhtUX)

#### Additional query parameters

You can include additional params to the link image query to hide certain elements. Currently, we support adding `?hide_creation=true` to hide the "Created On" field. This only applies to the large widget type. For example, you would do the following:

```
https://api.dsc.gg/v2/widget/:link_ending?hide_creation=true
```

And thats it! The widget will now hide the "Created On" field.