Data API requests
This article is part of a significant update to the Bubble manual and your feedback is critical to our efforts to continuously enhance our written documentation.
We would greatly appreciate if you could take a moment to let us know your thoughts on the quality of it. Thank you for your support!
Give feedback on this article
This is the short-form reference entry for the different request types of the Bubble Data API. Each request uses an HTTP method. To learn more about what an HTTP method is from a more technical perspective, check out our guide on How RESTful APIs work and HTTP methods specifically.
We also have an in-depth guide on the Data API and on the different Data API requests.
get
https://appname.bubbleapps.io/api/1.1/obj
/typename/uid
Retrieve record by ID
You can retrieve a thing by sending a GET request with the record’s Unique ID. Use the endpoint below, where the parts in bold are replaced with the relevant strings from your application:
Parameters
Query
*
The unique ID of the record
Responses
200: OK
Success
404: Not Found
Record not found
You can retrieve a thing by sending a GET request with the record’s Unique ID. Use the endpoint below, where the parts in bold are replaced with the relevant strings from your application:
- Check that the data type is active in the Data API settings
- If this is the live environment of your app, check that the settings have been deployed
- Check that the full unique ID is included in the URL
- Check that there is an existing record with that unique ID in your application
- Check that you are using the URL of the right branch of your application
patch
https://appname.bubbleapps.io/api/1.1/obj/typename/
UID
Make changes to a Thing by ID
You can make changes to a thing by sending a PATCH request with the record’s Unique ID.
The body of the request should be a JSON object with a list of keys and values to modify. The keys should match the names of the keys returned via a GET request, and the values need to be correctly formatted.
For this request to work, the Modify via API privacy settings must be active on the relevant data type. The privacy rule will be checked both before the modification to confirm that the user has permission to modify this thing, and after the modification to confirm that the modification was valid. We do not permit a user to modify a thing in a way that would take away that user's ability to perform further modifications.
Possible solutions for error 400 (field(s) not found):
- Check that there are no duplicate field name(s)
Possible solutions for error 401 (not authorized):
Possible solutions for error 404 (record not found):
- Check that the data type is active in the Data API settings
- Check that the Create via API box is checked in the relevant privacy rules in your app
- If this is the live environment of your app, check that the settings have been deployed
- Check that the full unique ID is included in the URL
- Check that there is an existing record with that unique ID in your application
- Check that you are using the URL of the right branch of your application
put
https://appname.bubbleapps.io/api/1.1/obj/
typename/UID
Replace a Thing by ID
You can make changes to a thing by sending a PUT request with the record’s Unique ID.
The body of the request should be a JSON object with a list of keys and values to modify. The keys should match the names of the keys returned via a GET request, and the values need to be correctly formatted.
The PUT HTTP method will overwrite all editable fields on a record. Any field that is not given a new value will be left empty or reset to the default value they are given in the Data Type editor.
To make changes to selected fields without overwriting other fields, use the Make changes to a thing by ID request.
The following fields cannot be changed:
- Unique ID (not replaced)
- Created date (not replaced)
- Modified date (automatically updated)
For this request to work, the Modify via API setting in the Thing's Privacy Rule must be active. The privacy rule will be checked both before the modification to confirm that the user has permission to modify this thing, and after the modification to confirm that the modification was valid. We do not permit a user to modify a thing in a way that would take away that user's ability to perform further modifications.
Possible solutions for error 400 (field not found):
- Check that there are no duplicate field name(s)
- Check that the field name is correct and correctly formatted
Possible solutions for error 400 (field not found):
- If this is the live branch of your app, check that the settings have been deployed
- Check that the full unique ID is included in the URL
- Check that there is an existing record with that unique ID in your application
- Check that you are using the URL of the right branch of your application
Possible solutions for error 401 (not authorized):
delete
https://appname.bubbleapps.io/api/1.1/obj
typename/UID
Delete a Thing
For this request to work, the Delete via API setting must be active on the relevant data type's Privacy Rules.
Possible solutions to error 404 (record not found):
- Check that the data type is active in the Data API settings
- If this is the live branch of your app, check that the settings have been deployed
- Check that the full unique ID is included in the URL
- Check that there is an existing record with that unique ID in your application
- Check that you are using the URL of the right branch of your application
- Check that the Delete via API box is checked in the relevant privacy rules in your app
Possible solutions to error 401 (not authorized):
post
https://appname.bubbleapps.io/api/1.1/obj/
typename
Create a Thing
The body of the request should be a JSON object containing the details you want to save on the new Thing. The keys should match the names of the keys returned via a GET request for that type of thing, and the values should be correctly formatted.
Bubble will automatically create the following fields and their value cannot be overridden:
- Unique ID
- Created date
- Modified date
All fields that have a default value set in the data type editor will be given that default value if another value is not provided in the request.
If you are creating a new user, there are two built-in special fields that are not present on other data types:
- Email (required)
- Password (optional)
This method creates a User in the database, but does not return any authentication token for that User. If you are looking to create or log in as a User in order to authenticate them as an API client, you may be interested in the article below:
Article: Authenticating as a User with the Bubble API
For this request to work, the Create via API privacy setting must be active on the relevant data type. The privacy rule will be checked on the new data for the thing, and the creation attempt will be rejected if Bubble does not find a matching privacy rule that allows the creation to happen.
Possible solutions for error 401 (not authorized):
post
https://appname.bubbleapps.io/api/1.1/obj
/bulk
Bulk create Things
You can create a list of new things in a bulk operation by sending a POST request to the /typename/bulk endpoint. The body of the request should be formatted as a text document with one new object to create per line. The objects should be in JSON format without any newlines. The keys and values should be the same as when creating a single thing.
The keys should match the names of the keys returned via a GET request for that type of thing, and the values should be correctly formatted.
The maximum number of items that can be created via a single bulk request is currently 1,000. There is also a limit of 4 minutes for the request to complete; if it takes longer than 4 minutes, items that have not yet been created will be marked as errors in the response.
The creation speed and risk of timeout depends on the available capacity that your application has as well as the size of the items that you are creating.
Caution: Bulk creation can consume a lot of application capacity, so we recommend that if your app is being used in production and capacity is limited, that you test bulk creation in smaller chunks and work your way up.
Using this endpoint requires the Create via API permission. The Privacy Rule will be checked on the new data for each new thing, and the creation attempt will be rejected if Bubble does not find a matching privacy rule that allows the creation to happen. If some things are rejected and some are accepted, the accepted items will be created.
The response body from this call is a text/plain document with one line per thing in the original request. Each line consists of a JSON object, with a 'status' field indicating whether or not the creation was successful. On success, the status will be 'success', and the object will contain an 'id' field with the id of the newly-created object.
Possible solutions to error 400 (wrong content-type):
- Make sure that the Content-type in the Header is set to text/plain.
Possible solutions to error 400 (Could not parse as JSON):
This error is returned on each row where the JSON could not be parsed.
- Make sure that the JSON is correctly formatted
To check the formatting of JSON you can use a tool like JSON checker
External link: https://jsonchecker.com/
Server error or timeout error
Under certain circumstances, like an overall system failure or the app being completely out of capacity, you may get a generic error response that does not have individual lines for each object.
Possible solutions to server error or timeout error:
If you get a generic error response, try the following:
- Check your application’s capacity chart to see if you may have spent all your capacity
get
https://appname.bubbleapps.io/api/1.1/obj/
typename
Get a list of Things
The constraints parameter should be an array of constraints that include the parameters above.
Add parameters directly in the URL as a query strings. It can be limit, cursor (Pagination), constraints (Search constraints), sort_field, and descending (Sorting options).
Constraint examples
You can narrow down the list returned by the Data API to match specific constraints, just like with Do a search for in Bubble. The constraints parameter should be an array of constraints that include the following:
Key | Value example |
key | Unitname, unitnumber |
constraint_type | equals, greater than |
value | Unit A, 3 |
Constraint Type | Description | Field Types |
|---|---|---|
equals or not equal | Use to test strict equality | All field types |
is_empty or is_not_empty | Use to test whether a thing's given field is empty or not | All field types |
text contains or not text contains | Use to test whether a text field contains a string. Text contains will not respect partial words that are not of the same stem. | Text fields only |
greater than or less than | Use to compare a thing's field value relative to a given value | Text, number, and date fields |
in or not in | Use to test whether a thing's field is in a list or not for all field types. | All field types |
contains or not contains | Use to test whether a list field contains an entry or not for list fields only. | List fields only |
empty or not empty | Use to test whether a list field is empty or not for list fields only. | List fields only |
geographic_search | Use to test if the current thing is within a radius from a central address. To use this, the value sent with the constraint must have an address and a range. | See below |
In this example, we will send a request to search for a unit by the name ‘Unit A’ using the following two constraints:
Key | Value |
|---|---|
key | unitname, unitnumber |
constraint_type | contains, greater than |
value | Unit A, 3 |
The URL below represents the URL before URL-encoding:
GET https://securitybook.bubbleapps.io/version-test/api/1.1/obj/rentalunit?constraints=[ { "key": "unitname", "constraint_type": "equals", "value": "Unit A" } ,{ "key": "unitnumber", "constraint_type": "greater than", "value": "3" }]
After applying URL encoding, the same URL should look like this:
GET https://securitybook.bubbleapps.io/version-test/api/1.1/obj/rentalunit?constraints=[%20{%20%22key%22:%20%22unitname%22,%20%22constraint_type%22:%20%22equals%22,%20%22value%22:%20%22Unit%20A%22%20}%20,{%20%22key%22:%20%22unitnumber%22,%20%22constraint_type%22:%20%22greater%20than%22,%20%22value%22:%20%223%22%20}]
In the response, Bubble will supply two values to aid in pagination:
- Cursor: the rank of the first item in the list
- Count: the number of items in the current response
- Remaining: the number of records left
By default, GET requests are sorted by their creation date. The Bubble Data API supports the sort_field and descending parameter.
- Sort_field: the field you want to sort by
- Descending (true/false)
To define more than one sorting field, add an array additional_sort_fields, which should contain objects of the similar type as above, i.e., with sort_field and descending.
Suggested solutions to error 404 (incompatible constraint type)
- Check that the field type you are applying the constraint to and the constraint type are compatible
- Check that the constraint type is spelled correctly
- There is a limit of 50,000 items in any GET request, meaning that if a database contains 100,000 items and the cursor is set at 50,001 no results will be returned
- For dedicated plans the limit is 10,000,000 items
You may find these entries from our manual useful to get a deeper understanding of how the Bubble API works:
Last modified 2mo ago