Firebase Database REST API

API Usage

You can use any Firebase Database URL as a REST endpoint. All you need to do is append .json to the end of the URL and send a request from your favorite HTTPS client.

GET - Reading Data

Data from your Realtime Database can be read by issuing an HTTP GET request to an endpoint. The following example demonstrates how you might retrieve a user's name that you had previously stored in Realtime Database.

curl 'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name.json'

A successful request is indicated by a 200 OK HTTP status code. The response contains the data associated with the path in the GET request.

{ "first": "Jack", "last": "Sparrow" }

PUT - Writing Data

You can write data with a PUT request.

curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name.json'

A successful request is indicated by a 200 OK HTTP status code. The response contains the data specified in the PUT request.

{ "first": "Jack", "last": "Sparrow" }

POST - Pushing Data

To accomplish the equivalent of the JavaScript push() method (see Lists of Data), you can issue a POST request.

curl -X POST -d '{"user_id" : "jack", "text" : "Ahoy!"}' \
  'https://[PROJECT_ID].firebaseio-demo.com/message_list.json'

A successful request is indicated by a 200 OK HTTP status code. The response contains the child name of the new data specified in the POST request.

{ "name": "-INOQPH-aV_psbk3ZXEX" }

PATCH - Updating Data

You can update specific children at a location without overwriting existing data using a PATCH request. Named children in the data being written with PATCH are overwritten, but omitted children are not deleted. This is equivalent to the JavaScript update() function.

curl -X PATCH -d '{"last":"Jones"}' \
 'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name/.json'

A successful request is indicated by a 200 OK HTTP status code. The response contains the data specified in the PATCH request.

{ "last": "Jones" }

DELETE - Removing Data

You can delete data with a DELETE request:

curl -X DELETE \
  'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name/last.json'

A successful DELETE request is indicated by a 200 OK HTTP status code with a response containing JSON null.

Method Override

If you make REST calls from a browser that does not support the preceding methods, you can override the request method by making a POST request and setting your method by using the X-HTTP-Method-Override request header.

curl -X POST -H "X-HTTP-Method-Override: DELETE" \
  'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name/last.json'

You can also use the x-http-method-override query parameter.

curl -X POST \
  'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name/last.json?x-http-method-override=DELETE'

Query Parameters

The Firebase Database REST API accepts the following query parameters and values:

access_token

Supported by all request types. Authenticates this request to allow access to data protected by Firebase Realtime Database Rules. See the REST authentication documentation for details.

curl 'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name.json?access_token=CREDENTIAL'

shallow

This is an advanced feature, designed to help you work with large datasets without needing to download everything. Set this to true to limit the depth of the data returned at a location. If the data at the location is a JSON primitive (string, number or boolean), its value will simply be returned. If the data snapshot at the location is a JSON object, the values for each key will be truncated to true.

Arguments REST Methods Description
shallow GET Limit the depth of the response.
curl 'https://[PROJECT_ID].firebaseio-demo.com/.json?shallow=true'

Note that shallow cannot be mixed with any other query parameters.

print

Formats the data returned in the response from the server.

Arguments REST Methods Description
pretty GET, PUT, POST, PATCH, DELETE View the data in a human-readable format.
silent GET, PUT, POST, PATCH Used to suppress the output from the server when writing data. The resulting response will be empty and indicated by a 204 No Content HTTP status code.
curl 'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name.json?print=pretty'
curl -X PUT -d '{ "first": "Jack", "last": "Sparrow" }' \
  'https://[PROJECT_ID].firebaseio-demo.com/users/jack/name.json?print=silent'

callback

Supported by GET only. To make REST calls from a web browser across domains, you can use JSONP to wrap the response in a JavaScript callback function. Add callback= to have the REST API wrap the returned data in the callback function you specify.

<script>
  function gotData(data) {
    console.log(data);
  }
</script>
<script src="https://[PROJECT_ID].firebaseio-demo.com/.json?callback=gotData"></script>

format

If set to export, the server will encode priorities in the response.

Arguments REST Methods Description
export GET Include priority information in the response.
curl 'https://[PROJECT_ID].firebaseio-demo.com/.json?format=export'

download

Supported by GET only. If you would like to trigger a file download of your data from a web browser, add download=. This causes the REST service to add the appropriate headers so that browsers know to save the data to a file.

curl 'https://[PROJECT_ID].firebaseio-demo.com/.json?download=myfilename.txt'

orderBy

See the section in the guide on ordered data for more information.

limitToFirst, limitToLast, startAt, endAt, equalTo

See the section in the guide on filtering data for more information.

Streaming from the REST API

Firebase REST endpoints support the EventSource / Server-Sent Events protocol. To stream changes to a single location in your Realtime Database, you need to do a few things:

  • Set the client's Accept header to "text/event-stream"
  • Respect HTTP Redirects, in particular HTTP status code 307
  • If the location requires permission to read, you must include the auth parameter

In return, the server will send named events as the state of the data at the requested URL changes. The structure of these messages conforms to the EventSource protocol.

event: event name
data: JSON encoded data payload

The server may send the following events:

put

The JSON-encoded data is an object with two keys: path and data. The path key points to a location relative to the request URL. The client should replace all of the data at that location in its cache with data.

patch

The JSON-encoded data is an object with two keys: path and data. The path key points to a location relative to the request URL. For each key in data, the client should replace the corresponding key in its cache with the data for that key in the message.

keep-alive

The data for this event is null. No action is required.

cancel

The data for this event is null. This event will be sent if the Firebase Realtime Database Rules cause a read at the requested location to no longer be allowed.

auth_revoked

The data for this event is a string indicating that a the credential has expired. This event is sent when the supplied auth parameter is no longer valid.

Here's an example set of events that the server may send:

// Set your entire cache to {"a": 1, "b": 2}
event: put
data: {"path": "/", "data": {"a": 1, "b": 2}}

// Put the new data in your cache under the key 'c', so that the complete cache now looks like:
// {"a": 1, "b": 2, "c": {"foo": true, "bar": false}}
event: put
data: {"path": "/c", "data": {"foo": true, "bar": false}}

// For each key in the data, update (or add) the corresponding key in your cache at path /c,
// for a final cache of: {"a": 1, "b": 2, "c": {"foo": 3, "bar": false, "baz": 4}}
event: patch
data: {"path": "/c", "data": {"foo": 3, "baz": 4}}

Priorities

Priority information for a location can be referenced with a "virtual child" named .priority. You can read priorities with GET requests and write them with PUT requests. For example, the following request retrieves the priority of the users/tom node:

curl 'https://[PROJECT_ID].firebaseio-demo.com/users/tom/.priority.json'

To write priority and data at the same time, you can add a .priority child to the JSON payload:

curl -X PUT -d '{"name": {"first": "Tom"}, ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio-demo.com/users/tom.json'

To write priority and a primitive value (e.g. a string) at the same time, you can add a .priority child and put the primitive value in a .value child:

curl -X PUT -d '{".value": "Tom", ".priority": 1.0}' \
  'https://[PROJECT_ID].firebaseio-demo.com/users/tom/name/first.json'

This writes "Tom" with a priority of 1.0. Priorities can be included at any depth in the JSON payload.

Server Values

You can write server values at a location using a placeholder value which is an object with a single .sv key. The value for that key is the type of server value you wish to set. For example, the following request sets the node's value to the Firebase server's current timestamp:

curl -X PUT -d '{".sv": "timestamp"}' \
  'https://[PROJECT_ID].firebaseio-demo.com/users/tom/startedAtTime.json'

You can also write priorities using server values, using the "virtual child" path noted above.

Supported server values include:

Server Value
timestamp The time since UNIX epoch, in milliseconds.

Retrieving and Updating Firebase Realtime Database Rules

The REST API can also be used to retrieve and update the Firebase Realtime Database Rules for your Firebase project. You'll need your Firebase project's secret, which you can find under the Service Accounts panel of your Firebase project's setting.

curl 'https://[PROJECT_ID].firebaseio-demo.com/.settings/rules.json?auth=FIREBASE_SECRET'
curl -X PUT -d '{ "rules": { ".read": true } }' 'https://[PROJECT_ID].firebaseio-demo.com/.settings/rules.json?auth=FIREBASE_SECRET'

Error Conditions

The Firebase Database REST API can return the following error codes.

HTTP Status Codes
400 Bad Request

One of the following error conditions:

  • Unable to parse PUT or POST data.
  • Missing PUT or POST data.
  • The request attempts to PUT or POST data that is too large.
  • The REST API call contains invalid child names as part of the path.
  • The REST API call path is too long.
  • The request contains an unrecognized server value.
  • The index for the query is not defined in your Firebase Realtime Database Rules.
  • The request does not support one of the query parameters that is specified.
  • The request mixes query parameters with a shallow GET request.
401 Unauthorized

One of the following error conditions:

  • The auth token has expired.
  • The auth token used in the request is invalid.
  • Authenticating with an access_token failed.
403 Forbidden The request violates your Firebase Realtime Database Rules.
404 Not Found The specified Realtime Database was not found.
500 Internal Server Error The server returned an error. See the error message for further details.
503 Service Unavailable The specified Firebase Realtime Database is temporarily unavailable, which means the request was not attempted.

Send feedback about...

Need help? Visit our support page.