openapi: 3.0.3
info:
  title: Metabase API
  description: >-
    The Metabase API provides programmatic access to Metabase, an open source
    business intelligence and analytics platform. It allows developers to manage
    dashboards, questions (cards), collections, databases, users, permissions,
    and to execute queries against connected data sources.
  version: "1.0"
  contact:
    name: Metabase
    url: https://www.metabase.com
  license:
    name: AGPL-3.0
    url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
  - url: https://your-metabase-instance.com/api
    description: Self-hosted or cloud Metabase instance
security:
  - ApiKeyAuth: []
  - SessionAuth: []
tags:
  - name: Sessions
    description: Authentication and session management.
  - name: Collections
    description: Organize dashboards, questions, and pulses.
  - name: Dashboards
    description: Build and manage interactive dashboards.
  - name: Cards
    description: Saved questions used to power dashboards and embedded analytics.
  - name: Databases
    description: Manage data source connections and metadata.
  - name: Datasets
    description: Execute ad-hoc queries against connected databases.
  - name: Search
    description: Search across cards, dashboards, collections, and more.
  - name: Users
    description: User account management.
  - name: Permissions
    description: Group and permission management.
  - name: Settings
    description: Global application settings.
paths:
  /session:
    post:
      tags: [Sessions]
      summary: Create a session
      description: Authenticate using username and password to obtain a session ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [username, password]
              properties:
                username:
                  type: string
                  format: email
                password:
                  type: string
                  format: password
      responses:
        '200':
          description: Session created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
        '400':
          description: Invalid credentials.
    delete:
      tags: [Sessions]
      summary: Delete a session
      description: Sign out the current session.
      responses:
        '204':
          description: Session deleted.
  /collection:
    get:
      tags: [Collections]
      summary: List collections
      responses:
        '200':
          description: A list of collections.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Collection'
    post:
      tags: [Collections]
      summary: Create a collection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CollectionInput'
      responses:
        '200':
          description: Collection created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
  /collection/{id}:
    get:
      tags: [Collections]
      summary: Get a collection
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A collection.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
  /dashboard:
    get:
      tags: [Dashboards]
      summary: List dashboards
      responses:
        '200':
          description: A list of dashboards.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Dashboard'
    post:
      tags: [Dashboards]
      summary: Create a dashboard
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DashboardInput'
      responses:
        '200':
          description: Dashboard created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
  /dashboard/{id}:
    get:
      tags: [Dashboards]
      summary: Get a dashboard
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A dashboard.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dashboard'
    put:
      tags: [Dashboards]
      summary: Update a dashboard
      parameters:
        - $ref: '#/components/parameters/IdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DashboardInput'
      responses:
        '200':
          description: Dashboard updated.
    delete:
      tags: [Dashboards]
      summary: Archive a dashboard
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '204':
          description: Dashboard archived.
  /card:
    get:
      tags: [Cards]
      summary: List saved questions (cards)
      responses:
        '200':
          description: A list of cards.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Card'
    post:
      tags: [Cards]
      summary: Create a card
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CardInput'
      responses:
        '200':
          description: Card created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /card/{id}:
    get:
      tags: [Cards]
      summary: Get a card
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A card.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Card'
  /card/{id}/query:
    post:
      tags: [Cards]
      summary: Execute a card's query
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: Query result.
  /database:
    get:
      tags: [Databases]
      summary: List databases
      responses:
        '200':
          description: A list of databases.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Database'
    post:
      tags: [Databases]
      summary: Add a database connection
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DatabaseInput'
      responses:
        '200':
          description: Database added.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
  /database/{id}:
    get:
      tags: [Databases]
      summary: Get a database
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A database.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Database'
  /dataset:
    post:
      tags: [Datasets]
      summary: Execute an ad-hoc query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                database:
                  type: integer
                type:
                  type: string
                  enum: [query, native]
                native:
                  type: object
                  properties:
                    query:
                      type: string
      responses:
        '200':
          description: Query result.
  /search:
    get:
      tags: [Search]
      summary: Search Metabase content
      parameters:
        - in: query
          name: q
          schema:
            type: string
          description: Search term.
      responses:
        '200':
          description: Search results.
  /user:
    get:
      tags: [Users]
      summary: List users
      responses:
        '200':
          description: A list of users.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'
    post:
      tags: [Users]
      summary: Create a user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserInput'
      responses:
        '200':
          description: User created.
  /user/{id}:
    get:
      tags: [Users]
      summary: Get a user
      parameters:
        - $ref: '#/components/parameters/IdParam'
      responses:
        '200':
          description: A user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
  /permissions/group:
    get:
      tags: [Permissions]
      summary: List permission groups
      responses:
        '200':
          description: A list of permission groups.
  /setting:
    get:
      tags: [Settings]
      summary: List settings
      responses:
        '200':
          description: A list of settings.
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
    SessionAuth:
      type: apiKey
      in: header
      name: X-Metabase-Session
  parameters:
    IdParam:
      in: path
      name: id
      required: true
      schema:
        type: integer
  schemas:
    Collection:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        slug:
          type: string
        description:
          type: string
        parent_id:
          type: integer
          nullable: true
        archived:
          type: boolean
    CollectionInput:
      type: object
      required: [name]
      properties:
        name:
          type: string
        description:
          type: string
        parent_id:
          type: integer
          nullable: true
    Dashboard:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        collection_id:
          type: integer
          nullable: true
        creator_id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    DashboardInput:
      type: object
      required: [name]
      properties:
        name:
          type: string
        description:
          type: string
        collection_id:
          type: integer
          nullable: true
    Card:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        description:
          type: string
        database_id:
          type: integer
        collection_id:
          type: integer
          nullable: true
        dataset_query:
          type: object
        display:
          type: string
    CardInput:
      type: object
      required: [name, dataset_query, display, visualization_settings]
      properties:
        name:
          type: string
        dataset_query:
          type: object
        display:
          type: string
        visualization_settings:
          type: object
        collection_id:
          type: integer
          nullable: true
    Database:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
        engine:
          type: string
        details:
          type: object
        is_sample:
          type: boolean
        created_at:
          type: string
          format: date-time
    DatabaseInput:
      type: object
      required: [name, engine, details]
      properties:
        name:
          type: string
        engine:
          type: string
          example: postgres
        details:
          type: object
    User:
      type: object
      properties:
        id:
          type: integer
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        is_superuser:
          type: boolean
        is_active:
          type: boolean
    UserInput:
      type: object
      required: [email, first_name, last_name]
      properties:
        email:
          type: string
          format: email
        first_name:
          type: string
        last_name:
          type: string
        password:
          type: string
          format: password