Endpoints

The Documentation shown below will always be for the latest version of the Cosmo API Addon.

Replace example.com with your server's IP or FQDN.

User

User Information

Get information about a user.

GET http://example.com/api/v1/users/info

Retrieve information about any user.

This endpoint can be used by the specific user's API Key or the Admin Key.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to fetch information on.

200: OK SUCCESS

Example Response:

{
    "discord_id": "490537526436560896",
    "uuid": "2aaf1cc8c6a14ae98d973b9f07f8ff3a",
    "credits": 5624,
    "cosmetics": {
        "equipped": {
            "bandana": null,
            "bodywear": "pEK8nKC4",
            "cloak": null,
            "glasses": null,
            "hat": null,
            "mask": null,
            "pet": null,
            "shoes": null,
            "wings": null
        },
        "locker": [
            "pEK8nKC4",
            "2uOb7Kt5"
        ]
    }
}

Get a user's transactions.

GET http://example.com/api/v1/users/transactions

Retrieve a list of a user's transactions and items bought using the shop.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to fetch information on.

200: OK SUCCESS

{
    "discord_id": "490537526436560896",
    "uuid": "2aaf1cc8c6a14ae98d973b9f07f8ff3a"
    "transactions": [
        {
            "cosmeticId": "pEK8nKC4",
            "cost": 100,
            "timestamp": 1686515025
        },
        {
            "cosmeticId": "2uOb7Kt5",
            "cost": 300,
            "timestamp": 1686515798
        }
    ],
}

Get all linked accounts and UUID's.

GET http://example.com/api/v1/users/list

Retrieve an array of all the linked accounts and which Minecraft UUID it is linked to.

This endpoint can be used by the Admin Key only.

200: OK SUCCESS

{
    "447076198762151937": "70c8e04f35a942dabe5cc16af8058a8a",
    "490537526436560896": "2aaf1cc8c6a14ae98d973b9f07f8ff3a"
}

Account Linking

Link a Minecraft Account to a Discord Account.

POST http://example.com/api/v1/users/link

Bind a Minecraft account to a Discord Account by listing the two IDs.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
discordid*	String	The user's Discord ID that you wish to link.
minecraft_username*	String	The Minecraft Username that you wish to link.

201: Created CREATED

{"linked": True}

Unlink a Minecraft Account from a Discord Account.

DELETE http://example.com/api/v1/users/unlink

Unlink a Discord Account from a Minecraft Account or vice-versa.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to unlink.

200: OK SUCCESS

{"unlinked": True}

Cosmetics

Cosmetic Information

List all cosmetics.

GET http://example.com/api/v1/cosmetics/list

Retrieve a list of all the cosmetics the bot has. This is not an endpoint for the shop (which shows buyable cosmetics).

This endpoint can be used by any user API Key or the Admin Key.

200: OK SUCCESS

[
    {
        "categoryId": "eIH69Ue4",
        "cost": 125,
        "description": "Turn into an enderman!",
        "id": "AIr77hfh",
        "name": "Enderman",
        "showcaseImage": "https://i.imgur.com/abcdef",
        "type": "cloak"
    },
    {
        "categoryId": "eIH69Ue4",
        "cost": 150,
        "description": "Happy birthday to you!",
        "id": "AgsoNWHI",
        "name": "Birthday Cape!",
        "showcaseImage": "https://i.imgur.com/123456",
        "type": "cloak"
    }
]

List all buyable cosmetics from the shop.

GET http://example.com/api/v1/cosmetics/shop

Retries a list of all the cosmetics in the shop.

This endpoint can be used by any user API Key or the Admin Key.

200: OK SUCCESS

put example here

Modifying Cosmetics

Create a cosmetic.

POST http://example.com/api/v1/cosmetics/create

Create/upload a cosmetic or cloak to Cosmo. There is no error handling for incorrect image and file URLs.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
name*	String	The display name for the cosmetic.
type*	String	The type of cosmetic. Accepted types: cloak, wings, pet, hat, bodywear, bandana, mask, shoes, glasses.
description*	String	The description for the cosmetic.
categoryid*	String	The category ID for the cosmetic to be in.
cost*	String	The cost of the cosmetic, given as an integer. The value type is parsed as a string, then converted to an integer. To make the cosmetic unavailable for purchase, set this to "0".
showcase_image_url*	String	A direct image URL to the showcase image of the cosmetic. Suggested formats: .png, .jpeg, .jpg
model_source_url*	String	A direct URL to the CFG of the cosmetic model. Not required for "cloak" type cosmetics. Required format: .cfg
texture_source_url*	String	A direct image URL to the texture of the cosmetic. Required format: .png

200: OK SUCCESS

put response here

Edit a cosmetic

PATCH http://example.com/api/v1/cosmetics/update

Edit a cosmetic's details.

Apart from "original_name" all other values are optional, but one must be chosen to actually edit. You can edit any amount of values with one request.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
original_name*	String	The original name of the cosmetic you wish to edit
name	String	The new display name for the cosmetic.
type	String	The new type for the cosmetic. Accepted types: wings, pet, hat, bodywear, bandana, mask, shoes, glasses. Cloak types cannot be changed.
description	String	The new description for the cosmetic.
categoryid	String	The new category ID for the cosmetic to be in.
cost	String	The new cost of the cosmetic, given as an integer. The value type is parsed as a string, then converted to an integer.
showcase_image_url	String	The new direct image URL to the showcase image of the cosmetic.
model_source_url	String	The new direct URL to the CFG of the cosmetic model. Not required for "cloak" type cosmetics.
texture_source_url	String	The new direct image URL to the texture of the cosmetic.

200: OK SUCCESS

{"edited": true}

Delete a cosmetic.

DELETE http://example.com/api/v1/cosmetics/delete

Delete a cosmetic from the bot.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
cosmetic*	String	The cosmetic's name for the one that you would like to delete.

200: OK SUCCESS

{"deleted": true}

Cosmetic Ownership

Purchase a cosmetic.

POST http://example.com/api/v1/cosmetics/buy

Purchase a cosmetic from the shop.

This endpoint can be used by the specific user's API Key or the Admin Key.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to buy the cosmetic on. If this request is being issued from a user key, the ID MUST reflect their account.
cosmeticid*	String	The ID of the cosmetic they wish to purchase.

200: OK SUCCESS

ex resp

Grant a cosmetic.

POST http://example.com/api/v1/cosmetics/grant

Force grant a cosmetic to a user.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to grant the cosmetic to.
cosmeticid*	String	The ID of the cosmetic to grant.

200: OK SUCCESS

{"granted": True}

Revoke a cosmetic.

DELETE /cosmetics/revoke

Force remove a cosmetic from a user.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to grant the cosmetic to.
cosmeticid*	String	The ID of the cosmetic to grant.

200: OK SUCCESS

{"revoked": True}

Equipping/Unequipping

Equip a cosmetic.

POST http://example.com/api/v1/cosmetics/equip

Equip a cosmetic for a user, or on your own account.

This endpoint can be used by the specific user's API Key or the Admin Key.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to equip the cosmetic on. If this request is being issued from a user key, the ID MUST reflect their account.
cosmetictype*	String	The type of cosmetic to equip. Accepted types: cloak, wings, pet, hat, bodywear, bandana, mask, shoes, glasses.
cosmeticid*	String	The cosmetic ID to equip.

200: OK SUCCESS

{"equipped": True}

Unequip a cosmetic.

DELETE http://example.com/api/v1/cosmetics/unequip

Unequip a cosmetic for a user, or on your own account.

This endpoint can be used by the specific user's API Key or the Admin Key.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to unequip the cosmetic from. If this request is being issued from a user key, the ID MUST reflect their account.
cosmetictype*	String	The type of cosmetic to unequip. Accepted types: cloak, wings, pet, hat, bodywear, bandana, mask, shoes, glasses.

200: OK SUCCESS

{"unequipped": True}

Categories

Category Information

List all categories.

GET http://example.com/api/v1/categories/list

Retrieve a list of all cosmetic categories with their name & ID.

This endpoint can be used by any user API Key or the Admin Key.

200: OK SUCCESS

[
    {
        "id": "eIH69Ue4",
        "name": "Lightning Set"
    },
    {
        "id": "F1wHozEL",
        "name": "Fluffy Series"
    }
]

Modifying Categories

Create a new category.

POST http://example.com/api/v1/categories/create

Create a new category in the bot.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
name*	String	The display name for the new category.

200: OK SUCCESS

{
    "id": "kI80vjRP",
    "name": "Lightning Bundle"
}

Rename a category.

PATCH http://example.com/api/v1/categories/rename

Update a category name.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
old_name*	String	The old name of the category.
new_name*	String	The new name for the category.

200: OK SUCCESS

Returns the new data for the category.

{
    "id": "kI80vjRP",
    "name": "Mushroom Bundle"
}

Delete a category.

DELETE http://example.com/api/v1/categories/delete

Delete a category from the bot.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
category_id*	String	The ID of the category to delete.

200: OK SUCCESS

Example response

Credits

Fetching Credits

The user's credits can be fetched using the /users/info endpoint.

Modifying Credits

Modify a user's credit amount.

PATCH http://example.com/api/v1/credits/modify

Adjust a user's credit amount by a certain amount.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to fetch information on.
amount*	String	Amount to modify the credits by. Example: "-5", "60", "-100"

200: OK SUCCESS

{"credits": 660} // Shows the users new amount of credits.

Set a user's credit amount.

PATCH http://example.com/api/v1/credits/set

Update a user's credit amount by defining a new amount. If you wish to add or remove credits from a user, you should use the "modify" endpoint.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to fetch information on.
new_amount*	String	A number giving the new amount of credits for the user.

200: OK SUCCESS

{"credits": 560} // Shows the users new amount of credits.

Coupons

Coupon Information

List all coupon codes.

GET http://example.com/api/v1/coupons/list

Retrieve a list of every coupon code in the bot. Active or inactive.

This endpoint can be used by the Admin Key only.

200: OK SUCCESS

Example response

Modifying Coupons

Create a coupon code.

POST http://example.com/api/v1/coupons/create

Create a coupon code to add to the bot.

One of the "credit_grant" and "cosmetic_grant" parameters is required, or both can be used. The request will fail if none is provided.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
code*	String	The name / code for the coupon code.
active	Boolean	Set to False to set the coupon to not be active (can't be used). If not specified or the input is incorrect, the coupon will be active.
uses	Integer	Amount of uses the coupon should have. If not specified or the input is incorrect, the coupon will have unlimited uses
expires	Integer	A unix timestamp for when the coupon should expire. If not specified or the input is incorrect, the coupon will have no expiry.
day_limit	Integer	The maximum amount of days a user can be in the server to redeem the coupon code. If not specified or the input is incorrect, the coupon will not have a day limit.
credit_grant	Integer	The amount of credits to grant to the user apon redemption. If not specified or the input is incorrect, the coupon will not grant any credits.
cosmetic_grant	String	The cosmetic's ID to grant to the user apon redemption. If not specified or the input is incorrect, the coupon will not grant any cosmetics.

201: Created CREATED

{"created": true}

Update a coupon code.

PATCH http://example.com/api/v1/coupons/edit

Edit a coupon code's details.

Apart from "original_name", all other values are optional, but one must be chosen to actually edit. You can edit any amount of values with one request.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
original_code*	String	The original name of the coupon you wish to edit
code	String	The new name / code for the coupon code.
active	String	Set to False to set the coupon to not be active (can't be used). If not specified or the input is incorrect, the coupon will be active.
uses	String	The new amount of uses the coupon should have. If not specified or the input is incorrect, the coupon will have unlimited uses
expires	String	The new unix timestamp for when the coupon should expire. If not specified or the input is incorrect, the coupon will have no expiry.
day_limit	String	The new maximum amount of days a user can be in the server to redeem the coupon code. If not specified or the input is incorrect, the coupon will not have a day limit.
credit_grant	String	The new amount of credits to grant to the user apon redemption. If not specified or the input is incorrect, the coupon will not grant any credits.
cosmetic_grant	String	The new cosmetic ID to grant to the user apon redemption. If not specified or the input is incorrect, the coupon will not grant any cosmetics.

200: OK SUCCESS

{"edited": true}

Delete a coupon code.

DELETE http://example.com/api/v1/coupons/delete

Delete a coupon code from the bot. You should usually deactivate a coupon code if you'd rather it wasn't used anymore so that the coupon's history is saved.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
code*	String	The coupon code / name to delete

200: OK SUCCESS

{"deleted": true}

Redeeming Coupons

Redeem a coupon code.

POST http://example.com/api/v1/coupons/redeem

Redeem a coupon code on a user's account.

If a code has a dayLimit set, it cannot be redeemed via the API because it cannot check if the user fits or doesn't fit into that category.

This endpoint can be used by the specific user's API Key or the Admin Key.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to equip the cosmetic on. If this request is being issued from a user key, the ID MUST reflect their account.
code*	String	The code to redeem

200: OK SUCCESS

{
    "redeemed": True,
    "rewards": {
        "credits": 50,
        "cosmetic": "Butterfly Hat"
    }
}

Creator Codes

Code Information

List all creator codes.

GET http://example.com/api/v1/creatorcodes/list

Retrieve a list of every creator code in the bot.

This endpoint can be used by the Admin Key only.

200: OK SUCCESS

[
    {
        "code": "fbr",
        "id": "EFcNT0GE",
        "owner": 447076198762151937,
        "uses": [
            {
                "amount_to_creator": 2,
                "cost": 50,
                "customer": 490537526436560896,
                "item_bought": "AgsoNWHI",
                "timestamp": 1687797660
            }
        ]
    }
]

Check if a user is supporting.

GET http://example.com/api/v1/creatorcodes/supporting

Check if a user is supporting a certain creator.

This endpoint can be used by any user's API Key or the Admin Key.

Path Parameters

Name	Type	Description
id*	String	Either a Discord ID or a Minecraft UUID to check for.
creator_code*	String	The creator code to check if the user is supporting.

200: OK SUPPORTING

{"supporting": true}

404: Not Found NOT SUPPORTING

{"supporting": false}

Modifying Codes

Create a creator code.

POST http://example.com/api/v1/creatorcodes/create

Create a coupon code to add to the bot. WARNING: There is no validation for the Discord ID being correct. Make sure that whatever you code has validation.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
code*	String	The code to use as the creator code.
assigned_user*	String	The DISCORD ID to assign this code to. They will get the designated percentage of the credits.

201: Created SUCCESS

{"created": true}

Update a creator code.

PATCH http://example.com/api/v1/creatorcodes/update

Update a creator code's name or assigned user. WARNING: There is no validation for the Discord ID being correct. Make sure that whatever you code has validation.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
original_code*	String	The code's name to edit.
new_code	String	The new code's name.
new_owner	String	The NEW DISCORD ID to assign this code to. They will now get the designated percentage of the credits.

200: OK SUCCESS

{"edited": true}

Delete a creator code.

DELETE http://example.com/api/v1/creatorcodes/delete

Delete a creator code from the bot.

This endpoint can be used by the Admin Key only.

Path Parameters

Name	Type	Description
code*	String	The code name to delete

200: OK SUCCESS

{"deleted": true}

Setting Codes

Set a creator code.

POST http://example.com/api/v1/creatorcodes/set

Set a creator code on a user's account. Any purchases that the user makes will then give a percentage (set in the config) of funds to the code's owner.

This endpoint can be used by the specific user's API Key or the Admin Key.

Path Parameters

Name	Type	Description
code*	String	The code to set. Set to "0" to remove a code from an account.
id*	String	Either a Discord ID or a Minecraft UUID to equip the cosmetic on. If this request is being issued from a user key, the ID MUST reflect their account.

200: OK SUCCESS

{"processed": true}