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 the 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 by 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 to 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 of 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 send 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.