Breaking changes to the API interface

Metabase 0.66.0

• The can-write-metadata query parameter of GET /api/database, GET /api/database/:id/schemas, GET /api/database/:id/schema/:schema and GET /api/database/:id/schema/, and the can-write query parameter of GET /api/table, have been removed and are ignored. To list only what the current user can edit the data model of, pass include_editable_data_model=true to the database endpoints and include-editable-data-model=true to GET /api/table instead.

• GET /api/database/:id/metadata?include_hidden=true no longer returns fields whose visibility is “Do not include” (sensitive). Pass the new include_sensitive_fields=true to get them, for tables whose data model the current user can edit, as with GET /api/table/:id/query_metadata.

• POST /api/ee/serialization/export accepts a dirname of 1-255 characters from A-Z a-z 0-9 _ - . % that does not start with . or -. Other values get 400 Bad Request.

• PUT /api/field/:id no longer accepts nfc_path, which only sync sets, and answers null for has_field_values, display_name, visibility_type or json_unfolding with 400 Bad Request. Leave a key out to keep its value. PUT /api/table/:id, PUT /api/table and the Data Studio bulk table edit answer data_authority: null the same way.

Metabase 0.65.0

• POST /api/transform and PUT /api/transform/:id answer a target table that already exists with 409 Conflict instead of 403 Forbidden. The message, “A table with that name already exists.”, is unchanged. 403 remains the answer when the user lacks permission.

Metabase 0.64.0

• POST /api/slack/bug-report now requires bug reporting to be enabled (MB_BUG_REPORTING_ENABLED). diagnosticInfo.reporter is now a boolean: true attributes the report to the authenticated user, false (or omitting it) submits the report anonymously. The previous { "name": ..., "email": ... } object is still accepted and treated as true; the name and email in it are ignored. The request body is validated against a fixed set of keys; undeclared keys are dropped. This change is backported to 0.58 and later; see the per-version entries below.

• Self-hosted environments must now explicitly enable transforms before beginning to use them via the API. Admins can enable transforms in Data Studio or by setting the MB_TRANSFORMS_ENABLED environment variable to true.

• The endpoints that fetch prefill values for action forms have been converted from GET to POST so that parameter values are sent in the JSON request body instead of the URL query string. parameters is now a JSON object in the request body rather than a JSON-encoded query-string parameter:

  • GET /api/action/:action-id/execute has been replaced by POST /api/action/:action-id/execute/values.
  • GET /api/dashboard/:dashboard-id/dashcard/:dashcard-id/execute has been replaced by POST /api/dashboard/:dashboard-id/dashcard/:dashcard-id/execute/values.
  • GET /api/public/dashboard/:uuid/dashcard/:dashcard-id/execute has been replaced by POST /api/public/dashboard/:uuid/dashcard/:dashcard-id/execute/values.

  The GET variants have been removed without a deprecation period.

• PUT /api/notification/:id now identifies the notification by the URL only. An id in the request body (and a payload.id) is ignored instead of being used to target a different notification. Previously, a body id that didn’t match the URL deleted and recreated the notification.

• POST /api/notification/:id/send requires write access to the notification instead of read access. Only the notification’s creator or an admin can send it, and with advanced permissions enabled the creator also needs the Subscriptions and Alerts application permission.

• POST /api/notification, PUT /api/notification/:id, and POST /api/notification/send apply channel permissions to inline handler definitions. A handler that carries an inline channel (instead of a channel_id) requires permission to create channels. A handler that attaches, replaces, or removes a template requires permission to write channel templates.

• POST /api/notification/send validates the request body with the same schema as POST /api/notification. id, payload_id, and other ids of saved rows are no longer part of the accepted body, since the notification being sent is never saved.

• POST /api/action and PUT /api/action/:id return a 403 when the action’s dataset_query is a native query and the caller doesn’t have native query permission on the target database. This matches what the Metabase UI already required.

• POST /api/pulse/test requires the Subscriptions and Alerts application permission.

• GET /api/transform/run/:run-id requires read access to the run’s transform. Runs whose transform has been deleted are only visible to admins. Previously, the endpoint only checked that the run existed.

• Creating or updating a transform checks query permissions on every table and saved question referenced by the transform’s source query, not only the source database. Requests that used to succeed can now return a 403.

• GET /api/ee/tenant and GET /api/ee/tenant/:id only include member_count and attributes for admins. Other people get id, name, slug, is_active, and tenant_collection_id.

• Pulse and subscription recipient lists are scoped by tenancy for everyone who isn’t an admin: people in a tenant see only recipients in their own tenant, and internal people see only other internal people. GET /api/pulse/form_input no longer includes the Slack channel list for people in a tenant.

• PUT /api/dashboard/:id returns a 400 when a link card’s entity id or a click behavior’s target id isn’t an integer. Previously, these values were stored as-is.

• Unauthenticated requests to PUT /api/email, DELETE /api/email, and POST /api/email/test return a 401 instead of a 403. The endpoints are now mounted behind the same authentication middleware as the other admin routes.

Metabase 0.63.15

• POST /api/slack/bug-report: diagnosticInfo.reporter is now a boolean and bug reporting must be enabled. See the 0.64.0 entry.

Metabase 0.62.18

• POST /api/slack/bug-report: diagnosticInfo.reporter is now a boolean and bug reporting must be enabled. See the 0.64.0 entry.

Metabase 0.61.20

• POST /api/slack/bug-report: diagnosticInfo.reporter is now a boolean and bug reporting must be enabled. See the 0.64.0 entry.

Metabase 0.61.0

• POST /api/metabot/describe/card and POST /api/metabot/describe/dashboard/:id have been removed. These endpoints provided LLM-powered autodescription of cards and dashboards using the legacy OpenAI client. This functionality has been superseded by the Metabot agent.

Metabase 0.60.26

• POST /api/slack/bug-report: diagnosticInfo.reporter is now a boolean and bug reporting must be enabled. See the 0.64.0 entry.

Metabase 0.59.30

• POST /api/slack/bug-report: diagnosticInfo.reporter is now a boolean and bug reporting must be enabled. See the 0.64.0 entry.

Metabase 0.58.32

• POST /api/slack/bug-report: diagnosticInfo.reporter is now a boolean and bug reporting must be enabled. See the 0.64.0 entry.

Metabase 0.57.0

• MBQL queries (in Cards and elsewhere) are now serialized as MBQL 5 as opposed to MBQL 4 (aka legacy MBQL) in the application database and in REST API responses. While we do not officially support editing or introspection of MBQL via the REST API (please treat it as an opaque object), to support existing usages the GET /api/card/:id endpoint can return the Card dataset_query as MBQL 4 if you include the query parameter ?legacy-mbql=true.

Metabase 0.56.13

• /api/collection/graph endpoints now no longer return ‘none’ permissions in the returned graph. Missing fields in between group ids and collection id indicate that the group provides no permissions for the collection. For example, what was returned in versions before 0.56.13:

  {
    "revision": 2,
    "groups": { "1": { "root": "write", "1": "read", "2": "none" } }
  }
  

  becomes:

  { "revision": 2, "groups": { "1": { "root": "write", "1": "read" } } }
  

  in versions 0.56.13 and up.

Metabase 0.55.0

• POST /api/card/from-csv has been renamed to POST /api/upload/csv.

• GET /api/util/stats has been renamed to GET /api/analytics/anonymous-stats.

• GET /api/util/bug_report_details has been renamed to GET /api/bug-reporting/details.

• POST /api/util/product-feedback has been renamed to POST /api/product-feedback.

• POST /api/util/entity_id has been renamed to POST /api/eid-translation/translate.

• POST /api/util/password_check has been renamed to POST /api/session/password-check.

• GET /api/util/logs has been renamed to GET /api/logger/logs.

• GET /api/util/openapi has been removed; you can use GET /api/docs/openapi.json instead, which does the same thing.

• GET /api/util/diagnostic_info/connection_pool_info has been renamed to GET /api/bug-reporting/connection-pool-details.

Metabase 0.54.0

• The alert system has been migrated from the legacy pulse infrastructure to the new notification system. This migration includes the following changes:

  • The majority of /api/alert endpoints have been removed in favor of the new /api/notification endpoints. For backward compatibility, these endpoints will remain available until the next release:

    • GET /api/alert
    • GET /api/alert/:id
    • DELETE /api/alert/:id/subscription

  • Developers should migrate to using the /api/notification endpoints. For reference:

    • An overview of the new notification system can be found at src/metabase/notification/README.md
    • Notification API documentation at /api/docs/#tag/apinotification
    • Interactive API documentation available at /api/docs endpoint

Metabase 0.53.0

• POST /api/card/:card-id/query/:export-format

  Previously, request parameters (parameters, pivot-results?, and format-rows?) could be sent via query parameters or as application/x-www-form-urlencoded form content. In Metabase 0.53.0, parameters must be sent as either:

  • application/x-www-form-urlencoded form content
  • JSON-encoded in the request body

  Sending parameters as query parameters in the URL is no longer supported.

Metabase 0.52.0

• POST /api/user/:id/send_invite has been removed.

• GET /:id/fields now includes the Table ID.

• APIs under /api/pulse and /api/alert will be removed in a future version as we’re transitioning to a new architecture.

Metabase 0.51.0

• GET /api/dashboard/:id/query_metadata

  New endpoint that combines responses for /api/field/:id, /api/database/:id, and /api/table/:id/query_metadata. This should drastically cut down on the required number of requests to display a card.

• GET /api/card/:id/query_metadata

  New endpoint that combines responses for /api/field/:id, /api/database/:id, and /api/table/:id/query_metadata. This should drastically cut down on the required number of requests to display a dashboard.

• /api/legacy-metric

  The /api/legacy-metric endpoints have been removed.

• POST /api/session/pulse/unsubscribe and POST /api/session/pulse/unsubscribe/undo have been moved to POST /api/pulse/unsubscribe and POST /api/pulse/unsubscribe/undo respectively.

Metabase 0.50.0

• GET /api/collection/tree and GET /api/collection/:id/items These API endpoints will always return official collections first, before other items in the collection.

• PUT /api/dashboard/:id, PUT /api/card/:id, and PUT /api/collection/:id

  When setting archived to true, the Dashboard, Card, or Collection will be automatically moved to the Trash collection, a special collection that holds all archived items.

  When setting archived to false, you may optionally also provide a collection_id (for Dashboards or Cards) or a parent_id (for Collections). In this case, the entity will be re-parented to the specified Collection when it is moved from the Trash. If a new collection_id or parent_id is not provided, the entity will be moved back to its original location if possible. If this is impossible (for example, the original location is also in the Trash) an error will occur.

• /api/metric

  The /api/metric endpoints have been renamed to /api/legacy-metric. The new metrics use the /api/card endpoints.

• GET /api/permissions/graph and PUT /api/permissions/graph

  The data key has been removed from the permissions graph. The data key has been replaced with two new keys: view-data and create-queries. Valid permission values for view-data are unrestricted, blocked, sandboxed or restricted. Valid permission values for create-queries are query-builder-and-native, query-builder, and no.

  If you’re scripting permissions, you’ll need to update your scripts to reflect these breaking changes to the /api/permissions/graph endpoints. For more about the new data permissions of View data and Create queries, see our docs on data permissions. And here’s a page that talks about the change (and why we did it).

• GET /api/transform/:db-id/:schema/:transform-name, which hasn’t been used internally by Metabase for ages, has been removed.

• POST /api/user/:id/send_invite is deprecated and will be removed in the next version.

Metabase 0.49.5

NOTE: These endpoint changes were added in 0.49.3, and a bug in GET /api/embed/card/:token/query/:export-format was fixed in 0.49.5.

• POST /api/card/:card-id/query/:export-format

• POST /api/:dashboard-id/dashcard/:dashcard-id/card/:card-id/query/:export-format

• POST /api/dataset/:export-format

• GET /api/embed/card/:token/query/:export-format

• GET /api/embed/dashboard/:token/dashcard/:dashcard-id/card/:card-id/:export-format

  The above endpoints now accept the format_rows query parameter. It is an optional boolean parameter that will default to true if not included in the request. When format_rows is true, the export will have formatting applied such that the values match what they appear as in the app. When format_rows is false, formatting is not applied and exports will behave as they did before 0.49.0.

  The value of format_rows has no effect when exporting xlsx files.

Metabase 0.49.0

• POST /api/card and PUT /api/card/:id

  The dataset key is deprecated and will be removed in a future version, most likely 50. In its place we have added a new key: type which is equivalent in that it distinguishes Models from Questions. type="model" is equivalent to dataset=true and type="question" is equivalent to dataset=false.

• all endpoints that return data (e.g. exports in JSON, XLSX, CSV, endpoints that end in “/query”)

  Starting from v49, we respond to the API calls with values formatted according to the instance localization options