Data API requests

The different resources availabe in the Bubble Data API.

This core reference entry is suited for advanced-level builders.

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.

Retrieve record by ID

GET https://appname.bubbleapps.io/api/1.1/obj/typename/uid

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:

Query Parameters

NameTypeDescription

id*

String

The unique ID of the record

{
    "statusCode": 404,
    "body": {
        "status": "MISSING_DATA",
        "message": "Missing object of type rentalunit: object with id 1671702337369x488321592367327900 does not exist"
    }
}

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:

Errors and solutions

Possible solutions for error 404:

  • 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

Make changes to a Thing by ID

PATCH https://appname.bubbleapps.io/api/1.1/obj/typename/UID

Save changes to the fields of a database record identified by its unique ID.

Request Body

NameTypeDescription

key1

varying

The field to change and new value. Must match field type.

No body

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.

Privacy Rules

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.

Errors and solutions

Possible solutions for error 400 (field(s) not found):

  • Check that the field name is correct and correctly formatted

  • Check that there are no duplicate field name(s)

Possible solutions for error 401 (not authorized):

  • Check that you are including the right credentials in the authentication, such as the bearer token

  • Check that the Modify via API box is checked in the relevant Privacy Rules in your app

Possible solutions for error 404 (record not found):

  • Check that the Find this in searches box is checked in the relevant Privacy Rules in in your app

  • 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

Replace a Thing by ID

PUT https://appname.bubbleapps.io/api/1.1/obj/typename/UID

Overwrite all editable fields on a Thing by its unique ID

Request Body

NameTypeDescription

key1

varying

The field to change and new value. Must match field type.ld

No body

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.

Non-editable fields

The following fields cannot be changed:

  • Unique ID (not replaced)

  • Created date (not replaced)

  • Modified date (automatically updated)

Privacy Rules

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.

Errors and solutions

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):

  • 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 Create via API box is checked in the relevant Privacy Rules in your app

Possible solutions for error 401 (not authorized):

  • Check that you are including the right credentials in the authentication, such as the bearer token

  • Check that the Modify via API box is checked in the relevant Privacy Rules in your app

Delete a Thing

DELETE https://appname.bubbleapps.io/api/1.1/obj/typename/UID

Delete a thing by sending a DELETE request with the record’s Unique ID.

{
    "statusCode": 404,
    "body": {
        "status": "MISSING_DATA",
        "message": "Missing object of type rentalunit: object with id 1671702337369x488321592367327900 does not exist"
    }
}

Privacy Rules

For this request to work, the Delete via API setting must be active on the relevant data type's Privacy Rules.

Errors and solutions

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):

  • Check that you are including the right credentials in the authentication, such as the bearer token

  • Check that the Delete via API box is checked in the relevant Privacy Rules in your app

Create a Thing

POST https://appname.bubbleapps.io/api/1.1/obj/typename

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.

Request Body

NameTypeDescription

key1

varying

The field to change and new value. Must match field type.

{
    "status": "success",
    "id": "1671702337369x488321592367327900"
}

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.

Automatically created fields and default values:

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.

Creating users

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

Privacy Rules

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.

Errors and solutions

Possible solutions for error 401 (not authorized):

  • Check that the Create via API box is checked in the relevant Privacy Rules in your app

  • Check that you are including the right credentials in the authentication, such as the bearer token

Bulk create Things

POST https://appname.bubbleapps.io/api/1.1/obj/typename/bulk

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.

Body:

{"key1": “value”, "key2": “value”}

{"key1": “value”, "key2": “value”}

Content-type:

text/plain

(See comment below)
{"status":"success","id":"1671702337369x488321592367327900"}
{"status":"success","id":"1671702337369x488321592367327901"}

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.

Limitations

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.

Privacy Rules

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.

Success

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.

Errors and solutions

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 Bubble’s status page for any server downtime

  • Check your application’s capacity chart to see if you may have spent all your capacity

  • Check the Bubble forum for any threads about similar problems

  • Get in touch with Bubble support

Get a list of Things

GET https://appname.bubbleapps.io/api/1.1/obj/typename

Search for and retrieve a list of a given data type with or without constraints.

Query Parameters

NameTypeDescription

key

String

The key to which you want to apply the constraint and

constraint type

String

The type of constraint to apply

Value

Varying

The value the constraint should compare to

cursor

Number

Start from item #

limit

String

Show item until #

sort_field

String

The field you want to sort by

exclude_remaining

Boolean

Don't count all remaining items

{
    "statusCode": 404,
    "body": {
        "status": "NOT_FOUND",
        "message": "Constraint type not found contains for field unit_name_text and type rentalunit"
    }
}

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 types

Constraint TypeDescriptionField 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 .

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.

Example

In this example, we will send a request to search for a unit by the name ‘Unit A’ using the following two constraints:

KeyValue

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

Pagination

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

Sorting

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.

Errors and solutions

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

Limitations

  • 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 the Enterprise plan the limit is 10,000,000 items

Manual entries

You may find these entries from our manual useful to get a deeper understanding of how the Bubble API works:

What is a RESTful API?How to authenticateThe Data APIData API requests

Last updated