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
    ]
}

`207 Multi Status`#

{
    "processed": {
        "items": [
            // items which were stored 
        ]
    },
    "failed": {
       "items": [
           // items failed because of internal processing
       ]
    }
}

Client errors#

In case of client errors, no items in the request are stored.

`400 Bad Request`#

{
    "errors" : [
       // error messages
    ] 
}

Bad requests occur in the following cases:

if an item has a non-string key
if the number of items in the requests exceeds 25
if total request size exceeds 16 MB
if any individual item exceeds 400KB
if there are two items with identical keys
if any item does not follow the naming constraints

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

`200 OK`#

{
  "key": {key},
  // the rest of the item
}

`404 Not Found`#

{
  "key": {key}
}

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.

The server will always return 200 regardless if an item with that key existed or not.

`200 OK`#

{
  "key": {key}
}

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
    }
}

`201 Created`#

{
  "key": {key}, // auto generated key if key was not provided in the request
  "field1": "value1",
  // the rest of the item
}

Client errors#

`409 Conflict` (if key already exists)#

{
  "errors": ["Key already exists"] 
}

`400 Bad Request`#

{
  "errors": [
     // error messages
  ]
}

Bad requests occur in the following cases:

if the item has a non-string key
if size of the item exceeds 400KB
if the item does not follow the naming constraints

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
}

`200 OK`#

{
   "key": {key},
   "set": {
     // identical to the request
   },
   "delete": ["field1", ..] // identical to the request 
}

Client errors#

`404 Not Found` (if key does not exist)#

{
  "errors": ["Key not found"] 
}

`400 Bad Request`#

{
  "errors": [
     // error messages
  ]
}

Bad requests occur in the following cases:

if you're updating or deleting the key
if set and delete have conflicting attributes
if you're setting a hierarchical attribute but an upper level attribute does not exist, for eg. {"set": {"user.age": 22}} but user is not an attribute of the item.
if attributes in set do not follow the naming constraints

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
}

The response is paginated if the reponse size exceeds 1 MB or the total number of items matching the query exceeds the limit provided in the request.

For paginated responses, last will return the last key seen in the response. You must use this key in the following request to continue retreival of items. If the response does not have the last key, then no further items are to be retreived.

`200 OK`#

{
    "paging": {
        "size": 5, // size of items returned
        "last": "adfjie" // last key seen if paginated, provide this key in the following request
    },
    "items": [
       {
         "key": {key},
         // rest of the item
       },
       // rest of the items
   ]
}

Client Errors#

`400 Bad Request`#

{
  "errors": [
    // error messages
  ]
}

Bad requests occur in the following cases:

if a query is made on the key
if a query is not of the right format
if limit is provided in the request and is less than 1

Contact#

team@deta.sh

General & Auth#

note

Root URL#

Auth#

Content Type#

Endpoints#

Put Item#

Example#

207 Multi Status#

Client errors#

400 Bad Request#

Get Item#

note

200 OK#

404 Not Found#

Delete Item#

note

200 OK#

Insert Item#

Example#

201 Created#

Client errors#

409 Conflict (if key already exists)#

400 Bad Request#

Update Item#

note

Example#

200 OK#

Client errors#

404 Not Found (if key does not exist)#

400 Bad Request#

Query Items#

Example#

200 OK#

Client Errors#

400 Bad Request#

Contact#

`207 Multi Status`#

`400 Bad Request`#

`200 OK`#

`404 Not Found`#

`200 OK`#

`201 Created`#

`409 Conflict` (if key already exists)#

`400 Bad Request`#

`200 OK`#

`404 Not Found` (if key does not exist)#

`400 Bad Request`#

`200 OK`#

`400 Bad Request`#