Upload a file
POST/projects/{projectId}/entities/{entityId}/uploadFile
Base URL: https://api.tinkermode.com
Upload a file associated with an entity instance. To upload a file, the client
must first acquire (an) upload URL(s) by using the open-upload action in the request body.
After completing the upload (by making a PUT request to the upload URL(s)), the client
must explicitly "close" the upload by using the close-upload action in the request body.
Authentication
Send an Authorization header of the form ModeCloud <AUTH_CODE>.
Must contain a device API key of a device belonging to the same home, a user API key of a user with permission to create entity files, a service account token with the entity file create permission, or a project API key with admin permissions.
Path parameters
| Name | Type | Required | Constraints | Description |
|---|---|---|---|---|
projectId | integer | Yes | The unique ID for a specified project. | |
entityId | string | Yes | Entity ID (unique within project) |
Request body
Content type: application/json
| Property | Type | Required | Constraints | Description | |||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
action | string | Yes | one of: open-upload, close-upload | Action to be taken. | |||||||||||||||||||||||||||||||||||
metadata | object | No | Metadata for the file. Required for the open-upload action. | ||||||||||||||||||||||||||||||||||||
| |||||||||||||||||||||||||||||||||||||||
numberOfParts | integer | No | Optional number of parts to split the upload into. Defaults to 1. | ||||||||||||||||||||||||||||||||||||
uploadId | string | No | Upload ID returned from the open-upload action. Required for the close-upload action. | ||||||||||||||||||||||||||||||||||||
Responses
200 For the open-upload action, this represents a successful start of the upload for a file. The response
body is a JSON object that contains an array of pre-signed upload URLs. The
client should divide up the file in the same number of parts as the number of URLs,
and upload each part to its corresponding URL with a PUT request.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
uploadId | string | No | Upload ID returned from the open-upload action. | |
urls | array<string> | No | URL to upload the entity file, or, URLs to upload each part of the entity file. |
204 For the close-upload action, this represents a successful completion of entity file upload.
401 Authorization is required to access this resource.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
403 Request failed because of invalid data or denied permission.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
429 Request failed because of rate limit.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
500 An unexpected error has occurred.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |
503 The service is temporarily unavailable.
Content type: application/json
| Property | Type | Required | Constraints | Description |
|---|---|---|---|---|
data | object | No | read-only (server-generated) | Any relevant data related to error. |
reason | string | Yes | read-only (server-generated) | Reason of error. |