Routes#

General Warning

All routes will return BAD_REQUEST - 400 if required parameters are omitted.

/bundles/:id#

GET#

Retrieve a bundle's data

URL Parameters#

id: The bundle's UID, unlike packs and users, bundles do not have a plaintext ID

Possible Responses#

OK - 200 PackBundle

NOT_FOUND - 404 ApiError

Examples#

Retrieve a bundle

fetch('https://api.smithed.dev/v2/bundles/123456789')

DELETE#

Delete a bundle from the database

URL Parameters#

id: The bundle's UID, unlike packs and users, bundles do not have a plaintext ID

Query Parameters#

token string Either Firebase Id Token or a valid PAT

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Delete a bundle

fetch('https://api.smithed.dev/v2/bundles/123456789?token=ILOVESMITHED', {method: 'DELETE'})

PUT#

Update an existing bundle

URL Parameters#

id: The bundle's UID, unlike packs and users, bundles do not have a plaintext ID

Query Parameters#

token string Either Firebase Id Token or a valid PAT

Body Parameters#

data PackBundle The data to replace the existing with, omitting the owner field.

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Update a bundle

fetch('https://api.smithed.dev/v2/bundles/123456789', {
  method: 'PUT',
  body: {
     data: <PackBundle>
  },
  headers: {
     "Content-Type": "application/json"
  }
})

/bundles/:id/download#

GET#

Download a pack bundle. This route wraps /download and returns the same information.

URL Parameters#

id: The bundle's UID, unlike packs and users, bundles do not have a plaintext ID

Query Parameters#

mode 'datapack' | 'resourcepack' | 'both' = 'both' Which files should be downloaded from the API.

version string? = ' ' Which version of the bundle to download

Possible Responses#

OK - 200 ArrayBuffer

NOT_FOUND - 404 ApiError

Examples#

Download a bundle's resourcepack

fetch('https://api.smithed.dev/v2/bundles/123456789/download?mode=resourcepack')

/bundles#

POST#

Update an existing bundle

Query Parameters#

token string Either Firebase Id Token or a valid PAT

Body Parameters#

data PackBundle The data to replace the existing with, omitting the owner field.

Possible Responses#

CREATED - 201 string

UNAUTHORIZED - 401 ApiError

Examples#

Upload a new bundle

fetch('https://api.smithed.dev/v2/bundles', {
  method: 'PUT',
  body: {
     data: <PackBundle>
  },
  headers: {
     "Content-Type": "application/json"
  }
})

/download#

GET#

This route facilitates the download and merging of packs off of the platform.

Query Parameters#

pack string The ID (uid or plaintext) of the pack to merge. A specific version can be specified with the following format <id>@<version>. Version can be a semver comparison. Many packs can be downloaded by specifiying the parameter multiple times

version MinecraftVersion? The targeted version of Minecraft. Any packs that do not have atleast 1 version supporting this will be skipped.

mode 'datapack'|'resourcepack'|'both' = 'both' What should be downloaded, if both is specified then the datapack and resourcepack are served zipped within the download.

Possible Responses#

OK - 200 ArrayBuffer

SERVER_ERROR - 500 ApiError

Examples#

Download packs

fetch('https://api.smithed.dev/v2/download?pack=tcc&pack=manic&version=1.19')

/packs/:id#

GET#

Retrieve a pack's data

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Possible Responses#

OK - 200 PackData

NOT_FOUND - 404 ApiError

Examples#

Fetch a packs's data

fetch('https://api.smithed.dev/v2/packs/coc')

/packs/:id/contributors#

GET#

Get a list of contributors to a pack

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

Examples#

Set a packs's data

fetch('https://api.smithed.dev/v2/packs/coc/contributors')

POST#

Add a list of contributors to a pack

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Query Parameters#

token string Either Firebase Id Token or a valid PAT

contributors string[]

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Set a packs's data

fetch('https://api.smithed.dev/v2/packs/coc/contributors?token=NOT_TODAY_HAHA&contributors=CreeperMagnet_', {
  method:'POST'
})

DELETE#

Remove a list of contributors from a pack

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Query Parameters#

token string Either Firebase Id Token or a valid PAT

contributors string[]

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Set a packs's data

fetch('https://api.smithed.dev/v2/packs/coc/contributors?token=NOT_TODAY_HAHA&contributors=CreeperMagnet_', {
  method:'DELETE'
})

/packs/:id/meta#

GET#

Retrieve a pack's metadata

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Possible Responses#

OK - 200 PackMetaData

NOT_FOUND - 404 ApiError

Examples#

Set a packs's data

fetch('https://api.smithed.dev/v2/packs/coc/meta')

/packs/:id/versions#

GET#

Get the list of a pack's versions

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Possible Responses#

OK - 200 PackVersion

NOT_FOUND - 404 ApiError

Examples#

Get a pack's versions

fetch('https://api.smithed.dev/v2/packs/coc/versions')

POST#

Add to the list of a pack's versions

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Query Parameters#

token string Either Firebase Id Token or a valid PAT

version string The valid semver version number to assign

Body Parameters#

data PackVersion The data to add to the list

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Add a version to a pack

fetch('https://api.smithed.dev/v2/packs/coc/versions?token=FOO&version=0.0.1', {
  method: 'POST',
  body: {data: <PackVersion>},
  headers: {'Content-Type': 'application/json'}
})

/packs/:id/versions/:versionId#

PATCH#

Add to the list of a pack's versions

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup. versionId: The version number to target

Query Parameters#

token string Either Firebase Id Token or a valid PAT

Body Parameters#

data PackVersion The data to merge/overwrite with

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Add a version to a pack

fetch('https://api.smithed.dev/v2/packs/coc/versions/0.0.1?token=FOO', {
  method: 'PATCH',
  body: {data: <PackVersion>},
  headers: {'Content-Type': 'application/json'}
})

DELETE#

Add to the list of a pack's versions

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup. versionId: The version number to target

Query Parameters#

token string Either Firebase Id Token or a valid PAT

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Delete a version

fetch('https://api.smithed.dev/v2/packs/coc/versions/0.0.1?token=FOO', {
  method: 'DELETE',
})

/packs/:id/versions/latest#

DELETE#

Returns the latest version of the specified pack

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Query Parameters#

version MinecraftVersion? Optionally, get the latest version for the specified game version

Possible Responses#

OK - 200 PackVersion

NOT_FOUND - 404 ApiError

Examples#

Get the latest version for 1.19

fetch('https://api.smithed.dev/v2/packs/coc/versions/latest?version=1.19', {})

/packs#

GET#

Get a list of packs which meet the specified criteria

Query Parameters#

search string A search query against the name or id of the pack

sort SortOptions How to sort the requested data

limit int = 20 How many packs to send. Maximum of 100 per request.

start int = 0 How far into the queries should be counted

category PackCategory[]? Which categories should the pack be a part of

version MinecraftVersion[]? Which versions should the pack support

hidden boolean = false Should unlisted packs be returned.

scope string[]? A list of variable lookups starting with data. or meta.

Possible Responses#

OK - 200 {id: string, displayName: string, data?: any, meta?: any}

Examples#

Get a list of packs that are marked as Extensive and their descriptions

fetch('https://api.smithed.dev/v2/packs?category=Extensive&scope=data.display.description')

POST#

Upload a new pack to the plaform

Query Parameters#

token string Either Firebase Id Token or a valid PAT

id string The plaintext id for the pack

Body Parameters#

data PackData

Possible Responses#

OK - 200 {packId: string}

CONFLICT - 409 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Upload a new pack called foobar

fetch('https://api.smithed.dev/v2/packs/coc?token=NOT_TODAY_HAHA&id=foobar', {
  method:'POST',
  body: {data: <Pack Data>},
  headers: {'Content-Type': 'application/json'}
})

/packs/count#

GET#

Similar to /packs, this route returns the number of packs which match the criteria

Query Parameters#

search string A search query against the name or id of the pack

category PackCategory[]? Which categories should the pack be a part of

version MinecraftVersion[]? Which versions should the pack support

hidden boolean = false Should unlisted packs be returned.

Possible Responses#

OK - 200 number

Examples#

Number of packs which contain the

fetch('https://api.smithed.dev/v2/packs/count?search=the')

/sanitize#

GET#

Sanitize a value to a consistent format (Alphanumeric + - & _)

Query Parameters#

value string The value too properly sanitize

Possible Responses#

OK - 200 string

Examples#

Sanitize a username

fetch('https://api.smithed.dev/v2/sanitize?value=Jachro') // Returns "jachro"

/supported-versions#

GET#

Retrieve the list of all MinecraftVersion supported by the platform

Possible Responses#

OK - 200 MinecraftVersion[]

/tokens#

POST#

This route allows the creation of a PAT

Query Parameters#

token string Specifically a Firebase ID Token, not another PAT

expires string How long should the token be valid for, in the form `<h|>

name string? Name of token shown in the UI

scopes PermissionScope[]? = [] List of permissions for the token

Possible Responses#

OK - 200 {tokenDocId: string, tokenEntry: PAToken, token: string}

SERVER_ERROR - 500 ApiError

Examples#

Get a 1 day token

fetch('https://api.smithed.dev/v2/tokens?token=<ID Token Here>&expires=1d', {mode: "POST"})

GET#

This route gets all tokens owned by the user

Query Parameters#

token string Specifically a Firebase ID Token, not another PAT

Possible Responses#

OK - 200 {tokenDocId, tokenEntry: PAToken}[]

SERVER_ERROR - 500 ApiError

Examples#

Get all tokens

fetch('https://api.smithed.dev/v2/tokens?token=<ID Token Here>')

/tokens/:id#

DELETE#

This route deletes a given token

URL Parameters#

id: string: The Doc Id for the token

Query Parameters#

token string Specifically a Firebase ID Token, not another PAT

Possible Responses#

SERVER_ERROR - 500 ApiError

Examples#

Get a token

fetch('https://api.smithed.dev/v2/tokens/123456?token=<ID Token Here>')

/tokens/:id/refresh#

POST#

This refreshes a given token

URL Parameters#

id: string: The Doc Id for the token

Query Parameters#

token string Specifically a Firebase ID Token, not another PAT

Possible Responses#

OK - 200 {tokenEntry: PAToken, token: string}

SERVER_ERROR - 500 ApiError

Examples#

Get a token

fetch('https://api.smithed.dev/v2/tokens/123456?token=<ID Token Here>')

/users/:id/bundles#

GET#

Retrieve a specific users owned and contributed packs

URL Parameters#

id: The user's UID or plaintext username. Using UID is more performant as it is a direct lookup.

Possible Responses#

OK - 200 string[]

NOT_FOUND - 404 ApiError

Examples#

Fetch a user's bundles

fetch('https://api.smithed.dev/v2/users/TheNuclearNexus/bundles')

/users/:id#

GET#

Retrieve a specific users information

URL Parameters#

id: The user's UID or plaintext username. Using UID is more performant as it is a direct lookup.

Possible Responses#

OK - 200 {uid: string, cleanName: string, displayName: string, role: string}

NOT_FOUND - 404 ApiError

Examples#

Fetch a user's data

fetch('https://api.smithed.dev/v2/users/TheNuclearNexus')

PATCH/PUT#

Set a specific users information

URL Parameters#

id: The pack's UID or plaintext id. Using UID is more performant as it is a direct lookup.

Query Parameters#

token string Either Firebase Id Token or a valid PAT

Body Parameters#

data Omit<UserData, ['cleanName', 'creationTime', 'uid]>

Possible Responses#

OK - 200 string

NOT_FOUND - 404 ApiError

UNAUTHORIZED - 401 ApiError

FORBIDDEN - 403 ApiError

Examples#

Set a user's data

fetch('https://api.smithed.dev/v2/users/TheNuclearNexus?token=NOT_TODAY_HAHA', {
  method:'PATCH',
  body: {data: <User Data>},
  headers: {'Content-Type': 'application/json'}
})

/users/:id/pfp#

GET#

Retrieve a specific user's pfp

URL Parameters#

id: The user's UID or plain text username. Using UID is more performant as it is a direct lookup.

Possible Responses#

OK - 200 ArrayBuffer

NOT_FOUND - 404 ApiError

Examples#

Fetch a user's pfp

fetch('https://api.smithed.dev/v2/users/TheNuclearNexus/pfp')

/users/:id/packs#

GET#

Retrieve a specific users owned and contributed packs

URL Parameters#

id: The user's UID or plaintext username. Using UID is more performant as it is a direct lookup.

Possible Responses#

OK - 200 string[]

NOT_FOUND - 404 ApiError

Examples#

Fetch a user's data

fetch('https://api.smithed.dev/v2/users/TheNuclearNexus/packs')

/validate-download#

GET#

This route is used to ensure that a download url is valid and reachable by the Smithed servers.

Query Parameters#

url string The download url

Possible Responses#

OK - 200 {valid: boolean}

Examples#

Validate a github url

fetch('https://api.smithed.dev/v2/validate-download?url=' + encodeURIComponent(
  'https://github.com/TheNuclearNexus/CallOfChaos/releases/download/0.0.5/Call.of.Chaos.0.0.5.zip'
))