-
Notifications
You must be signed in to change notification settings - Fork 4.9k
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.
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":"cam@metabase.com","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.
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": "cam@metabase.com", "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.
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.
Similarly, if you try to fetch an object the current user doesn't have permissions for, the API will return a 403 (Forbidden).
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
andPOST
endpoints tend to listbody
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.
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.
- Backend
- Metabase Developer Reference
- Product Management
- QA and Testing
- Writing A Driver
- Driver Notices
- REST API Notices
- Writing style guide for documentation and blog posts (WIP)