v0.0.3
Official Docs all rights reserved under SnailDOS
Endpoint is available at https://api.snaildos.com
All responses follow a certain template that reports if the requested action was successful or not.
All requests return a status property indicating if the action was successful or not
If an action is successful it follows this template under two conditions.
If the requested action fetches a certain document from the database it returns all the data that is accessible based on the user privileges
For example, fetching a user:
{
"status": true,
"user": {
"id": "string",
"createdAt": "number",
"scopes": "string[]",
"email": "string",
"name": "string",
"verified": "boolean"
}
}
/!\ This has a single exception which is the “fetch currently playing” endpoint. (Refer to the proper section of the documentation for more)
If the requested action modifies, deletes, to posts a certain document from the database (for example, register user) it returns data that has been modified a consequence of the requested action or if the content was created it returns important data to access the newly created data
For example, registering a new user:
{
"status": true,
"token": "string"
}
If an action has failed it follows this template under all conditions.
{
"status": false,
"message": "string"
//...other properties may follow as details to what went wrong.
}
Failed actions provide an appropriate status code for what went wrong.
Some parts of the documentation may include status codes explaining the issues related to what went wrong
429: Too many requests
{
"status": false,
"global": true,
"message": "too many requests",
"try_again": "number" //Time in milliseconds
}
{
"status": false,
"global": false,
"message": "too many requests",
"bucketKey": "string", //Unique bucket key generated to identify the action executed by the user
"try_again": "number" //Time in milliseconds
}
408: Request time out
{
"status": false,
"message": "request timeout"
}
415: Unsupported media type
{
"status": false,
"message": "unsupported media type"
}
400: Invalid body provided
{
"status": false,
"message": "invalid body provided"
}
500: Internal server error
{
"status": false,
"message": "Internal server error"
}
404: Endpoint was not found
{
"status": false,
"method": "string",
"url": "url",
"message": "endpoint was not found"
}
Currently identification only allows user token, Oauth2 bearer tokens are planned for certain endpoints.
To identify a user append to the request an authorization header.
The server could respond with the following errors if the validation of the authorization header failed:
403: The user that owns the provided token does not have the proper scopes (permissions) to execute this action.
401: The user has failed the header validation
02-applications
This endpoint allows you to access public information of an application
{
"status": true,
"application": {
"id": "string",
"callback_urls": "string[]",
"image": "string",
"name": "string"
}
}
03-radio
This endpoint allows you to access public information about what the radio is currently playing
{
"status": true,
"playing": "string | null",
"url": "youtubeurlforlivestream"
}
Again using authentication in the headers it will show what the radio is playing with a lower ratelimit
{
"status": true,
"playing": "string | null",
"url": "youtubeurlforlivestream"
}
04-users
This endpoint allows the client to create a new user
To perform this action a body with the following schema is required:
{
"email": "string", //Should be of an email format
"name": "string",
"pass": "string", //Should be longer or equal 15 characters in length and smaller than or equal to 300 characters in length,
"captcha": "string" //Should be a valid hcaptcha response token
}
If the action is successful a response following this schema should be received.
{
"status": true,
"token": "string"
}
To perform this action a body with the following schema is required:
{
"verificationCode": "string" //Should be the code received by email from the user
}
If the action is successful a response following this schema should be received.
{
"status": true
}
To perform this action a body with the following schema is required:
{
"email": "string", //Should be a valid user email
"pass": "string", //Should be the correct user password
"captcha": "string" //Should be a valid hcaptcha token
}
If the action is successful a response following this schema should be received.
{
"status": true,
"token": "string"
}
If the action is successful a response following this schema should be received.
{
"status": true,
"user": {
"id": "string",
"createdAt": "number",
"scopes": "string[]",
"email": "string",
"name": "string",
"verified": "boolean"
}
}
To perform this action send a body following this schema
{
"email"?:"string",//Should be a valid new email that is neither already used or the current user's email.
"name"?: "string",//Should not be equal to the user's current name
"pass"?: "string",//Should not be equal to the user's current password,
"originalPassword": "string",//Should be the user's current password to validate their identity.
"captcha": "string"//Should be a valid hcaptcha response token.
}
email,name,pass are all optional properties, but at least one of them should be passed
{
"status": true,
"verified": "boolean",
"updated": "(email|name|pass)[]"
}
To perform this action the user should not have started a deletion sequence.
If the action is successful a response following this schema should be received.
{
"status": true
}
To perform this action the user should have already started a deletion sequence and sent a body following this schema
{
"deleteCode": "string" //Should be the deletion code received by email
}
If the action is successful a response following this schema should be received.
{
"status": true
}
We use hCaptcha for our captcha system.
a04b537a-17d4-4a34-9092-ca0583ce459e
You will need our site key above to interact with our API and return a completed captcha response.
Please refer to https://docs.hcaptcha.com/ to add our captcha into your site and interact with our API.