HTTP API
#
General & Authnote
You can get your Project Key and your Project ID from your Deta dashboard. You need these to talk with the Deta API.
info
Base currently supports maximum 16 digit numbers (integers and floating points), please store larger numbers as a string.
#
Root URLThis URL is the base for all your HTTP requests:
https://database.deta.sh/v1/{project_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 anyPUT
orPOST
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.
#
AuthA Project 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: a0abcyxz_aSecretValue'
.
#
Content TypeWe only accept JSON payloads. Make sure you set the headers correctly: 'Content-Type: application/json'
#
Endpoints#
Put ItemsPUT /items
Stores multiple items in a single request. This request overwrites an item if the key already exists.
- Request
- Response
207 Multi Status
#
#
Client errorsIn case of client errors, no items in the request are stored.
400 Bad Request
#
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
info
Empty keys in objects/dictionaries/structs, like {"": "value"}
are invalid and will fail to be added during the backend processing stage.
#
Get ItemGET /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
#
Delete ItemDELETE /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 ItemPOST /items
Creates a new item only if no item with the same key
exists.
- Request
- Response
#
Update ItemPATCH /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. |
#
ExampleIf the following item exists in the database
Then the request
results in the following item in the database:
200 OK
#
#
Client errors404 Not Found
(if key does not exist)#
400 Bad Request
#
Bad requests occur in the following cases:
- if you're updating or deleting the
key
- if
set
anddelete
have conflicting attributes - if you're setting a hierarchical attribute but an upper level attribute does not exist, for eg.
{"set": {"user.age": 22}}
butuser
is not an attribute of the item.
#
Query ItemsPOST /query
List items that match a query.
- Request
- Response
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 |
#
ExampleThe 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.
note
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
#
#
Client Errors400 Bad Request
#
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
#
IssuesIf you run into any issues, consider reporting them in our Github Discussions.