StarDots.io Logo

StarDots

Documentation home

Open API

This chapter will introduce how to integrate open APIs. The following knowledge is for developers, and we assume that you have a certain programming foundation.

Are you an AI agent? Read the Markdown docs
On this page

Authentication

StarDots performs authentication by reading the headers field in the http request initiated by the client and verifying the relevant fields. Therefore, all open API requests should carry these authentication field information, and you need to note that these fields are case-sensitive and all fields should be lowercase.

  • x-stardots-timestamp
    Description
    Current timestamp in seconds. The difference with the StarDots server cannot exceed 60 seconds. Note: The time zone of StarDots is Asia/Singapore, which is UTC+8.
  • x-stardots-nonce
    Description
    A random string of 4 to 20 characters, which can only contain uppercase letters, lowercase letters, and numbers. Note that this value must be unique within 60 seconds.
  • x-stardots-key
    Description
    Key information issued by StarDots.
  • x-stardots-sign
    Description
    The signature field is a string generated by combining the above fields according to a certain signature algorithm. The specific signature algorithm will be introduced next.

Signature algorithm

We assume the following field values

key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
secret
Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp
x-stardots-timestamp
1728958751
x-stardots-nonce
fQvDmMLnKE
x-stardots-key
2dcded8e-f231-4d0a-8498-d10ef0639eb3
Key and Secret are issued by StarDots, you can find them in the console settings page.

Then we assemble the above field values

needSignStr = x-stardots-timestamp + "|" + secret + "|" + x-stardots-nonce

Next, we calculate the MD5 digest of the string assembled above

signStrAfterMD5 = md5("1728958751|Ey1JNRCiJOzaIOIilcyJvteTn5YXykFXUwmiHLymK8LHkITfGPo5mTUdLlg0jPHST9fMwMZKxIKUBvSsT5uxrq0lXuerll3eRW2tbMOsvySRY539L8cR6iRFV2DQqdlzbseyq7k9N0U5pZgj6f43e3MngbIttgSDl1G44IBOwqsI2HVXE5H6mf1bHlvWw6Ziuk8Xcw18AioG47SFBLIatrq6E9yEBJgFgcYysCH8JvY659hhqI3Ii1CA5zVtyNp|fQvDmMLnKE")
signStrAfterMD5 = "51dabfe4b47e73d4a3b85fe29c4f1e82"

Finally we convert the summary string to uppercase

sign = signStrAfterMD5.toUpperCase()
sign = "51DABFE4B47E73D4A3B85FE29C4F1E82"

Therefore, the final value of the x-stardots-sign field is 51DABFE4B47E73D4A3B85FE29C4F1E82

Common HTTP response body

All interface responses maintain a unified data structure

  • code
    Data type
    number
    Required
    Yes
    Description
    Service response code. 200 indicates success.
  • message
    Data type
    string
    Required
    Yes
    Description
    Message prompt of the operation result.
  • requestId
    Data type
    string
    Required
    Yes
    Description
    A unique number for the request, which can be used for troubleshooting.
  • success
    Data type
    boolean
    Required
    Yes
    Description
    Indicates whether the business operation is successful.
  • ts
    Data type
    number
    Required
    Yes
    Description
    Server millisecond timestamp.
  • data
    Data type
    any
    Required
    Yes
    Description
    Business data field. This field can be of any data type. For specific data types, please refer to the corresponding interface.

Functional Interface

Note that all interfaces will have request rate limits, and all interfaces share a set of rate limit rules. So far, StarDots' rate limit is 300 times per minute.

Request endpoint

https://api.stardots.io

Space List

Get space list data.

Request method
GET
Request path
/openapi/space/list
Request content type
application/json
Response content type
application/json

Request parameters

  • page
    Data type
    number
    Required
    No
    Description
    Page number, default value is 1.
  • pageSize
    Data type
    number
    Required
    No
    Description
    The number of entries per page ranges from 1 to 100, and the default value is 20.

Request demo

/openapi/space/list?page=1&pageSize=50

Response fields

  • name
    Data type
    string
    Required
    Yes
    Description
    The name of the space.
  • public
    Data type
    boolean
    Required
    Yes
    Description
    Whether the accessibility of the space is false.
  • createdAt
    Data type
    number
    Required
    Yes
    Description
    The system timestamp in seconds when the space was created. The time zone is UTC+8.
  • fileCount
    Data type
    number
    Required
    Yes
    Description
    The number of files in this space.

Response demo

{
    "code": 200,
    "data": [
        {
            "createdAt": 1723789637,
            "fileCount": 2,
            "name": "star",
            "public": true
        }
    ],
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

Create Space

Create a new space.

Request method
PUT
Request path
/openapi/space/create
Request content type
application/json
Response content type
application/json

Request parameters

  • space
    Data type
    string
    Required
    Yes
    Description
    The name of the space. It can only be a combination of letters or numbers, and the length is 4 to 15 characters.
  • public
    Data type
    boolean
    Required
    No
    Description
    Specifies whether the space is publicly accessible. The default value is false.

Request demo

{
    "public": false,
    "space": "stardots"
}

Response fields

No fields

Response demo

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

Delete Space

Delete an existing space. Note that you must ensure that there are no files in this space, otherwise the deletion will fail.

Request method
DELETE
Request path
/openapi/space/delete
Request content type
application/json
Response content type
application/json

Request parameters

  • space
    Data type
    string
    Required
    Yes
    Description
    The name of the space. It can only be a combination of letters or numbers, and the length is 4 to 15 characters.

Request demo

{
    "space": "stardots"
}

Response fields

No fields

Response demo

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

Space accessibility

Toggle the accessibility of a space.

Request method
POST
Request path
/openapi/space/accessibility/toggle
Request content type
application/json
Response content type
application/json

Request parameters

  • space
    Data type
    string
    Required
    Yes
    Description
    The name of the space. It can only be a combination of letters or numbers, and the length is 4 to 15 characters.
  • public
    Data type
    boolean
    Required
    No
    Description
    Specifies whether the space is publicly accessible. The default value is false.

Request demo

{
    "public": false,
    "space": "stardots"
}

Response fields

No fields

Response demo

{
    "code": 200,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

File list in space

Get the list of files in the space. The list is sorted in descending order by file upload time.

Request method
GET
Request path
/openapi/file/list
Request content type
application/json
Response content type
application/json

Request parameters

  • space
    Data type
    string
    Required
    Yes
    Description
    The name of the space. It can only be a combination of letters or numbers, and the length is 4 to 15 characters.
  • page
    Data type
    number
    Required
    No
    Description
    Page number, default value is 1.
  • pageSize
    Data type
    number
    Required
    No
    Description
    The number of entries per page ranges from 1 to 100, and the default value is 20.

Request demo

{
    "space": "stardots",
    "page": 1,
    "pageSize": 20
}

Response fields

  • page
    Data type
    number
    Required
    Yes
    Description
    Page number, default value is 1.
  • pageSize
    Data type
    number
    Required
    Yes
    Description
    The number of entries per page ranges from 1 to 100, and the default value is 20.
  • totalCount
    Data type
    number
    Required
    Yes
    Description
    The total number of entries.
  • list
    Data type
    array<object>
    Required
    Yes
    Description
    File list array.
  • list.name
    Data type
    string
    Required
    Yes
    Description
    The name of the file.
  • list.byteSize
    Data type
    number
    Required
    Yes
    Description
    The size of the file in bytes.
  • list.size
    Data type
    string
    Required
    Yes
    Description
    File size, formatted for readability.
  • list.uploadedAt
    Data type
    number
    Required
    Yes
    Description
    The timestamp of the file upload in seconds. The time zone is UTC+8.
  • list.url
    Data type
    string
    Required
    Yes
    Description
    The access address of the file. Note that if the accessibility of the space is private, this field value will carry the access ticket, which is valid for 20 seconds.

Response demo

{
    "code": 0,
    "data": {
        "list": [
            {
                "byteSize": 3600000,
                "name": "star",
                "size": "35KB",
                "uploadedAt": 1723789637,
                "url": "https://....."
            }
        ],
        "page": 1,
        "pageSize": 10,
        "totalCount": 1
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

File access ticket

Get the access ticket for the file. When the accessibility of the space is private, you need to bring the access ticket to access the files under the space, otherwise the request will be rejected.

Request method
POST
Request path
/openapi/file/ticket
Request content type
application/json
Response content type
application/json

Request parameters

  • space
    Data type
    string
    Required
    Yes
    Description
    The name of the space. It can only be a combination of letters or numbers, and the length is 4 to 15 characters.
  • filename
    Data type
    string
    Required
    Yes
    Description
    The name of the file.

Request demo

{
    "filename": "1.jpg",
    "space": "stardots"
}

Response fields

  • ticket
    Data type
    string
    Required
    Yes
    Description
    Access Ticket.

Response demo

{
    "code": 200,
    "data": {
        "ticket": "a312.."
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

File upload

Upload the file to the space. Note that this request requires you to initiate the request in the form of a form.

Request method
PUT
Request path
/openapi/file/upload
Request content type
multipart/form-data
Response content type
application/json

Request parameters

  • space
    Data type
    string
    Required
    Yes
    Description
    The name of the space. It can only be a combination of letters or numbers, and the length is 4 to 15 characters.
  • file
    Data type
    binary
    Required
    Yes
    Description
    The binary stream of the file. Note that the file name must not exceed 170 characters. The file size cannot exceed 10MB.

Response fields

  • space
    Data type
    string
    Required
    Yes
    Description
    The name of the space. It can only be a combination of letters or numbers, and the length is 4 to 15 characters.
  • filename
    Data type
    string
    Required
    Yes
    Description
    The name of the file.
  • url
    Data type
    string
    Required
    Yes
    Description
    The access link of the file. If the accessibility of the space is private, the access link will carry the access ticket.

Response demo

{
    "code": 200,
    "data": {
        "filename": "1.png",
        "space": "space",
        "url": "https://i.stardots.io/space/1.png"
    },
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

Delete files

Delete files in the space. This interface supports batch operations.

Request method
DELETE
Request path
/openapi/file/delete
Request content type
application/json
Response content type
application/json

Request parameters

  • space
    Data type
    string
    Required
    Yes
    Description
    The name of the space. It can only be a combination of letters or numbers, and the length is 4 to 15 characters.
  • filenameList
    Data type
    array<string>
    Required
    Yes
    Description
    Array of file names.

Request demo

{
    "filenameList": ["1.jpg", "2.jpg"],
    "space": "stardots"
}

Response fields

No fields

Response demo

{
    "code": 0,
    "data": null,
    "message": "SUCCESS",
    "requestId": "5686efa5-c747-4f63-8657-e6052f8181a9",
    "success": true,
    "ts": 1670899688591
}

Server response codes

Server response codes are the response codes returned by the server to the client, used to represent the result of server processing the request.

  • 200
    Description
    Success
  • 504
    Description
    Request timeout
  • 999999
    Description
    Server internal error
  • 100000
    Description
    Request parameter error
  • 100001
    Description
    Access token invalid
  • 100002
    Description
    Human verification failed
  • 100003
    Description
    Verification code incorrect
  • 100004
    Description
    Account does not exist
  • 100005
    Description
    Account password does not match
  • 100006
    Description
    Subscription plan does not exist
  • 100007
    Description
    SMS/email sending too frequently
  • 100008
    Description
    SMS/email sending limit exceeded
  • 100009
    Description
    Space/bucket does not exist
  • 100010
    Description
    Space/bucket already exists
  • 100011
    Description
    Space/bucket is not empty
  • 100012
    Description
    Operation too frequent
  • 100013
    Description
    Space/bucket quantity quota reached the upper limit
  • 100014
    Description
    File quantity quota reached the upper limit
  • 100015
    Description
    Traffic transfer quota exhausted
  • 100016
    Description
    Subscription plan does not match
  • 100017
    Description
    Space/bucket file access restricted
  • 100018
    Description
    File exceeds size limit
  • 100019
    Description
    File format not supported
  • 100020
    Description
    Referer not allowed
  • 100021
    Description
    Function only open to Pro or Premium users
  • 100022
    Description
    Function only open to Premium users
  • 100023
    Description
    Certificate content invalid
  • 100024
    Description
    Certificate and private key do not match
  • 100025
    Description
    Invalid image MIME type
  • 100026
    Description
    File access link expired
  • 100027
    Description
    API call limit reached
  • 100028
    Description
    Batch operations only open to paid users
  • 100029
    Description
    Image link invalid
  • 100030
    Description
    Account suspended due to violation of terms

SDK

StarDots provides SDKs for various programming languages to help you quickly integrate with our API. You can find the SDKs in the following links:

If you encounter any problems, please contact us