Create data upload job

POST/homes/{homeId}/dataUploads

Base URL: https://api.tinkermode.com

Create a new data upload job for the home. The catalogId and sourceId must map to a valid data source. The deviceId field is only required if the relevant data source also has a device ID associated with it.

Early Access: This feature is in early access and may change. Pricing and availability are under review. For questions or issues, contact your delivery team.

Authentication

Send an Authorization header of the form ModeCloud <AUTH_CODE>.

Must contain the API key of a user or service account who has the permission to create data upload jobs of a home or a Project API Key with "Admin" privileges.

Path parameters

Name	Type	Required	Constraints	Description
`homeId`	integer	Yes		The unique ID for a specified home.

Request body

Content type: application/json

Property	Type	Required	Constraints	Description
`catalogId`	string	Yes	read-only (server-generated)	Catalog ID of the data source from which the data file originated.
`completedTime`	string	No	read-only (server-generated); format: date-time	If the data upload is fully processed, the completion time is included here.
`deviceId`	number	No	read-only (server-generated)	ID of the device/gateway from which the data file originated. Optional.
`errorMessage`	string	No	read-only (server-generated)	If upload has failed, an error messages will be included here.
`fileName`	string	Yes	read-only (server-generated)	Name of data file.
`homeId`	number	Yes	read-only (server-generated)	ID of home targeted by the upload.
`id`	number	Yes	read-only (server-generated)	Unique ID assigned to upload request.
`importedRecords`	number	Yes	read-only (server-generated)	Number of data reocrds imported so far.
`percentageComplete`	number	Yes	read-only (server-generated); min: 0; max: 1	Percentage of the data file that has been imported.
`projectId`	number	Yes	read-only (server-generated)	ID of the project associated to this request.
`sourceId`	string	Yes	read-only (server-generated)	ID of the data source from which the data file originated.
`state`	string	Yes	read-only (server-generated); one of: waiting_for_upload, upload_complete, in_progress, completed, failed_input_error, failed_system_error, cancel_requested, cancel_completed	Current state of the upload request.
`uploadUrl`	string	No	read-only (server-generated)	The URL for uploading the data file.

Request example

{
  "catalogId": "D201",
  "deviceId": 12345,
  "fileName": "data_file.csv",
  "sourceId": "xyzzy-123"
}

Responses

`201` Successful creation of data upload job.

Content type: application/json

Response example

{
  "catalogId": "D201",
  "deviceId": 12345,
  "fileName": "humidity_data.csv",
  "homeId": 1234,
  "id": 50,
  "importedRecords": 0,
  "percentageComplete": 0,
  "projectId": 1234,
  "sourceId": "xyzzy-123",
  "state": "waiting_for_upload",
  "uploadUrl": "https://tinkermode-home-data-uploads.s3.us-west-2.amazonaws.com/1234/1234/f770f4c9-a7ad-4c56-8d74-c71a57f669da?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLE/20250904/us-west-1/s3/aws4_request&X-Amz-Date=20250904T120000Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=EXAMPLESIGNATURE"
}

`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 permission to create home data upload sub-resource is missing or invalid data.

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.