Data API requests

The different resources availabe in the Bubble Data API.

Experience level

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

In-depth articles (2)

To learn about this topic more in-depth, we recommend reading the suggested articles below:

• Article series: The Data API

• Article: Introduction to APIs This article covers how APIs work in general, and explores the terminology used.

Postman Collection

Bubble offers a collection. This collection is specifically designed to help developers understand and experiment with the various API functionalities available in Bubble.

External page: Bubble Postman collection

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

Name	Type	Description
id*	String	The unique ID of the record

404: Not Found Record not found

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

200: OK Success

{
    "response": {
        "_id": "1671702337369x488321592367327900",
        "Created By": "[e-mail]",
        "Created Date": "2022-12-22T09:45:37.369Z",
        "Modified Date": "2022-12-22T09:45:37.417Z",
        "Unit name": "Unit A"
    }
}

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

Name	Type	Description
key1	varying	The field to change and new value. Must match field type.

204: No Content Success

No body

400: Bad Request Field(s) not found

{
    "statusCode": 400,
    "body": {
        "status": "ERROR",
        "message": "Unrecognized field: Fieldname"
    }
}

404: Not Found Record not found

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

401: Unauthorized User is not authorized to make the change

{
    "error_class": "Unauthorized",
    "args": {
        "code": "1671711631737x692262587046790400"
    },
    "message": null,
    "translation": "You do not have permission to modify this object"
}

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

Name	Type	Description
key1	varying	The field to change and new value. Must match field type.ld

204: No Content Success

No body

400: Bad Request Field not found

{
    "statusCode": 400,
    "body": {
        "status": "ERROR",
        "message": "Unrecognized field: Fieldname"
    }
}

404: Not Found Record not found

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

401: Unauthorized User is not authorized to make the change

{
    "error_class": "Unauthorized",
    "args": {
        "code": "1671711631737x692262587046790400"
    },
    "message": null,
    "translation": "You do not have permission to modify this object"
}

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.

404: Not Found Record not found

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

401: Unauthorized User is not authorized to make the change

{
    "error_class": "Unauthorized",
    "args": {
        "code": "1671714622020x932812958293338700"
    },
    "message": null,
    "translation": "You do not have permission to delete this object"
}

204: No Content Success

No body

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

Name	Type	Description
key1	varying	The field to change and new value. Must match field type.

201: Created Success

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

401: Unauthorized User is not authorized to make the change

{
    "error_class": "Unauthorized",
    "args": {
        "code": "1671716913010x902588598612626300"
    },
    "message": null,
    "translation": "Permission denied: cannot create this object"
}

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

200: OK Success

(See comment below)

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

400: Bad Request Wrong Content-Type

{
    "statusCode": 400,
    "body": {
        "status": "ERROR",
        "message": "Expecting a newline-seperated list of JSON objects.  Make sure the Content-Type header is text/plain"
    }
}

400: Bad Request Could not parse as JSON

One per row

{"status":"error","message":"Could not parse as JSON: {\"Unit name\": \unit1}"}

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

Name	Type	Description
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

404: Not Found Constraint type is not compatible

{
    "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 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 .	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:

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

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