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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dsc.gg/endpoints.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.