# StarDots OpenAPI

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.

[Web documentation](https://stardots.io/en/documentation/openapi) · [Pricing and quotas](https://stardots.io/pricing.md)

Base URL: `https://api.stardots.io`

## 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.

| Name | Description |
| --- | --- |
| `x-stardots-timestamp` | 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` | 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` | Key information issued by StarDots. |
| `x-stardots-sign` | 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

Key and Secret are issued by StarDots, you can find them in the console settings page.

Join the timestamp, your secret, and the nonce with literal pipe characters. Hash the result with MD5 and uppercase the hexadecimal digest. Send that digest as the `x-stardots-sign` header.

```text
input = timestamp + "|" + secret + "|" + nonce
x-stardots-sign = uppercase(hex(MD5(input)))
```

## Common HTTP response body

All interface responses maintain a unified data structure

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

## Endpoints

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.

### Space List

Get space list data.

- Request: `GET /openapi/space/list`
- Request content type: `application/json`
- Response content type: `application/json`

#### Request parameters

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

#### Request example

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

#### Response fields

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

#### Response example

```json
{
    "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: `PUT /openapi/space/create`
- Request content type: `application/json`
- Response content type: `application/json`

#### Request parameters

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

#### Request example

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

#### Response fields

No fields

#### Response example

```json
{
    "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: `DELETE /openapi/space/delete`
- Request content type: `application/json`
- Response content type: `application/json`

#### Request parameters

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

#### Request example

```json
{
    "space": "stardots"
}
```

#### Response fields

No fields

#### Response example

```json
{
    "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: `POST /openapi/space/accessibility/toggle`
- Request content type: `application/json`
- Response content type: `application/json`

#### Request parameters

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

#### Request example

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

#### Response fields

No fields

#### Response example

```json
{
    "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: `GET /openapi/file/list`
- Request content type: `application/json`
- Response content type: `application/json`

#### Request parameters

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

#### Request example

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

#### Response fields

| Name | Data type | Required | Description |
| --- | --- | --- | --- |
| `page` | `number` | Yes | Page number, default value is 1. |
| `pageSize` | `number` | Yes | The number of entries per page ranges from 1 to 100, and the default value is 20. |
| `totalCount` | `number` | Yes | The total number of entries. |
| `list` | `array<object>` | Yes | File list array. |
| `list.name` | `string` | Yes | The name of the file. |
| `list.byteSize` | `number` | Yes | The size of the file in bytes. |
| `list.size` | `string` | Yes | File size, formatted for readability. |
| `list.uploadedAt` | `number` | Yes | The timestamp of the file upload in seconds. The time zone is UTC+8. |
| `list.url` | `string` | Yes | 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 example

```json
{
    "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: `POST /openapi/file/ticket`
- Request content type: `application/json`
- Response content type: `application/json`

#### Request parameters

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

#### Request example

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

#### Response fields

| Name | Data type | Required | Description |
| --- | --- | --- | --- |
| `ticket` | `string` | Yes | Access Ticket. |

#### Response example

```json
{
    "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: `PUT /openapi/file/upload`
- Request content type: `multipart/form-data`
- Response content type: `application/json`

#### Request parameters

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

#### Response fields

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

#### Response example

```json
{
    "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: `DELETE /openapi/file/delete`
- Request content type: `application/json`
- Response content type: `application/json`

#### Request parameters

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

#### Request example

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

#### Response fields

No fields

#### Response example

```json
{
    "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.

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

- [Go](https://github.com/stardots-io/stardots-sdk-go)
- [Java](https://github.com/stardots-io/stardots-sdk-java)
- [C#](https://github.com/stardots-io/stardots-sdk-csharp)
- [Python](https://github.com/stardots-io/stardots-sdk-python)
- [Typescript](https://github.com/stardots-io/stardots-sdk-ts)
- [C++](https://github.com/stardots-io/stardots-sdk-cpp)
- [Rust](https://github.com/stardots-io/stardots-sdk-rust)
- [PHP](https://github.com/stardots-io/stardots-sdk-php)
- [Ruby](https://github.com/stardots-io/stardots-sdk-ruby)
- [V](https://github.com/stardots-io/stardots-sdk-v)
- [Swift](https://github.com/stardots-io/stardots-sdk-swift)
- [Kotlin](https://github.com/stardots-io/stardots-sdk-kotlin)
- [Dart](https://github.com/stardots-io/stardots-sdk-dart)
