Platform

Forge / Reference / KVS/Custom Entity Store API

Custom Entity Store

The Custom Entity Store lets you store data in custom entities, which are data structures you can define according to your app's needs. Custom entities let you assign multiple values (or "attributes") to a single key (or "entity") and define indexes to optimize queries against these values.

Operations

POST/v1/entity/get POST/v1/entity/set POST/v1/entity/delete POST/v1/entity/query

POST

Get custom entity value by key

Gets a custom entity value by key.

Request

Request bodyapplication/json

key

string

Required

entityName

string

Required

Responses

Successfully retrieved the value corresponding to the key and the entity

application/json

EntityKeyValueSchema

POST/v1/entity/get

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/forge/storage/kvs/v1/entity/get' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "<string>",
  "entityName": "<string>"
}'

200Response

{
  "key": "<string>",
  "value": {},
  "entityName": "<string>"
}

POST

Set custom entity value by key

Stores a JSON value with a specified key, for the selected entity.

Request

Request bodyapplication/json

key

string

Required

value

object

Required

entityName

string

Required

Responses

Successfully set the value to the corresponding key and the entity

POST/v1/entity/set

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/forge/storage/kvs/v1/entity/set' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "<string>",
  "value": {},
  "entityName": "<string>"
}'

POST

Delete custom entity value by key

Deletes a value by key, for the selected entity.

Request

Request bodyapplication/json

key

string

Required

entityName

string

Required

Responses

Successfully deleted the key and the corresponding value of the entity

POST/v1/entity/delete

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/forge/storage/kvs/v1/entity/delete' \
  --header 'Content-Type: application/json' \
  --data '{
  "key": "<string>",
  "entityName": "<string>"
}'

POST

Query custom entities

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.

Request

Request bodyapplication/json

entityName

string

Required

indexName

string

Required

partition

array<anyOf [string, number, boolean]>

range

object

filters

oneOf [AndFilterSchema, OrFilterSchema]

sort

string

cursor

string

limit

integer

Responses

Successfully retrieved the data from storage for an entity

application/json

QueryResponseSchema

POST/v1/entity/query

curl

Node.js

Java

Python

PHP

curl --request POST \
  --url 'https://api.atlassian.com/forge/storage/kvs/v1/entity/query' \
  --header 'Accept: application/json' \
  --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
}'

200Response

{
  "cursor": "<string>",
  "data": [
    {
      "key": "<string>",
      "value": "<string>"
    }
  ]
}