The custom data API can be used to add arbitrary data to your Data Cloud instance. It allows you to store value JSON objects by unique reference and key pairs. The records are stored in the custom_data table that is queryable alongside all of your other Data Cloud data.

For more information about the supported SQL operators and functions available for querying the JSON values please reference the PostgreSQL documentation.

API methods

customData.get
customData.set
customData.setAll
customData.delete

customData.get

Retrieve a record based on unique reference and key pair, or ID.

Required Arguments

If looking up by reference and key pair:

Name	Description
reference	String - The domain reference.
key	String - The domain key.

If looking up by ID:

Name	Description
id	String - Generated unique ID for the record.

Response

Name	Description
id	String - Generated unique ID for the record.
reference	String - The received reference argument.
key	String - The received key argument.
value	JSON Object - The received value argument.
timestamp	String - ISO8601 timestamp. The received timestamp argument, or generated timestamp.

Example

curl https://yourinstance.getdx.net/api/customData.get?reference=orgname/repo&key=example \
  -H 'Accepts: application/json' \
  -H 'Authorization: Bearer your_bearer_token_here'

customData.set

Creates or updates the record by unique reference and key pair.

Required Arguments

Name	Description
reference	String - The domain reference.
key	String - The domain key.
value	JSON Object - The object to be stored.

Optional Arguments

Name	Description
timestamp	String - ISO8601 timestamp. This will default to when the request is received if not included.

Response

Name	Description
id	String - Generated unique ID for the record.
reference	String - The received reference argument.
key	String - The received key argument.
value	JSON Object - The received value argument.
timestamp	String - ISO8601 timestamp. The received timestamp argument, or generated timestamp.

Example

curl -X POST https://yourinstance.getdx.net/api/customData.set \
  -H 'Accepts: application/json' \
  -H 'Authorization: Bearer your_bearer_token_here' \
  -H 'Content-Type: application/json' \
  --data '{
    "reference”: “orgname/repo”,
    "key”: “example”,
    "value”: { “version”: “1.2.3” },
    "timestamp": "2024-01-01T11:22:33"
  }'

customData.setAll

Creates or updates multiple records. Each record contains a reference and key pair to identify it, then a value and an optional timestamp.

Required Arguments

Name	Description
data	JSON Array - A list of custom data objects (see below)

Data objects: Required Arguments

Name	Description
reference	String - The domain reference.
key	String - The domain key.
value	JSON Object - The object to be stored.

Data objects: Optional Arguments

Name	Description
timestamp	String - ISO8601 timestamp. This will default to when the request is received if not included.

Response

Name	Description
data	JSON Array - The stored objects. IDs will be available for both edited and newly-inserted objects.

Response: data objects

Name	Description
id	String - Generated unique ID for the record.
reference	String - The received reference argument.
key	String - The received key argument.
value	JSON Object - The received value argument.
timestamp	String - ISO8601 timestamp. The received timestamp argument, or generated timestamp.

Example

curl -X POST https://yourinstance.getdx.net/api/customData.setAll \
  -H 'Accepts: application/json' \
  -H 'Authorization: Bearer your_bearer_token_here' \
  -H 'Content-Type: application/json' \
  --data '{
    "data": [
      {
        "reference": "orgname/repo",
        "key": "example",
        "value": { "version": "1.2.3" },
        "timestamp": "2024-01-01T11:22:33"
      },
      {
        "reference": "orgname/other-repo",
        "key": "other-example",
        "value": { "version": "4.5.6" },
        "timestamp": "2024-01-01T11:22:33"
      }
    ]
  }'

Note that if any items are malformed, the complete request will be rejected and no upserts will be made.

customData.delete

Delete a record based on unique reference and key pair, or ID.

Required Arguments

If looking up by reference and key pair:

Name	Description
reference	String - The domain reference.
key	String - The domain key.

If looking up by ID:

Name	Description
id	String - Generated unique ID for the record.

Response

Name	Description
id	String - Generated unique ID for the record.
reference	String - The received reference argument.
key	String - The received key argument.
value	JSON Object - The received value argument.
timestamp	String - ISO8601 timestamp. The received timestamp argument, or generated timestamp.

Example

curl -X POST https://yourinstance.getdx.net/api/customData.delete \
  -H 'Accepts: application/json' \
  -H 'Authorization: Bearer your_bearer_token_here' \
  -H 'Content-Type: application/json' \
  --data '{
    "reference”: “orgname/repo”,
    "key”: “example”
  }'