Base

General & Auth

Get a Data Key . If it’s a Builder project, get it from Builder. Your Collection ID is the first chars of the Data Key, before the _. You need these to talk with the Deta API.

ℹ️ Base currently supports maximum 16 digit numbers (integers and floating points), please store larger numbers as a string.

Root URL

This URL is the base for all your HTTP requests:

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

The base_name is the name given to 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 Data Key must to be provided in the request headers as a value for the X-API-Key key for authentication. This is how we authorize your requests.

Example 'X-API-Key: a0abcyxzxsr_aSecretValue'.

Data Keys were called Project Keys in earlier versions of Deta.

Content Type

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

Endpoints

Put Items

PUT /items

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

`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

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.

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

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.

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

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.

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
}

`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

Update Item

PATCH /items/{key}

Updates an item only if an item with key exists.

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

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": "[email protected]"
   },

   "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": "[email protected]"
  },
  "likes": ["anime", "ramen"],
  "purchases": 3
}

`200 OK`

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

`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.

Query Items

POST /query

List items that match a query.

JSON Payload	Required	Type	Description
`query`	No	`list`	list of 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
`sort`	No	`string`	sort order based on item keys, `asc` or `desc`, default ‘asc’

Example

{
   "query": [
        // separate objects in the list are ORed
        // query evaluates 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 data process size exceeds 1 MB (before the query is applied) 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.

Upto 1 MB of data is retrieved before filtering with the query. Thus, in some cases you might get an empty list of items but still the last key evaluated in the response.

To apply the query through all the items in your base, you have to call fetch until last is empty.

`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 an unsupported 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

Issues

If you run into any issues, consider reporting them in our Discord.

HTTP API

Drive