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'

Naming Constraints

  • All user provided keys in an item can only contain alphanumeric(a-z,A-Z,0-9), underscore(_), dot(.), dash(-) and tilde (~) characters. For instance a random key$ is not a valid key because it contains a space and a $.

  • Object attributes cannot contain the question mark character(?). For eg an object like {"val?ue": 1} can not be stored in the detabase.

Endpoints

Put Item

PUT /items

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

JSON PayloadRequiredTypeDescription
itemsYesarrayAn 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.

URL ParameterRequiredTypeDescription
keyYesstringThe key (aka. ID) of the item you want to retrieve

Delete Item

DELETE /items/{key}

Delete a stored item.

URL ParameterRequiredTypeDescription
keyYesstringThe 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.

JSON PayloadRequiredTypeDescription
itemYesobjectThe 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.

JSON PayloadRequiredTypeDescription
setnoobjectThe attributes to be updated or created.
incrementnoobjectThe attributes to be incremented. Increment value can be negative.
appendnoobjectThe attributes to append a value to. Appended value must be a list.
prependnoobjectThe attributes to prepend a value to. Prepended value must be a list.
deletenostring arrayThe 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.

JSON PayloadRequiredTypeDescription
queryNolista query
limitNointno of items to return. min value 1 if used
lastNostringlast 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

Edit this page