describeValues

The "describeValues" action takes one or more keys and retrieves their previously stored values. The server looks up each key you specify. A key is case sensitive and must exactly match the key you used to store the value. 

The response includes matching key-value pairs in the "keyValuePairs" property. It includes keys it could not find in the "unmatchedKeys" property. It does not return an error. Each key-value pair also includes the following information: the key without its hierarchy, its creation date, last modified date, and the username of the account that last modified it.

This action returns the "keyWithoutHierarchy" property, which contains the leaf part of a hierarchical key. For example, given the key "myApp/queries/My Favorite" and a hierarchical delimiter of "/", the leaf part of the key is "My Favorite". This action uses the "hierarchyDelimiter" property to define the hierarchical delimiter so it can populate the "keyWithoutHierarchy" property.

 

How to use "describeValues"

Use the "keyStore" property to specify the keystore from which keys are returned. In the "keys" property, include one or more key strings. 

When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.

When using the "user" keystore, the action automatically uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to retrieve keys for other accounts.

If the response contains "errorCode": 0, then the request succeeded. The "keyValuePairs" property in the response contains an array of key-value pair objects: one for each matching key. The "unmatchedKeys" property in the response contains an array of key strings: one for each unmatched key. 

No additional information is included in the response to optimize network communication speed. If there is an error, the "errorMessage" property describes the problem.

Use the optional "hierarchyDelimiter" property to define a string, such as the forward slash character /, to delimit hierarchical levels in the key. It defaults to the empty string "", which causes the API to put no value in the "keyWithoutHierarchy" property. If you set it to a string, the action populates the "keyWithoutHierarchy" property, which contains the key's text following the last occurrence of the hierarchy delimiter. For example, given the key, "myApp/queries/My Favorite", the "keyWithoutHierarchy" property contains "My Favorite".

A key without its hierarchy is useful when an application lets users save items with user-defined names. The application can use the key-value API to store these items. To organize these items, the application typically creates a key like "myApp/queries/My Favorite". It uses a fixed hierarchical value at the beginning of the key, such as "myApp/queries/" and assigns the remainder of the key to the user-defined name for the item, such as "My Favorite". The "keyWithoutHierarchy" property contains the user-defined name.

 

Request examples

Global keystore

{
  "api": "db",
  "action": "describeValues",
  "params": {
    "keyStore": "global", 
    "keys": [ 
      "myKey", 
      "myApp/queries/My Favorite" 
    ],
    "hierarchyDelimiter": "/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Role keystore

The action uses the specified role and returns an error if the current session's account does not have that role. An administrator account may describe key-value pairs for any role.

{
  "api": "db",
  "action": "describeValues",
  "params": {
    "keyStore": "role", 
    "roleName": "operator",
    "keys": [ 
      "myKey"
    ],
    "hierarchyDelimiter": "/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore

The action automatically uses the session's username.

{
  "api": "db",
  "action": "describeValues",
  "params": {
    "keyStore": "user", 
    "keys": [ 
      "nonExistentKey"
    ],
    "hierarchyDelimiter": "/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

User keystore using elevated privileges

When an administrator account runs the action, it can optionally use the "username" property to specify the account of the key-value pair. This allows an elevated account to retrieve key-value pairs for other accounts.

{
  "api": "db",
  "action": "describeValues",
  "params": {
    "keyStore": "user", 
    "username": "someone_else", 
   "keys": [ 
      "myKey"
    ],
    "hierarchyDelimiter": "/"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Global keystore 

{
  "result": {
    "keyStore": "global", 
    "hierarchyDelimiter": "/",
    "keyValuePairDetails": [
      {
        "key": "myKey",
        "value": {"my": "value"},
        "keyWithoutHierarchy": "myKey",
        "username": "some_user", 
        "createdTimestamp": "2025-09-04T15:35:21.014",
        "updatedTimestamp": "2025-09-04T15:35:21.014"
      },
      {
        "key": "myApp/queries/My Favorite",
        "value": {"savedQuery": "favorite = 1"},
        "keyWithoutHierarchy": "My Favorite",
        "username": "some_user", 
        "createdTimestamp": "2025-09-04T15:35:21.014",
        "updatedTimestamp": "2025-09-04T15:35:21.014"
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

Role keystore 

{
  "result": {
    "keyStore": "role", 
    "roleName": "operator",
    "username": "me",
    "hierarchyDelimiter": "/",
    "keyValuePairDetails": [
      {
        "key": "myKey",
        "value": 1,
        "keyWithoutHierarchy": "myKey",
        "username": "some_user", 
        "createdTimestamp": "2025-09-04T15:35:21.014",
        "updatedTimestamp": "2025-09-04T15:35:21.014"
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore 

When the requested key does not exist, "keyValuePairDetails" is empty, but "unmatchedKeys" contains it.

{
  "result": {
    "keyStore": "user", 
    "username": "me",
    "hierarchyDelimiter": "/",
    "keyValuePairDetails": [],
    "unmatchedKeys": [ 
      "nonExistentKey" 
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

User keystore using elevated privileges

{
  "result": {
    "keyStore": "user", 
    "username": "someone_else", 
    "keyValuePairs": [
     { 
       "key": "myKey", 
       "value": "someone_else_value"
       "keyWithoutHierarchy": "myKey",
       "username": "someone_else", 
       "createdTimestamp": "2025-09-04T15:35:21.014",
       "updatedTimestamp": "2025-09-04T15:35:21.014"
      }
    ],
    "unmatchedKeys": []
  },
  "authToken": "replaceWithAuthTokenFromCreateSession",
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

hierarchyDelimiter

The "hierarchyDelimiter" property delimits hierarchical levels in the key. When set to "", this property defines no hierarchy. It may contain zero or more UTF-8 characters, such "/" or "||".

 

The "describeValues" action uses this string to calculate the "keyWithoutHierarchy" property, which contains the key's text following the last occurrence of the delimiter. If the "hierarchyDelimiter" property is "" or the action cannot find the delimiter string, it sets the "keyWithoutHierarchy" property to the whole key because the key does not contain a hierarchy.


Examples

  • Given the key, "myKey" and a hierarchy delimiter of "", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myKey" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myApp/queries/" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp||queries||" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp/queries/My Favorite" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "My Favorite".
  • Given the key, "myApp||queries||My Favorite" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "My Favorite".
     
 Optional with default of "" string 1 byte

keys

 The "keys" property contains an array of keys for an action to work on and return, such as [ "key1", "key2" ]. Required - No default value array of strings one or more key strings

keyStore

The "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role. An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 Required - No default value string enum

"global"

"role"

"user"

roleName

The "roleName" property specifies the key's role, which must match an RBAC role that exists in the server. It is not used with the other keystores. 


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 Required when "keystore": "role" string 1 to 64 bytes

username

The "username" property specifies the name that uniquely identifies the account. 

 

In "alter" actions, this property specifies the account that will be altered.

 

In Key-Value actions, the "username" property is optionally used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.
 

Required - No default value

 

Optional with default of the account name of the currently logged-in user for Key-Value actions

 

 string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

hierarchyDelimiter

The "hierarchyDelimiter" property is a string that delimits hierarchical levels in the key. It defaults to the empty string "", which defines no hierarchy. It may contain zero or more UTF-8 characters, such "/" or "||".

 

The "describeValues" action uses this string to calculate the "keyWithoutHierarchy" property, which contains the key's text following the last occurrence of the delimiter. If the "hierarchyDelimiter" property is "" or the action cannot find the delimiter string, it sets the "keyWithoutHierarchy" property to the whole key because the key does not contain a hierarchy.


Examples

  • Given the key, "myKey" and a hierarchy delimiter of "", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myKey" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "myKey".
  • Given the key, "myApp/queries/" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp||queries||" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "".
  • Given the key, "myApp/queries/My Favorite" and a hierarchy delimiter of "/", the "keyWithoutHierarchy" property contains "My Favorite".
  • Given the key, "myApp||queries||My Favorite" and a hierarchy delimiter of "||", the "keyWithoutHierarchy" property contains "My Favorite".
     
 string 1 byte

keyStore

The "keyStore" property specifies the keystore where the action stores and retrieves key-value pairs. There are three keystores: "global", "role", and "user".


The Simple Secure Key-Value API stores key-value pairs independently in each keystore; thus, the same key can exist in different keystores with different values. For example, the "settings/default/" key can exist in the global, user, and role keystores.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.


Within the user keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.


When using the "role" keystore, you must set the "roleName" property to the name of the role that owns the key-value pair. The action returns an error when the current user does not have the specified role.  An administrator account may set and get values for any role.


When using the "user" keystore, the action uses the session's username to identify the user's keys. When an administrator account runs the action, it can optionally use the "username" property to specify the user that owns the keys. This allows an elevated account to create and modify keys for other accounts.

 string enum

"global"

"role"

"user"

keyValuePairDetails

The "keyValuePairDetails" property contains an array of objects. Each object represents a key-value pair and contains extended information about a key and its value, including the "key", "value", "keyWithoutHierarchy", "username", "createdTimestamp", and "updatedTimestamp" properties.
 

{
  "key": "myKey",
  "value": {"my": "value"},
  "keyWithoutHierarchy": "myKey",
  "username": "some_user", 
  "createdTimestamp": "2025-09-04T15:35:21.014",
  "updatedTimestamp": "2025-09-04T15:35:21.014"
}
array of objects 
[
  { 
    "key": "k1",
    "value": 1,
    "keyWithoutHierarchy": "myKey",
    "username": "some_user",
    "createdTimestamp": "2025-09-04T15:35:21.014",
    "updatedTimestamp": "2025-09-04T15:35:21.014" 
  }
]

keyValuePairDetails

.createdTimestamp

 The "createdTimestamp" property is the date and time when something, such as a thing or key, was originally created in ISO 8601 format, such as "2025-08-28T10:47:13.041". It is never null. timestamp An ISO 8601 timestamp

keyValuePairDetails

.key

 The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value. string 1 to 128 bytes

keyValuePairDetails

.keyWithoutHierarchy

The "keyWithoutHierarchy" property contains the leaf part of a hierarchical key, which is the last part of a key following the hierarchical delimiter. For example, given the key "myApp/queries/My Favorite" and a / delimiter, the leaf part of the key is "My Favorite".


The "describeValuesFromHierarchy" action populates the "keyWithoutHierarchy" property with the part of the key following the value of the "partialKey" property.


The "describeValues" action populates the "keyWithoutHierarchy" property with the part of the key following the "hierarchyDelimiter" property.


How to use "keyWithoutHierarchy"


The "keyWithoutHierarchy" property is useful when an application lets users save items with user-defined names. An application defines the base part of a hierarchical key and the user defines the rest. For example, an application defines a base key of "myApp/queries/" and the user specifies a name, such as "My Favorite". The complete key is "myApp/queries/My Favorite". The "keyWithoutHierarchy" property contains the user-defined name, such as "My Favorite".


An application can use the "describeValuesFromHierarchy" action to return user-defined items that match a base key. Each match contains a "keyWithoutHierarchy" property, which is the user-defined name of an item. 

 string 1 to 128 bytes

keyValuePairDetails

.updatedTimestamp

 The "updatedTimestamp" property is the date and time when the thing was last updated. It is the same as the "createdTimestamp" property when the thing has never been updated. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

keyValuePairDetails

.username

The "username" property specifies the account name of a user or application.

It is required by the "createSession" action for authentication.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System limits for requirements of this and all other system properties.

In Key-Value actions, the "username" property is used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.

string

 

 

 1 to 64 bytes

keyValuePairDetails

.value

The "value" property associates a value with a label. It can be any JSON value that is associated with a label.

 

When you use the "alterLabel" action to update the "value" property, it replaces "value" with an entirely new value. It cannot replace parts of the JSON value.

 

In Key-Value actions, the "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 JSON 0 to 65,500 bytes

keyValuePairs

 The "keyValuePairs" property contains an array of objects. Each object represents a key-value pair and contains "key" and "value" properties, such as { "key": "k1",  "value": 1 }. array of key-value objects 
[
  { 
    "key": "myKey", 
    "value": 1
  }
]

keyValuePairs

.createdTimestamp

 The "createdTimestamp" property is the date and time when something, such as a thing or key, was originally created in ISO 8601 format, such as "2025-08-28T10:47:13.041". It is never null. timestamp An ISO 8601 timestamp

keyValuePairs

.key

 The "key" property is part of an optional key-value object that is defined in an array in the "userProperties" property. It is a user-defined string value. string 1 to 128 bytes

keyValuePairs

.keyWithoutHierarchy

The "keyWithoutHierarchy" property contains the leaf part of a hierarchical key, which is the last part of a key following the hierarchical delimiter. For example, given the key "myApp/queries/My Favorite" and a / delimiter, the leaf part of the key is "My Favorite".


The "describeValuesFromHierarchy" action populates the "keyWithoutHierarchy" property with the part of the key following the value of the "partialKey" property.


The "describeValues" action populates the "keyWithoutHierarchy" property with the part of the key following the "hierarchyDelimiter" property.


How to use "keyWithoutHierarchy"


The "keyWithoutHierarchy" property is useful when an application lets users save items with user-defined names. An application defines the base part of a hierarchical key and the user defines the rest. For example, an application defines a base key of "myApp/queries/" and the user specifies a name, such as "My Favorite". The complete key is "myApp/queries/My Favorite". The "keyWithoutHierarchy" property contains the user-defined name, such as "My Favorite".


An application can use the "describeValuesFromHierarchy" action to return user-defined items that match a base key. Each match contains a "keyWithoutHierarchy" property, which is the user-defined name of an item. 

 string 1 to 128 bytes

keyValuePairs

.updatedTimestamp

 The "updatedTimestamp" property is the date and time when the thing was last updated. It is the same as the "createdTimestamp" property when the thing has never been updated. It is returned in ISO 8601 format, such as "2025-08-28T10:47:13.041". timestamp ISO 8601 timestamp

keyValuePairs

.username

The "username" property specifies the account name of a user or application.

It is required by the "createSession" action for authentication.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System limits for requirements of this and all other system properties.

In Key-Value actions, the "username" property is used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.

string

 

 

 1 to 64 bytes

keyValuePairs

.value

The "value" property associates a value with a label. It can be any JSON value that is associated with a label.

 

When you use the "alterLabel" action to update the "value" property, it replaces "value" with an entirely new value. It cannot replace parts of the JSON value.

 

In Key-Value actions, the "value" property contains a JSON value, which may be up to 2 gigabytes in length. It can be any JSON value, such as an object, array, string, number, true, false, or null.

 JSON 0 to 65,500 bytes

roleName

The "roleName" property is required by the role keystore. It is not used with the other keystores. It specifies the key's role, which must match an RBAC role that exists in the server.


Within the role keystore, different roles can have the same key with different values. For example, the "operator" and "guest" roles can have their own "settings/default/" key and assign their own value to it.

 string 1 to 64 bytes

unmatchedKeys

The "unmatchedKeys" property contains a list of keys that an action could not find. An application can check this property to troubleshoot issues with key names.


The following actions look up keys by exact match and return this property:

  • "getValues"
  • "describeValues"
  • "deleteValues"
  • "renameKeys"
     
 array of strings zero or more key strings

username

The "username" property specifies the account name of a user or application.

It is required by the "createSession" action for authentication.

All API actions are performed in the context of the account identified by "username". For example, all tables created by an account are owned by the account. All queries use tables owned by the account.

In JSON DB API and JSON Hub API, use the "ownerName" property to cause an action to use a different account name than the value of "username". This allows an account to use tables created by another account and to create tables that are owned by another account.

Unlike other property names, such as "databaseName", "username" is all lowercase.

A zero-length username is invalid.

Note See System limits for requirements of this and all other system properties.

In Key-Value actions, the "username" property is used with the user keystore. It allows an administrator account or an account with the "keyValueAdmin" privilege to manage a key-value pair for another account; otherwise, the server automatically uses the session's account. This approach ensures that an ordinary account can only set and retrieve its own key-value pairs.


Within the User keystore, different users can have the same key with different values. For example, the "db" and "sam" users can have their own "settings/default/" key and assign their own value to it.

string

 

 

 1 to 64 bytes

 

 

Was this article helpful?

Give feedback about this article

Related Articles