Using the REST API

This guide should help answer some FAQs about using the Metabase REST API. Feel free to open an issue if you have any questions about using the REST API that aren't covered by this guide.

See also our Learn article, Working with the Metabase API.

The Basics

DISCLAIMER: As Metabase is a pre-1.0 product, the REST API is subject to change between releases. Generally, existing API endpoints are changed infrequently, and removed rarely; you should still however expect things to break occasionally and be prepared to make changes when upgrading to a new version of Metabase.

An API request generally looks something like:

curl -X GET \
  -H "Content-Type: application/json" \
  -H "X-Metabase-Session: 38f4939c-ad7f-4cbe-ae54-30946daf8593" \
  http://localhost:3000/api/user/current

# -> {"email":"[email protected]","first_name":"Cam", ...}

Some things to keep in mind:

• The Metabase API only supports JSON; all responses are returned as JSON, and request bodies must be JSON. As such, you'll want to pass the Content-Type: application/json header with all of your requests.
• For simplicity, our examples use curl. You'll definitely want to write some helper functions and use something a little more sophisticated. JSON requests can become quite complex, and it's error prone to try to write them out on the command line.
• It's extremely helpful to use the Inspector feature of your browser with the Metabase web interface to look at the requests and responses it makes. If something isn't clear in the documentation, take a look at how Metabase itself uses the endpoint. Similarly, the Inspector can help you determine the right endpoint to use for a given task.

Authorizing

Requests require a session token, which be obtained by calling POST /api/session with a user's username (in most cases their email address) and password:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"username": "[email protected]", "password": "myPassword"}' \
  http://localhost:3000/api/session 

# -> {"id":"38f4939c-ad7f-4cbe-ae54-30946daf8593"}

Once you've obtained a session token, pass it as the HTTP header X-Metabase-Session (as in the first example request above).

Some things to keep in mind:

• Sessions are good for 14 days by default; you can configure this value by setting the env var MAX_SESSION_AGE (value is in minutes).
• Logins are rate-limited for security purposes. Thus you should cache the credentials you receive and reüse them until they expire.
• If a session is expired or otherwise no longer valid, the API will return a response with a 401 (Unauthorized) status code.
• We recommend writing your code in a way will fetch a new session token and automatically retry requests a single time when the API returns a 401.

Admin Status

Some endpoints also require that the user be an admin. In some places in our codebase we instead use the term superuser, but it means the same thing. Endpoints that require superuser status generally say so in their documentation and will return a 403 (Forbidden) if the current user doesn't have superuser status.

Permissions

Similarly, if you try to fetch an object the current user doesn't have permissions for, the API will return a 403 (Forbidden).

REST API Endpoint Reference

Here is a complete list of API endpoints along with documentation for each.

The endpoint reference is automatically generated by running the command

java -jar metabase.jar api-documentation

This is periodically updated when new versions of Metabase are shipped.

Some things to keep in mind:

• PUT and POST endpoints tend to list body as one of their parameters; this is a side-effect of the way the documentation is generated, and you can ignore it. Other listed parameters (except for URL parameters like :id) should go inside the JSON in the HTTP request body.

Running Custom Queries

Queries are written in our custom JSON-based query language, MBQL. View the MBQL reference here. Before trying to run your own MBQL queries, you should familiarize yourself with how they look by constructing a few queries in Metabase and using the Web inspector to see how the request bodies map to them.