Create a data set object

Create an individual object on a data set:

POST https://ip-or-hostname/io/api/1/dataset/:id
curl \
	-X POST \
	-d key=:apiKey \
	https://ip-or-hostname/io/api/1/dataset/:id

This method will create a new record in a given data set where:

  • :apiKey is the API key to use for access (see below)
  • :id is the data set id (a UUID), per the /datasets API. The data set ID can also be found in the Data set inspector of the Data tab for the data set.

Note that you will most likely wish to pass other parameters as well to set values. The specific names of these parameters depend upon your data set schema. Please see below.

Query parameters

  • N/A

Body parameters

  • clientId string
    A unique id for the client accessing the table on your system. While this is optional it is a recommended parameter as it is useful for tracking requests in CloudTables' analytics.
  • clientName string
    A label that can help identify a user - e.g. a name or e-mail address. Typically the clientId will be an integer or UUID which mean you'd need to look up the user to understand who made what changes. Note that while the clientId should be unique per client and not change - the clientName can change and will be updated to reflect the latest value given (e.g. if a user modifies their name in your own system). Similar to role but allows multiple roles to be specified.
  • dp-{number} string Recommended
    Values that should be given to the data points in the data set. To get the data point id's please use the schema API or refer to the "ID" for the data point which can be found in the Data set inspector of the Data tab for the data set. The number of dp-{number} parameters will depend upon the number of data points configured for the data set. Each is optional (unless a "Required" validator is set for the data point) and will take the default value if not specified.
  • key string Required Header
    The API key which will allow access (and thus assign the roles that can be used for access). Note that this option can be also be provided as an HTTP header (also with the name key).
  • l-{number} number | number[] Recommended
    Values that should be used to establish a link to another data set. To get the link id's please use the schema API or refer to the "ID" for the link which can be found in the Data set inspector of the Data tab for the data set. The values to give should match the id property of the data set entries you wish to link to. Note that to remove all links, you must send an empty array for the link property.
  • role string
    The name of the role that should be used for access (if assigned to the API key - if the role is not available for the API key no access will be granted). If not provided then all roles available to the API key will be used.
  • roles string[]
    Similar to role but allows multiple roles to be specified.

Result

The JSON result will contain the data object for the row, if there are no errors, in the same structure as the individual row request route. Additionally, if any errors are reported there may be error and fieldError properties. If there are no errors, the error properties will not be present.

{
    "data": {
        "id": number,
        "dv": number,
        // ... data values
    },
    "error": string,         // General error information
    "fieldErrors": [
        {
            "name": string,  // Name of the data point in error
            "status": string // Error message
        }
    ]
}

Example

Consider the following being sent to our example data set for flights. It has a string field for the flight name and two links for the departure and arrival airports, in keeping with the example use for the data fetch examples:

curl \
	-X POST \
	-d key=:apiKey \
	-d dp-11=MyFlight \
	-d l-5=11 \
	-d l-6=3 \
	https://ip-or-hostname/io/api/1/dataset/:id

Will result in the following JSON return:

{
	"data": {
		"id": 27,
		"dv": 0,
		"dp-11": "MyFlight",
		"l-5": [{
			"id": 11,
			"dp-8": "Aberdeen"
		}],
		"l-6": [{
			"id": 3,
			"dp-8": "Bristol"
		}]
	},
	"success":true
}