# Welcome

The official welcome.

Welcome to the official API Documentation for Memerator.me's API. Here you will find documentation and examples on how to use the API.

Danger: This API is prone to change at any point. If at any point the docs are wrong, let us know in [#docs on the Memerator Discord server](https://discord.gg/3sVcrE3), if something is wrong with the API itself (like it's broken), let us know in [#api on the Memerator Discord server](https://discord.gg/hn4pBVU)!

Use the sidebar navigation to get help!


# Authorization

To talk to us, you need some Authorization. Simply head to [API key](https://memerator.me/api/auth) to get you set up! It's crucial to not tell anyone this! It's secure, for you, and with it, anyone can use your account. **All requests require authorization.**

Once you have a key, you simply need to add an Authorization header to your requests.

`Authorization: [your key]`


# Resources


# User/Profile

The User object is returned when requesting 1 or multiple users. An example object is as follows

| Field     | Type      | Description                                             |
| --------- | --------- | ------------------------------------------------------- |
| username  | string    | The username of this profile                            |
| bio       | string    | This user's bio                                         |
| id        | int       | The ID of this user.                                    |
| stats     | hash      | A hash of a user's meme, followers, and following count |
| perks     | hash      | A hash of a user's perks.                               |
| permalink | string    | The URL to this user's profile                          |
| joined    | timestamp | The exact date this user registered                     |

## Get User

<mark style="color:blue;">`GET`</mark> `https://api.memerator.me/v1/profile/:user`

This endpoint allows you to get a user's profile by ID or username.

#### Path Parameters

| Name  | Type   | Description                                 |
| ----- | ------ | ------------------------------------------- |
| :user | object | The user you want. Can be by ID or username |

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

```javascript
{
    "username": "Chew",
    "bio": "<script>alert('hi');</script>",
    "id": 476488167042580481,
    "stats": {
        "memes": 67,
        "followers": 2,
        "following": 3
    },
    "perks": {
        "verified": true,
        "staff": true,
        "translator": false,
        "pro": true
    },
    "permalink": "https://memerator.me/profile/476488167042580481",
    "joined": "2018-10-11T15:37:03.000Z"
}
```

{% endtab %}

{% tab title="404 Could not find a user matching this query." %}

```javascript
{
    "error": "this user does not exist!"
}
```

{% endtab %}
{% endtabs %}

## Get Integrations

<mark style="color:blue;">`GET`</mark> `https://api.memerator.me/v1/integrations`

Gets your integrations. Requires "View Integrations" key permission.

{% tabs %}
{% tab title="200 A JSONObject consisting of a mapping of service name to an array of integrations for said service name." %}

```javascript
{
    "google": [
        "my google email",
        "my second google email",
        "mcdonalds@gov.gov"
    ],
    "apple": [
        "send me @bitcoin"
    ],
    "minecraft": [
        "sdlhfw87e4rt43h7tu34tfelsiofyest8ye4t"
    ],
    "discord": [
        "4756754676574567567"
    ]
}
```

{% endtab %}
{% endtabs %}


# Meme

Information about the meme object

The Meme object is returned when requesting 1 or multiple memes. An example object is as follows.

| Field     | Type      | Description                                               |
| --------- | --------- | --------------------------------------------------------- |
| disabled  | boolean   | is the meme disabled?                                     |
| memeid    | string    | the meme's id                                             |
| caption   | string    | the meme's caption                                        |
| author    | User      | a user object of the author                               |
| rating    | hash      | hash of the rating, with the average and total ratings    |
| url       | string    | the url of the image of the meme                          |
| permalink | string    | the url of the meme on memerator.me                       |
| timestamp | timestamp | when the meme was submitted                               |
| time\_ago | string    | what appears on the website how long ago it was submitted |

```javascript
{
    "disabled": false,
    "memeid": "aaaaaaa",
    "caption": "***__AAAAAAAA__***",
    "author": {
        "username": "Chew",
        "bio": "#1 most depressed memerator user. pronouns: she/her",
        "id": 476488167042580481,
        "stats": {
            "memes": 171,
            "followers": 26,
            "following": 20
        },
        "perks": {
            "verified": true,
            "staff": true,
            "translator": false,
            "pro": true
        },
        "permalink": "https://memerator.me/profile/476488167042580481",
        "joined": "2018-10-11T15:37:03.000Z"
    },
    "rating": {
        "average": 3.75,
        "total": 4
    },
    "url": "https://cdn.memerator.me/K7bLRy9.jpg",
    "permalink": "https://memerator.me/meme/aaaaaaa",
    "timestamp": "2019-02-15T13:29:01.000Z",
    "time_ago": "11 months"
}
```

## Get a Meme

<mark style="color:blue;">`GET`</mark> `https://api.memerator.me/v1/meme/:id`

This request gets a meme by its ID.

#### Path Parameters

| Name    | Type   | Description                 |
| ------- | ------ | --------------------------- |
| Meme ID | string | The ID of the meme you want |

{% tabs %}
{% tab title="200" %}
Response of a valid meme.

```json
{
    "disabled": false,
    "memeid": "aaaaaaa",
    "caption": "***__AAAAAAAA__***",
    "author": {
        "username": "Chew",
        "bio": "#1 most depressed memerator user. pronouns: she/her",
        "id": 476488167042580481,
        "stats": {
            "memes": 171,
            "followers": 26,
            "following": 20
        },
        "perks": {
            "verified": true,
            "staff": true,
            "translator": false,
            "pro": true
        },
        "permalink": "https://memerator.me/profile/476488167042580481",
        "joined": "2018-10-11T15:37:03.000Z"
    },
    "rating": {
        "average": 3.75,
        "total": 4
    },
    "url": "https://cdn.memerator.me/K7bLRy9.jpg",
    "permalink": "https://memerator.me/meme/aaaaaaa",
    "timestamp": "2019-02-15T13:29:01.000Z",
    "time_ago": "11 months"
}
```

{% endtab %}

{% tab title="401" %}
Response of an invalid auth key.

```javascript
{
    "error": "Auth not valid"
}
```

{% endtab %}

{% tab title="404" %}
Response of a meme that doesn't exist (or is disabled, and you aren't the owner)

```javascript
{
    "error": "meme does not exist"
}
```

{% endtab %}
{% endtabs %}

## Get a Random Meme

<mark style="color:blue;">`GET`</mark> `https://api.memerator.me/v1/meme/random`

Gets a random meme. Note: Not completely random?

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

```
[a meme object]
```

{% endtab %}

{% tab title="401 Response when using an invalid API key" %}

```javascript
{
    "error": "Auth not valid"
}
```

{% endtab %}
{% endtabs %}

## Set Meme Caption

<mark style="color:orange;">`PUT`</mark> `https://api.memerator.me/v1/meme/:id/caption`

Change the caption of a meme you own.

#### Path Parameters

| Name | Type   | Description    |
| ---- | ------ | -------------- |
| :id  | string | ID of the meme |

#### Query Parameters

| Name    | Type   | Description                       |
| ------- | ------ | --------------------------------- |
| caption | string | The caption you want to set it to |

{% tabs %}
{% tab title="200 A successful caption change response" %}

```javascript
{
    "success": true,
    "caption": "uwu owo nyaa",
    "oldcaption": "you got got guten prankened"
}
```

{% endtab %}

{% tab title="400 When a known error occurs, you'll get this. It can differ, so we put a blank error in. Error will always contain something." %}

```javascript
{
    "error": ""
}
```

{% endtab %}

{% tab title="401 response when using an invalid api key" %}

```javascript
{
    "error": "Auth not valid"
}
```

{% endtab %}

{% tab title="403 Returned if you try to change the caption of a meme you don't own" %}

```javascript
{ "error": "you don't own this meme" }
```

{% endtab %}

{% tab title="404 Raised if you try to edit a meme that doesn't exist" %}

```javascript
{ "error": 'meme does not exist' }
```

{% endtab %}

{% tab title="500 When an unknown error occurs, you'll get this." %}

```javascript
{ "error": 'Unknown Error Changing Caption' }
```

{% endtab %}
{% endtabs %}

## Get Meme Comments

<mark style="color:blue;">`GET`</mark> `https://api.memerator.me/v1/meme/:id/comments`

This method returns an array of comments for a specified meme and their author.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| :id  | string | meme id     |

{% tabs %}
{% tab title="200 An array of comments. In each comment object there is ID, author (User object), the content, the associated Meme, the timestamp, and the creation in epoch seconds." %}

```javascript
[
    {
        "id": 5,
        "author": {
            "username": "Chew",
            "bio": "#1 most depressed Memerator user. pronouns: she/her 🏳️‍⚧️",
            "id": 476488167042580481,
            "stats": {
                "memes": 382,
                "followers": 28,
                "following": 24
            },
            "perks": {
                "verified": true,
                "staff": true,
                "translator": false,
                "pro": true
            },
            "permalink": "https://memerator.me/profile/476488167042580481",
            "joined": "2018-10-11T15:37:03.000Z",
            "joined_epoch_seconds": 1539272223
        },
        "content": "aaaaaaaaaaaaaaaaaaaaaa",
        "meme": {
            "disabled": false,
            "memeid": "aaaaaaa",
            "caption": "***__AAAAAAAA__***",
            "author": {
                "username": "Chew",
                "bio": "#1 most depressed Memerator user. pronouns: she/her 🏳️‍⚧️",
                "id": 476488167042580481,
                "stats": {
                    "memes": 382,
                    "followers": 28,
                    "following": 24
                },
                "perks": {
                    "verified": true,
                    "staff": true,
                    "translator": false,
                    "pro": true
                },
                "permalink": "https://memerator.me/profile/476488167042580481",
                "joined": "2018-10-11T15:37:03.000Z",
                "joined_epoch_seconds": 1539272223
            },
            "rating": {
                "average": 4.0,
                "total": 5
            },
            "age": 1,
            "url": "https://cdn.memerator.me/K7bLRy9.jpg",
            "permalink": "https://memerator.me/meme/aaaaaaa",
            "timestamp": "2019-02-15T13:29:01.000Z",
            "timestamp_epoch_seconds": 1550237341,
            "time_ago": "over 1 year"
        },
        "timestamp": "2020-02-02T15:11:31.000Z",
        "timestamp_epoch_seconds": 1580656291
    }
]
```

{% endtab %}
{% endtabs %}

## Disable a Meme

<mark style="color:orange;">`PUT`</mark> `https://api.memerator.me/v1/meme/:id/disable`

Disables a meme by ID. Meme author only!

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| :id  | string | Meme ID     |

{% tabs %}
{% tab title="200 If you did it right!" %}

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

{% endtab %}

{% tab title="400 If the meme is already disabled" %}

```
{ "error": "this meme is already disabled" }
```

{% endtab %}

{% tab title="401 If your key is invalid or can't access the resource" %}

```
{ "error": "Auth not valid" }
```

{% endtab %}

{% tab title="403 If you don't own the meme" %}

```
{ "error": "you don't own this meme" }
```

{% endtab %}

{% tab title="404 If the meme doesn't exist (or is disabled and you aren't the owner)" %}

```
{ "error": "meme does not exist" }
```

{% endtab %}
{% endtabs %}

## Enable a meme

<mark style="color:orange;">`PUT`</mark> `https://api.memerator.me/v1/meme/:id/enable`

Exact same as disable, but for enabling

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| :id  | string | The Meme ID |

{% tabs %}
{% tab title="200 If you did it right!" %}

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

{% endtab %}

{% tab title="400 If the meme is already enabled" %}

```
{ "error": "this meme is already enabled" }
```

{% endtab %}

{% tab title="401 If the API key is invalid or can't access the resource" %}

```
{ "error": "Auth not valid" }
```

{% endtab %}

{% tab title="403 If you don't own the meme" %}

```
{ "error": "you don't own this meme" }
```

{% endtab %}

{% tab title="404 If the meme doesn't exist or it's disabled and you aren't the owner." %}

```
{ "error": "meme does not exist" }
```

{% endtab %}
{% endtabs %}

## Get your Rating

<mark style="color:blue;">`GET`</mark> `https://api.memerator.me/v1/meme/:id/rating`

Gets your rating on a meme.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| :id  | string | the meme id |

{% tabs %}
{% tab title="200 The rating" %}

```
{ "rating": 5 }
```

{% endtab %}

{% tab title="401 If your key isn't valid or it's not allowed to access "Ratings"" %}

```
{ "error": 'Auth not valid' }
```

{% endtab %}

{% tab title="404 If the meme doesn't exist or it's disabled and you aren't the owner." %}

```
{ "error": 'meme does not exist' }
```

{% endtab %}
{% endtabs %}

## Get all Ratings

<mark style="color:blue;">`GET`</mark> `https://api.memerator.me/v1/meme/:id/ratings`

Gets all ratings for a meme. Pro only! Requires "Ratings" key permission.

#### Path Parameters

| Name | Type   | Description |
| ---- | ------ | ----------- |
| :id  | string | Meme ID.    |

{% tabs %}
{% tab title="200 A JSONArray of objects. Each Object contains a hash mapping of user to User object, rating to the rating, and the timestamp of the rating." %}

```javascript
[
    {
        "user": {
            "username": "treye_2019",
            "bio": "",
            "id": 296476360602419211,
            "stats": {
                "memes": 1,
                "followers": 0,
                "following": 0
            },
            "perks": {
                "verified": false,
                "staff": false,
                "translator": false,
                "pro": false
            },
            "permalink": "https://memerator.me/profile/296476360602419211",
            "joined": "2019-03-02T00:43:26.000Z",
            "joined_epoch_seconds": 1551487406
        },
        "rating": 1,
        "timestamp": "2019-05-20T13:04:33.000Z"
    },
    {
        "user": {
            "username": "Chew",
            "bio": "#1 most depressed Memerator user. pronouns: she/her 🏳️‍⚧️",
            "id": 476488167042580481,
            "stats": {
                "memes": 382,
                "followers": 28,
                "following": 24
            },
            "perks": {
                "verified": true,
                "staff": true,
                "translator": false,
                "pro": true
            },
            "permalink": "https://memerator.me/profile/476488167042580481",
            "joined": "2018-10-11T15:37:03.000Z",
            "joined_epoch_seconds": 1539272223
        },
        "rating": 5,
        "timestamp": "2019-05-20T13:04:33.000Z"
    },
    {
        "user": {
            "username": "Loyal_2019",
            "bio": null,
            "id": 181249274699448320,
            "stats": {
                "memes": 0,
                "followers": 0,
                "following": 0
            },
            "perks": {
                "verified": false,
                "staff": false,
                "translator": false,
                "pro": false
            },
            "permalink": "https://memerator.me/profile/181249274699448320",
            "joined": "2019-03-31T21:35:12.000Z",
            "joined_epoch_seconds": 1554068112
        },
        "rating": 4,
        "timestamp": "2019-05-20T13:04:33.000Z"
    },
    {
        "user": {
            "username": "ur_mom",
            "bio": "is gay",
            "id": 783885855388066361,
            "stats": {
                "memes": 239,
                "followers": 8,
                "following": 4
            },
            "perks": {
                "verified": true,
                "staff": false,
                "translator": false,
                "pro": false
            },
            "permalink": "https://memerator.me/profile/783885855388066361",
            "joined": "2019-10-24T20:37:28.000Z",
            "joined_epoch_seconds": 1571949448
        },
        "rating": 5,
        "timestamp": "2019-11-06T00:28:07.000Z"
    },
    {
        "user": {
            "username": "taketheshake",
            "bio": "I wish I was awesome as chew, but she's almost equivalent to comp sci meme Jesus, so maybe not.",
            "id": 338784252382412800,
            "stats": {
                "memes": 3,
                "followers": 5,
                "following": 1
            },
            "perks": {
                "verified": true,
                "staff": true,
                "translator": false,
                "pro": true
            },
            "permalink": "https://memerator.me/profile/338784252382412800",
            "joined": "2019-04-17T13:27:02.000Z",
            "joined_epoch_seconds": 1555507622
        },
        "rating": 5,
        "timestamp": "2020-02-28T14:39:58.000Z"
    }
]
```

{% endtab %}
{% endtabs %}


# Libraries

Memerator offers various official API Wrapper libraries in various different languages.

Official Libraries are below

| Language | Name               | Version | Links                                                     |
| -------- | ------------------ | ------- | --------------------------------------------------------- |
| Ruby     | memerator-sdk-ruby | 0.1.1   | [GitHub](https://github.com/Memerator/memerator-sdk-ruby) |
| Java     | memerator-sdk-java | 1.0.0   | [GitHub](https://github.com/Memerator/memerator-sdk-java) |
| C#       | memerator-sdk-cs   | Git     | [GitHub](https://github.com/Memerator/memerator-sdk-cs)   |

Un-official libraries are also welcome! If you make a library for us, please let us know by [contacting us](https://memerator.me/support)!


# Feature Table

What the libraries support

A \* next to a "Yes" means the feature is only available in an unreleased build, either in beta or on GitHub only depending on the language.

Anything extra or clarification is added in parenthesis.

| Feature                | <p>memerator-sdk-java</p><p>(Java)</p> | <p>memerator-sdk-ruby</p><p>(Ruby)</p> | <p>memerator-sdk-cs</p><p>(C#)</p> |
| ---------------------- | -------------------------------------- | -------------------------------------- | ---------------------------------- |
| Get Meme               | Yes                                    | Yes                                    | Yes\*                              |
| Get Meme Comments      | Yes                                    | Yes\*                                  | Yes\*                              |
| Set Meme Caption       | Yes                                    | Yes                                    | No                                 |
| Enable Meme            | Yes                                    | Yes                                    | Yes\*                              |
| Disable Meme           | Yes                                    | Yes                                    | Yes\*                              |
| Rate Meme              | Yes                                    | Yes                                    | No                                 |
| Get Meme Ratings       | Yes                                    | No                                     | No                                 |
| Get Own Meme Rating    | No                                     | No                                     | No                                 |
| Get Random Meme        | Yes                                    | Yes                                    | Yes\*                              |
| Get Recent Memes       | Yes                                    | Yes\*                                  | Yes\*                              |
| Get Top Memes          | Yes                                    | No                                     | No                                 |
| Get User Memes         | Yes                                    | Yes                                    | No                                 |
| View Integrations      | Yes                                    | No                                     | No                                 |
| Get Notifications      | Yes                                    | Yes                                    | Yes\*                              |
| Get Notification Count | Yes                                    | No                                     | Yes\*                              |
| Delete Notification    | Yes                                    | No                                     | Yes\*                              |
| Get Profiles           | Yes                                    | Yes                                    | Yes\*                              |
| Get Profile's Memes    | Yes                                    | Yes\* (self only)                      | No                                 |
| Update Profile         | Yes                                    | Yes                                    | Yes\*                              |
| View Reports           | Yes                                    | Yes                                    | Yes\*                              |
| View Stats             | Yes                                    | Yes                                    | No                                 |
| Submit Meme            | Yes                                    | No                                     | No                                 |
| View Top Memers        | Yes                                    | No (outdated)                          | No                                 |