# Community Hub API

### Authentication

You need to pass your API token as a header `x-api-key` for all requests.

###  Where to find your API key

You can find your API key by signing in to sesamelabs.xyz and then visiting `Settings -> In-App Events` API section.

<figure><img src="/files/wFEtkac3KvV36refXJia" alt=""><figcaption></figcaption></figure>

### Events API

Our product already has integrations with social platforms (like Twitter, Discord, Telegram, Youtube, etc). We also have on-chain integrations (Ethereum, Polygon). However, sometimes you might want to create Quests that incentivize off-chain activity that happens within your product (website, mobile, etc). This is where our events API can be used. Use the below POST endpoint to send events. Once that is hooked up, you can create a Quest, select Action type `In-App` and select the event name from the dropdown.

## Create an Event

<mark style="color:green;">`POST`</mark> `https:/sesamelabs.xyz/api/v0/events`

Use this API to send an event that takes place on your website to our servers. This can then be used to create Quests to incentivize user activity within your product.

#### Request Body

| Name                                            | Type   | Description                                                                                                                                                                                      |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| walletAddress<mark style="color:red;">\*</mark> | String | walletAddress of the user that completed the in-game event                                                                                                                                       |
| value<mark style="color:red;">\*</mark>         | Number | number of events completed by the wallet. In most cases it is best to use 1. However if you need to batch multiple completions of the same event, then this value can be something other than 1. |
| event                                           | String | <p>The name of the event. It would be great to keep the format of the events consistent. <br>E.g. camel casing, active/passive voice etc. e.g., "battleWon"</p>                                  |

{% tabs %}
{% tab title="200: OK Event Response" %}

<pre class="language-json"><code class="lang-json"><strong>{
</strong>	"success":true,
	"id":"cl9n8v8io00009k0rtjzwsofm",
	"appId":"cl6gosk7700368gbh4h1xwvcz",
	"walletAddress":"0x8abDecab4ad7Fc00C599631B662eC103a2F559a4",
	"timestamp":"2022-10-24T20:41:43.391Z",
	"eventName":"battleWon",
	"value":1,	
}
</code></pre>

{% endtab %}

{% tab title="500: Internal Server Error Error response" %}

```json
{"success": false}
```

{% endtab %}
{% endtabs %}

### Users API

#### User Type

Our `User` type has the following schema. It would either return the wallet address if the user authenticated with the wallet address or will return the discord id and the user name if requested with the discord id.

```
User {
  id: string,
  appId: string,
  xp: number,
  credits: number,
  points: number
  level: number,
  walletAddress: string?,
  discordId: string?,
  discordUser: string?,
  twitterId: string?,
  twitterUsername: string?,
  externalId: string?
}
```

#### Get User by Wallet Address

## User by wallet address

<mark style="color:blue;">`GET`</mark> `https://sesamelabs.xyz/api/v0/users/by/wallet/<address>`

Fetch a user based on their wallet address.

#### Path Parameters

| Name                                      | Type   | Description    |
| ----------------------------------------- | ------ | -------------- |
| address<mark style="color:red;">\*</mark> | String | wallet address |

{% tabs %}
{% tab title="200: OK The user object" %}

```json
{
    "appId": "clif75qg30016usyr0gb0c4mt",
    "credits": 0,
    "id": "clif7o49z0005usolwkuf7nv0",
    "level": 1,
    "walletAddress": "0xblahblah",
    "xp": 0
}
```

{% endtab %}
{% endtabs %}

#### Get User by ID

## User by ID

<mark style="color:blue;">`GET`</mark> `https://sesamelabs.xyz/api/v0/users/<id>`

Fetch user based on id

#### Path Parameters

| Name                               | Type   | Description |
| ---------------------------------- | ------ | ----------- |
| <mark style="color:red;">\*</mark> | String | User ID     |

{% tabs %}
{% tab title="200: OK The user Object" %}

```json
{
    "appId": "clif75qg30016usyr0gb0c4mt",
    "credits": 0,
    "id": "clif7o49z0005usolwkuf7nv0",
    "level": 1,
    "walletAddress": "0xblahblah",
    "xp": 0
}
```

{% endtab %}
{% endtabs %}

#### Get User by Discord ID

## User by DiscordID

<mark style="color:blue;">`GET`</mark> `https://sesamelabs.xyz/api/v0/by/discord/<discordId>`

Fetch user based on discord ID.

#### Path Parameters

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

{% tabs %}
{% tab title="200: OK The User object with Discord details" %}

```json
{
  "id": "clif7o49z0005usolwkuf7nv0",
  "appId": "clif75qg30016usyr0gb0c4mt",
  "xp": 0,
  "level": 1,
  "credits": 0,
  "discordId": "3050389892855xxxx",
  "discordUsername": "user#2828"
}
```

{% endtab %}
{% endtabs %}

#### Get User by External ID

## User by External ID

<mark style="color:blue;">`GET`</mark> `https://sesamelabs.xyz/api/v0/users/by/external-identity/<external_id>`

Fetch user based on external id

#### Path Parameters

| Name                                           | Type   | Description |
| ---------------------------------------------- | ------ | ----------- |
| external\_id<mark style="color:red;">\*</mark> | String | User ID     |

{% tabs %}
{% tab title="200: OK The user Object" %}

```json
{
    "appId": "clif75qg30016usyr0gb0c4mt",
    "credits": 0,
    "id": "clif7o49z0005usolwkuf7nv0",
    "level": 1,
    "walletAddress": "0xblahblah",
    "xp": 0
}
```

{% endtab %}
{% endtabs %}

#### Get Users

## Leaderboard

<mark style="color:blue;">`GET`</mark> `https://sesamelabs.xyz/api/v0/users/`

Gets a list of users sorted by XP

{% tabs %}
{% tab title="200: OK A list of users." %}

```json
[
    {
        "appId": "clif75qg30016usyr0gb0c4mt",
        "credits": 0,
        "id": "clif7o49z0005usolwkuf7nv0",
        "level": 1,
        "startedAt": "2023-06-02T23:43:23.303Z",
        "walletAddress": "0x3d7ec64a87ed1c446a414bef7d939f39ea16271e",
        "xp": 0
    },
    ....
]
```

{% endtab %}
{% endtabs %}

#### Create a User with a wallet address

## Create user with a wallet address

<mark style="color:green;">`POST`</mark> `https://sesamelabs.xyz/api/v0/users/`

Create a user with a given wallet address.

#### Request Body

| Name                                            | Type   | Description                               |
| ----------------------------------------------- | ------ | ----------------------------------------- |
| walletAddress<mark style="color:red;">\*</mark> | String | Wallet address as string e.g., 0xblahblah |

{% tabs %}
{% tab title="200: OK Newly created user object." %}

```
{
  "id": "clif8vqjf000ausolyzzocrfc",
  "appId": "clif75qg30016usyr0gb0c4mt",
  "xp": 0,
  "level": 1,
  "credits": 0,
  "walletAddress": "0x22ba14068266f2e3daC1d441782001590E0d8EA0"
}
```

{% endtab %}
{% endtabs %}

#### Create a User with an external ID

## Create user with a external id

<mark style="color:green;">`POST`</mark> `https://sesamelabs.xyz/api/v0/users/by/external-identity`

Create a user with an external identity, email, and name

#### Request Body

| Name                                         | Type   | Description                   |
| -------------------------------------------- | ------ | ----------------------------- |
| externalId<mark style="color:red;">\*</mark> | String | ID of the user in your DB     |
| fullName<mark style="color:red;">\*</mark>   | String | full name of the user         |
| email<mark style="color:red;">\*</mark>      | String | email of the user             |
| avatar                                       | String | URL of user's profile picture |

{% tabs %}
{% tab title="200: OK Newly created user object." %}

```
{
  "id": "clif8vqjf000ausolyzzocrfc",
  "appId": "clif75qg30016usyr0gb0c4mt",
  "xp": 0,
  "level": 1,
  "credits": 0,
  "walletAddress": "0x22ba14068266f2e3daC1d441782001590E0d8EA0"
}
```

{% endtab %}
{% endtabs %}

#### Reward user with XP and Credits

## Reward User&#x20;

<mark style="color:green;">`POST`</mark> `https://sesamelabs.xyz/api/v0/users/<id>/reward`

Reward users with XP and Credits.&#x20;

#### Path Parameters

| Name                               | Type   | Description                               |
| ---------------------------------- | ------ | ----------------------------------------- |
| <mark style="color:red;">\*</mark> | String | The User ID that want to grant rewards to |

#### Request Body

| Name                                        | Type   | Description                          |
| ------------------------------------------- | ------ | ------------------------------------ |
| xp<mark style="color:red;">\*</mark>        | Int    | XP                                   |
| credits<mark style="color:red;">\*</mark>   | Int    | Credits                              |
| eventName<mark style="color:red;">\*</mark> | String | eventName assocated with the reward. |

{% tabs %}
{% tab title="200: OK Status" %}

```json
{"success": true}
```

{% endtab %}
{% endtabs %}

**Reward by external user id with XP and Credits**

## Reward User by external ID

<mark style="color:green;">`POST`</mark> `https://sesamelabs.xyz/api/v0/users/by/external-identity/<external_id>/reward`

Reward external user id with XP and Credits.&#x20;

#### Path Parameters

| Name                                           | Type   | Description                                                 |
| ---------------------------------------------- | ------ | ----------------------------------------------------------- |
| external\_id<mark style="color:red;">\*</mark> | String | The ID of the user in your DB that want to grant rewards to |

#### Request Body

| Name                                        | Type   | Description                                                               |
| ------------------------------------------- | ------ | ------------------------------------------------------------------------- |
| xp<mark style="color:red;">\*</mark>        | Int    | XP                                                                        |
| credits                                     | Int    | Credits                                                                   |
| eventName<mark style="color:red;">\*</mark> | String | eventName assocated with the reward.                                      |
| points                                      | Int    | Same as Credits. Exactly one out of `credits` or `points` must be present |

{% tabs %}
{% tab title="200: OK Status" %}

```json
{"success": true}
```

{% 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.sesamelabs.xyz/product-guides/integrations/api/community-hub-api.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.