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.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
Requirednumber
string
array<WhereCondition>
object
Successfully retrieved the data from storage
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"
]
}
}'1
2
3
4
5
6
7
8
9
{
"cursor": "<string>",
"data": [
{
"key": "<string>",
"value": "<string>"
}
]
}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.
Forge and OAuth2 apps cannot access this REST resource.
string
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>"
}
}
]
}Gets a value by key, which was stored using Set secret value by key. The value is decrypted before being returned.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
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.
Forge and OAuth2 apps cannot access this REST resource.
string
Requiredstring
Requiredstring
Requiredarray<anyOf [string, number, boolean]>
object
oneOf [AndFilterSchema, OrFilterSchema]
string
string
integer
object
Successfully retrieved the data from storage for an entity
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"
]
}
}'1
2
3
4
5
6
7
8
9
{
"cursor": "<string>",
"data": [
{
"key": "<string>",
"value": "<string>"
}
]
}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:
Forge and OAuth2 apps cannot access this REST resource.
string
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: