HTTP API

General & Auth

note

You can get your Project Key and your Project ID from your Deta dashboard. You need these to talk with the Deta API.

Root URL

This URL is the base for all your HTTP requests:

https://database.deta.sh/v1/{project_id}/{base_name}

The base_name is the name for your database. If you already have a Base, then you can go ahead and provide it's name here. Additionally, you could provide any name here when doing any PUT or POST request and our backend will automatically create a new base for you if it does not exist. There is no limit on how many "Bases" you can create.

Auth

A Project Key must to be provided in the request headers X-API-Key for authentication. This is how we authorize your requests.

Example 'X-API-Key: a0abcyxz_aSecretValue'.

Content Type

We only accept JSON payloads. Make sure you set the headers correctly: 'Content-Type: application/json'

Endpoints

Put Item

PUT /items

Stores multiple items in a single request. This request overwrites an item if the key already exists.

• Request
• Response

JSON Payload	Required	Type	Description
items	Yes	array	An array of items object to be stored.

Example

{

// array of items to put

"items": [

{

"key": {key}, // optional, a random key is generated if not provided

"field1": "value1",

// rest of item

},

// rest of items

]

}

Get Item

GET /items/{key}

Get a stored item.

note

If the key contains url unsafe or reserved characters, make sure to url-encode the key. Otherwise, it will lead to unexpected behavior.

• Request
• Response

URL Parameter	Required	Type	Description
key	Yes	string	The key (aka. ID) of the item you want to retrieve

Delete Item

DELETE /items/{key}

Delete a stored item.

note

If the key contains url unsafe or reserved characters, make sure to url-encode the key. Otherwise, it will lead to unexpected behavior.

• Request
• Response

URL Parameter	Required	Type	Description
key	Yes	string	The key (aka. ID) of the item you want to delete.

Insert Item

POST /items

Creates a new item only if no item with the same key exists.

• Request
• Response

JSON Payload	Required	Type	Description
item	Yes	object	The item to be stored.

Example

{

"item": {

"key": {key}, // optional

// rest of item

}

}

Update Item

PATCH /items/{key}

Updates an item only if an item with key exists.

note

If the key contains url unsafe or reserved characters, make sure to url-encode the key. Otherwise, it will lead to unexpected behavior.

• Request
• Response

JSON Payload	Required	Type	Description
set	no	object	The attributes to be updated or created.
increment	no	object	The attributes to be incremented. Increment value can be negative.
append	no	object	The attributes to append a value to. Appended value must be a list.
prepend	no	object	The attributes to prepend a value to. Prepended value must be a list.
delete	no	string array	The attributes to be deleted.

Example

If the following item exists in the database

{

"key": "user-a",

"username": "jimmy",

"profile": {

"age": 32,

"active": false,

"hometown": "pittsburgh"

},

"on_mobile": true,

"likes": ["anime"],

"purchases": 1

}

Then the request

{

"set" : {

// change ages to 33

"profile.age": 33,

// change active to true

"profile.active": true,

// add a new attribute `profile.email`

"profile.email": "jimmy@deta.sh"

},

"increment" :{

// increment purchases by 2

"purchases": 2

},

"append": {

// append to 'likes'

"likes": ["ramen"]

},

// remove attributes 'profile.hometown' and 'on_mobile'

"delete": ["profile.hometown", "on_mobile"]

}

results in the following item in the database:

{

"key": "user-a",

"username": "jimmy",

"profile": {

"age": 33,

"active": true,

"email": "jimmy@deta.sh"

},

"likes": ["anime", "ramen"],

"purchases": 3

}

Query Items

POST /query

List items that match a query.

• Request
• Response

JSON Payload	Required	Type	Description
query	No	list	a query
limit	No	int	no of items to return. min value 1 if used
last	No	string	last key seen in a previous paginated response

Example

{

"query": [

// separate objects in the list are ORed

// query evaluetes to list all users whose hometown is Berlin and is active OR all users who age less than 40

{"user.hometown": "Berlin", "user.active": true},

{"user.age?lt": 40}

],

"limit": 5,

"last": "afsefasd" // last key if applicable

}

Contact

team@deta.sh