Forge Key-Value Store (KVS) API endpoints for storing and retrieving data in key-value pairs.
API Documentation: Forge REST API - KVS/Custom Entity Store
The Forge KVS API provides hosted storage capabilities that let you store data in your app installation. Use the /forge/storage/kvs/{target} endpoint to proxy requests to the Forge KVS REST API.
Gets a value by key.
storage:appstring
Requiredstring
RequiredGetOptions
Successfully retrieved the value corresponding to the key.
1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/get' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>",
"options": {
"metadataFields": [
"CREATED_AT"
]
}
}'1
2
3
4
5
6
{
"key": "<string>",
"value": "<string>",
"createdAt": 116,
"updatedAt": 121
}Stores a JSON value with a specified key. Forge resolves write conflicts using a last-write-wins strategy by default, but this can be configured via the key policy option. Optionally, you can specify a TTL (Time To Live) to automatically expire the data after a specified duration.
storage:appstring
Requiredstring
RequiredoneOf [string, boolean, number, array<undefined>, object]
RequiredExtendedSetOptions
Successfully set the value with metadata fields returned
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/set' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>",
"value": "<string>",
"options": {
"ttl": {
"value": 38,
"unit": "SECONDS"
},
"keyPolicy": "FAIL_IF_EXISTS",
"returnValue": "PREVIOUS",
"returnMetadataFields": [
"CREATED_AT"
]
}
}'1
2
3
4
5
6
7
{
"key": "<string>",
"value": "<string>",
"createdAt": 122,
"updatedAt": 127,
"expireTime": "<string>"
}Deletes a value by key. Write conflicts are resolved using a last-write-wins strategy.
storage:appstring
Requiredstring
RequiredSuccessfully deleted the key and the corresponding value
1
2
3
4
5
6
7
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/delete' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>"
}'Retrieve key-value pairs matching the provided list of criteria. This method does not return secret values set by Set secret value.
storage:appstring
Requirednumber
string
array<WhereCondition>
object
Successfully retrieved the data from storage
QueryResponseSchema
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/query' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"limit": 2154,
"after": "<string>",
"where": [
{
"condition": "BEGINS_WITH",
"property": "key",
"values": [
"<string>"
]
}
],
"options": {
"metadataFields": [
"CREATED_AT"
]
}
}'Sets multiple Key-Value Store and/or Custom Entity Store values in a single operation.
Returns a type BatchResponse which contains successfulKeys and failedKeys.
Optionally, you can specify a TTL (Time To Live) for each item to automatically expire the data after a specified duration.
storage:appstring
Requiredarray<anyOf [BatchSetTypedItemSchema, BatchSetUntypedItemSchema]>
Successfully set the keys to their corresponding values, returns list of successful and failed keys. Failed keys will contain details of the failure error codes.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/batch/set' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '[
{
"key": "<string>",
"value": "<string>",
"entityName": "<string>",
"options": {
"ttl": {
"value": 38,
"unit": "SECONDS"
}
}
}
]'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"successfulKeys": [
{
"key": "<string>",
"entityName": "<string>"
}
],
"failedKeys": [
{
"key": "<string>",
"entityName": "<string>",
"error": {
"code": "<string>",
"message": "<string>"
}
}
]
}Deletes multiple Key-Value Store and/or Custom Entity Store entries in a single operation.
Returns a type BatchResponse which contains successfulKeys and failedKeys.
Failed keys include an error object with code and message.
storage:appstring
Requiredarray<anyOf [BatchDeleteTypedItemSchema, BatchDeleteUntypedItemSchema]>
Successfully deleted the requested keys; returns list of successful and failed keys. Failed keys contain details of the failure error codes.
1
2
3
4
5
6
7
8
9
10
11
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/batch/delete' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '[
{
"key": "<string>",
"entityName": "<string>"
}
]'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"successfulKeys": [
{
"key": "<string>",
"entityName": "<string>"
}
],
"failedKeys": [
{
"key": "<string>",
"entityName": "<string>",
"error": {
"code": "<string>",
"message": "<string>"
}
}
]
}Gets multiple Key-Value Store and/or Custom Entity Store entries in a single operation.
Each request item may include optional options.metadataFields to request metadata (createdAt, updatedAt, expireTime) in the response.
Returns successfulKeys (each with value and optionally metadata) and failedKeys (with error.code, error.message).
storage:appstring
Requiredarray<anyOf [BatchGetTypedItemSchema, BatchGetUntypedItemSchema]>
Successfully retrieved the requested keys; returns list of successful keys (with value and optionally metadata) and failed keys (with error details).
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/batch/get' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '[
{
"key": "<string>",
"entityName": "<string>",
"options": {
"metadataFields": [
"CREATED_AT"
]
}
}
]'1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"successfulKeys": [
{
"key": "<string>",
"entityName": "<string>",
"value": "<string>",
"createdAt": 116,
"updatedAt": 121,
"expireTime": "<string>"
}
],
"failedKeys": [
{
"key": "<string>",
"entityName": "<string>",
"error": {
"code": "<string>",
"message": "<string>"
}
}
]
}Gets a value by key, which was stored using Set secret value by key. The value is decrypted before being returned.
storage:appstring
Requiredstring
RequiredGetOptions
Successfully retrieved the decrypted value corresponding to the key
1
2
3
4
5
6
7
8
9
10
11
12
13
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/secret/get' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>",
"options": {
"metadataFields": [
"CREATED_AT"
]
}
}'1
2
3
4
5
6
{
"key": "<string>",
"value": "<string>",
"createdAt": 116,
"updatedAt": 121
}Stores sensitive credentials in JSON format, with encryption. Values set with this method can only be accessed with Get secret value by key. Write conflicts are resolved using a last-write-wins strategy by default, but this can be configured via the key policy option. Optionally, you can specify a TTL (Time To Live) to automatically expire the data after a specified duration.
storage:appstring
Requiredstring
RequiredoneOf [string, boolean, number, array<undefined>, object]
RequiredExtendedSetOptions
Successfully set the value with metadata fields returned
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/secret/set' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>",
"value": "<string>",
"options": {
"ttl": {
"value": 38,
"unit": "SECONDS"
},
"keyPolicy": "FAIL_IF_EXISTS",
"returnValue": "PREVIOUS",
"returnMetadataFields": [
"CREATED_AT"
]
}
}'1
2
3
4
5
6
7
{
"key": "<string>",
"value": "<string>",
"createdAt": 122,
"updatedAt": 127,
"expireTime": "<string>"
}Deletes a secret value by key.
storage:appstring
Requiredstring
RequiredSuccessfully deleted the key and the corresponding encrypted value
1
2
3
4
5
6
7
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/secret/delete' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>"
}'Gets a custom entity value by key.
storage:appstring
Requiredstring
Requiredstring
RequiredGetOptions
Successfully retrieved the value corresponding to the key and the entity
1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/entity/get' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>",
"entityName": "<string>",
"options": {
"metadataFields": [
"CREATED_AT"
]
}
}'1
2
3
4
5
6
7
{
"key": "<string>",
"value": {},
"entityName": "<string>",
"createdAt": 116,
"updatedAt": 121
}Stores a JSON value with a specified key, for the selected entity. Optionally, you can specify a TTL (Time To Live) to automatically expire the data after a specified duration.
storage:appstring
Requiredstring
Requiredobject
Requiredstring
RequiredExtendedSetOptions
Successfully set the value with metadata fields returned
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/entity/set' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>",
"value": {},
"entityName": "<string>",
"options": {
"ttl": {
"value": 38,
"unit": "SECONDS"
},
"keyPolicy": "FAIL_IF_EXISTS",
"returnValue": "PREVIOUS",
"returnMetadataFields": [
"CREATED_AT"
]
}
}'1
2
3
4
5
6
7
8
{
"key": "<string>",
"value": {},
"entityName": "<string>",
"createdAt": 122,
"updatedAt": 127,
"expireTime": "<string>"
}Deletes a value by key, for the selected entity.
storage:appstring
Requiredstring
Requiredstring
RequiredSuccessfully deleted the key and the corresponding value of the entity
1
2
3
4
5
6
7
8
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/entity/delete' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"key": "<string>",
"entityName": "<string>"
}'Retrieves custom entities matching the provided list of criteria using query conditions. See Querying the Custom Entity Store for more information about building complex queries.
storage:appstring
Requiredstring
Requiredstring
Requiredarray<anyOf [string, number, boolean]>
object
oneOf [AndFilterSchema, OrFilterSchema]
string
string
integer
object
Successfully retrieved the data from storage for an entity
QueryResponseSchema
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/entity/query' \
--header 'Accept: application/json' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"entityName": "<string>",
"indexName": "<string>",
"partition": [
"<string>"
],
"range": {
"condition": "BEGINS_WITH",
"values": [
"<string>"
]
},
"filters": {},
"sort": "ASC",
"cursor": "<string>",
"limit": 2154,
"options": {
"metadataFields": [
"CREATED_AT"
]
}
}'Lets you perform a series of Key-Value Store and/or Custom Entity Store operations that must all succeed or fail together. This method supports 3 types of operations:
storage:appstring
Requiredarray<anyOf [SetTransactionTypedItemSchema, SetTransactionUntypedItemSchema]>
array<anyOf [BaseTransactionTypedItemSchema, BaseTransactionUntypedItemSchema]>
array<allOf [BaseTransactionTypedItemSchema, object]>
Successfully completed all the node operations
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
curl --request POST \
--url '{FORGE_EGRESS_PROXY_URL}/forge/storage/kvs/v1/transaction' \
--header 'forge-proxy-authorization: Forge as=app,id=invocation-123' \
--header 'Content-Type: application/json' \
--data '{
"set": [
{
"key": "<string>",
"value": "<string>",
"entityName": "<string>",
"conditions": {},
"options": {
"ttl": {
"value": 38,
"unit": "SECONDS"
}
}
}
],
"delete": [
{
"key": "<string>",
"entityName": "<string>",
"conditions": {}
}
],
"check": [
{
"key": "<string>",
"entityName": "<string>",
"conditions": {}
}
]
}'Rate this page: