# Guild Users

{% hint style="info" %}
**This endpoint requires an API key**. If you don't have one, you can get one by using the bot's slash command <mark style="color:purple;">`/apikey generate`</mark>
{% endhint %}

{% hint style="info" %}
**The API key owner must have the&#x20;**<mark style="color:purple;">**`Administrator`**</mark>**&#x20;permission** in the selected guild to be able to get its data
{% endhint %}

## Get guild's user leveling data

<mark style="color:blue;">`GET`</mark> `https://api.stefdp.com/gattinhosBot/guilds/{guild_id}/users/{user_id}`

#### Path Parameters

| Name                                        | Type   | Description         |
| ------------------------------------------- | ------ | ------------------- |
| guild\_id<mark style="color:red;">\*</mark> | String | The ID of the guild |
| user\_id                                    | String | The ID of the user  |

#### Headers

| Name                                            | Type   | Description        |
| ----------------------------------------------- | ------ | ------------------ |
| Authorization<mark style="color:red;">\*</mark> | String | `Bearer <API_KEY>` |

{% tabs %}
{% tab title="200: OK When no user is given" %}
Returns an array with the objects of each user who sent atleast one message after the leveling system was enabled

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

```json
[
  {
    "rankCard": {
      "backgroundImageURL": "/home/container/data/default_background.jpg",
      "progressBarColor": "#ffaabb"
    },
    "userId": "694986201739952229",
    "guildId": "940249530962706492",
    "username": "stef_dp",
    "level": 1,
    "xp": 0,
    "lastXpIncrease": "2023-09-24T11:00:58.370Z"
  }
]
```

{% endtab %}

{% tab title="Headers" %}

```http
Content-Type: application/json
```

{% endtab %}

{% tab title="Schema" %}

```json
{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "rankCard": {
        "type": "object",
        "properties": {
          "backgroundImageURL": {
            "type": "string",
            "description": "The URL of the background image of th rank card (a path if it's default image)"
          },
          "progressBarColor": {
            "type": "string",
            "description": "The HEX color of the progress bar"
          }
        },
        "description": "Data about the user's rankcard"
      },
      "userId": {
        "type": "string",
        "description": "The ID of the user"
      },
      "guildId": {
        "type": "string",
        "description": "The ID of the guild"
      },
      "username": {
        "type": "string",
        "description": "The username of the user"
      },
      "level": {
        "type": "number",
        "description": "The level of thr user"
      },
      "xp": {
        "type": "number",
        "description": "The XP of the user"
      },
      "lastXpIncrease": {
        "type": "string",
        "description": "The date when the xp was last added"
      }
    }
  }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="200: OK When a valid user is given" %}
Returns the object of the selected user if he has sent atleast one message after the leveling system was enabled

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

```json
{
  "rankCard": {
    "backgroundImageURL": "/home/container/data/default_background.jpg",
    "progressBarColor": "#ffaabb"
  },
  "userId": "694986201739952229",
  "guildId": "940249530962706492",
  "username": "stef_dp",
  "level": 1,
  "xp": 0,
  "lastXpIncrease": "2023-09-24T11:00:58.370Z"
}
```

{% endtab %}

{% tab title="Headers" %}

```http
Content-Type: application/json
```

{% endtab %}

{% tab title="Schema" %}

```json
{
  "type": "object",
  "properties": {
    "rankCard": {
      "type": "object",
      "properties": {
        "backgroundImageURL": {
          "type": "string",
          "description": "The URL of the background image of th rank card (a path if it's default image)"
        },
        "progressBarColor": {
          "type": "string",
          "description": "The HEX color of the progress bar"
        }
      },
      "description": "Data about the user's rankcard"
    },
    "userId": {
      "type": "string",
      "description": "The ID of the user"
    },
    "guildId": {
      "type": "string",
      "description": "The ID of the guild"
    },
    "username": {
      "type": "string",
      "description": "The username of the user"
    },
    "level": {
      "type": "number",
      "description": "The level of thr user"
    },
    "xp": {
      "type": "number",
      "description": "The XP of the user"
    },
    "lastXpIncrease": {
      "type": "string",
      "description": "The date when the xp was last added"
    }
  }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized The API key is not valid" %}
{% tabs %}
{% tab title="Body" %}

```json
{
    "code": 401,
    "message": "Unauthorized"
}
```

{% endtab %}

{% tab title="Headers" %}

```http
Content-Type: application/json
```

{% endtab %}

{% tab title="Schema" %}

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "number",
      "description": "The code of the error"
    },
    "message": {
      "type": "string",
      "description": "A description of the error"
    }
  }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403: Forbidden The user has been banned" %}
{% tabs %}
{% tab title="Body" %}

```json
{
    "code": 1000,
    "message": "The owner of this key is banned from the bot"
}
```

{% endtab %}

{% tab title="Headers" %}

```http
Content-Type: application/json
```

{% endtab %}

{% tab title="Schema" %}

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "number",
      "description": "The code of the error"
    },
    "message": {
      "type": "string",
      "description": "A description of the error"
    }
  }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="403: Forbidden The guild has been banned" %}
{% tabs %}
{% tab title="Body" %}

```json
{
    "code": 1001,
    "message": "The guild is banned from the bot"
}
```

{% endtab %}

{% tab title="Headers" %}

```http
Content-Type: application/jso
```

{% endtab %}

{% tab title="Schema" %}

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "number",
      "description": "The code of the error"
    },
    "message": {
      "type": "string",
      "description": "A description of the error"
    }
  }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="404: Not Found The user or the guild are not present in the bot's database" %}
{% tabs %}
{% tab title="Body" %}

```json
{
    "code": 404,
    "message": "Not Found"
}
```

{% endtab %}

{% tab title="Headers" %}

<pre class="language-http"><code class="lang-http"><strong>Content-Type: application/json
</strong></code></pre>

{% endtab %}

{% tab title="Schema" %}

```json
{
  "type": "object",
  "properties": {
    "code": {
      "type": "number",
      "description": "The code of the error"
    },
    "message": {
      "type": "string",
      "description": "A description of the error"
    }
  }
}
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

## Examples

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

```sh
curl 'https://api.stefdp.com/gattinhosBot/guilds/940249530962706492/users'
    -H 'Authorization: Bearer <API_KEY>'
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
fetch('https://api.stefdp.com/gattinhosBot/guilds/940249530962706492/users', {
    headers: {
        'Authorization': 'Bearer <API_KEY>'
    }
})
```

### Try it out!

{% @runkit/embed content="const guild\_id = 'YOUR\_GUILD\_ID'
const api\_key = 'YOUR\_API\_KEY'

fetch(`https://api.stefdp.is-a.dev/gattinhosBot/guilds/${guild_id}/users`, {
headers: {
'Authorization': `Bearer ${api_key}`
}
}).then(res => res.json()).then(console.log)" nodeVersion="18.x.x" %}
{% 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.stefdp.com/reference/gattinhosbot/guild-users.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.