Medusa Layouts API

openapi: 3.2.0
info:
  version: 2.19.0
  title: Medusa Admin Layouts API
  license:
    name: MIT
    url: https://github.com/medusajs/medusa/blob/develop/LICENSE
  description: 'An admin can modify the layout of their admin dashboard. This allows admins to customize their dashboard to their preferences and needs.

    These API routes allow admin users to manage layouts.

    '
servers:
- url: http://localhost:9000
- url: https://api.medusajs.com
tags:
- name: Layouts
  description: 'An admin can modify the layout of their admin dashboard. This allows admins to customize their dashboard to their preferences and needs.

    These API routes allow admin users to manage layouts.

    '
paths:
  /admin/layouts/configurations:
    get:
      operationId: GetLayoutsConfigurations
      summary: List Layout Configurations
      description: Retrieve a list of layout configurations made by admin users. The layouts can be filtered by fields such as `id`. The layouts can also be sorted or paginated.
      x-authenticated: true
      parameters:
      - name: id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: id
            description: Filter by layout configuration ID.
          - type: array
            description: Filter by layout configuration IDs.
            items:
              type: string
              title: id
              description: The layout configuration's ID.
      - name: zone
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: zone
            description: Filter by layout configuration zone.
          - type: array
            description: Filter by layout configuration zones.
            items:
              type: string
              title: zone
              description: The layout configuration's zone.
      - name: user_id
        in: query
        required: false
        schema:
          oneOf:
          - type: string
            title: user_id
            description: Filter by the ID of the user who created the layout configuration.
          - type: array
            description: Filter by the IDs of users who created the layout configurations.
            items:
              type: string
              title: user_id
              description: The ID of the user who created the layout configuration.
      - name: is_system_default
        in: query
        description: Filter by whether the layout configuration is a system default.
        required: false
        schema:
          type: boolean
          title: is_system_default
          description: Whether the layout configuration is a system default.
      - name: limit
        in: query
        description: Limit the number of items returned in the list.
        required: false
        schema:
          type: number
          title: limit
          description: Limit the number of items returned in the list.
          externalDocs:
            url: '#pagination'
      - name: offset
        in: query
        description: The number of items to skip when retrieving a list.
        required: false
        schema:
          type: number
          title: offset
          description: The number of items to skip when retrieving a list.
          externalDocs:
            url: '#pagination'
      - name: order
        in: query
        description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
        required: false
        schema:
          type: string
          title: order
          description: The field to sort the data by. By default, the sort order is ascending. To change the order to descending, prefix the field name with `-`.
          externalDocs:
            url: '#pagination'
      - name: with_deleted
        in: query
        description: The layout's with deleted.
        required: false
        schema:
          type: boolean
          title: with_deleted
          description: The layout's with deleted.
      - name: fields
        in: query
        description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. Without prefix it will replace the entire default fields.
        required: false
        schema:
          type: string
          title: fields
          description: Comma-separated fields that should be included in the returned data. If a field is prefixed with `+` it will be added to the default fields, using `-` will remove it from the default fields. Without prefix it will replace the entire default fields.
          externalDocs:
            url: '#select-fields-and-relations'
      - name: $and
        in: query
        description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
        required: false
        schema:
          type: array
          description: Join query parameters with an AND condition. Each object's content is the same type as the expected query parameters.
          items:
            type: object
          title: $and
      - name: $or
        in: query
        description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
        required: false
        schema:
          type: array
          description: Join query parameters with an OR condition. Each object's content is the same type as the expected query parameters.
          items:
            type: object
          title: $or
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: JavaScript
        label: JS SDK
        source: "import Medusa from \"@medusajs/js-sdk\"\n\nexport const sdk = new Medusa({\n  baseUrl: import.meta.env.VITE_BACKEND_URL || \"/\",\n  debug: import.meta.env.DEV,\n  auth: {\n    type: \"session\",\n  },\n})\n\nconst { layout_configurations } = await sdk.admin.layouts.listConfigurations()"
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/layouts/configurations'' \

          -H ''Authorization: Bearer {access_token}'''
      tags:
      - Layouts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                allOf:
                - type: object
                  description: The pagination details of the layout configurations list.
                  required:
                  - limit
                  - offset
                  - count
                  properties:
                    limit:
                      type: number
                      title: limit
                      description: The maximum number of items returned in the list.
                    offset:
                      type: number
                      title: offset
                      description: The number of items skipped before retrieving the list.
                    count:
                      type: number
                      title: count
                      description: The total number of items in the list.
                    estimate_count:
                      type: number
                      title: estimate_count
                      description: The estimated count retrieved from the PostgreSQL query planner, which may be inaccurate.
                      x-featureFlag: index_engine
                - type: object
                  description: The layout configurations list.
                  required:
                  - layout_configurations
                  properties:
                    layout_configurations:
                      type: array
                      description: The list of layout configurations.
                      items:
                        $ref: '#/components/schemas/AdminLayoutConfiguration'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-since: 2.17.2
  /admin/layouts/{zone}/configuration:
    get:
      operationId: GetLayoutsZoneConfiguration
      summary: List Layout Configurations
      description: Retrieve a list of layout configurations for a specific zone. These are the configurations made by the users for their admin dashboard layouts.
      x-authenticated: true
      parameters:
      - name: zone
        in: path
        description: The zone for which the layout configurations should be retrieved.
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl ''{backend_url}/admin/layouts/{zone}/configuration'' \

          -H ''Authorization: Bearer {access_token}'''
      tags:
      - Layouts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminLayoutConfigurationResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-since: 2.17.2
    post:
      operationId: PostLayoutsZoneConfiguration
      summary: Add Layout Configuration
      description: Add a layout configuration for a specific zone. This allows you to customize the layout of the admin dashboard for that zone, including the arrangement of widgets and other UI elements.
      x-authenticated: true
      parameters:
      - name: zone
        in: path
        description: The zone for which the layout configuration should be added.
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminSetLayoutConfiguration'
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: "curl -X POST '{backend_url}/admin/layouts/{zone}/configuration' \\\n-H 'Authorization: Bearer {access_token}' \\\n-H 'Content-Type: application/json' \\\n--data-raw '{\n  \"configuration\": {\n    \"widgets\": {}\n  }\n}'"
      tags:
      - Layouts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminLayoutConfigurationResponse'
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-workflow: setLayoutConfigurationWorkflow
      x-events: []
      x-since: 2.17.2
    delete:
      operationId: DeleteLayoutsZoneConfiguration
      summary: Clear Configuration of Layout
      description: Clears all user layout configurations for a given zone. This action will remove any customizations made by the user and revert to the system defaults.
      x-authenticated: true
      parameters:
      - name: zone
        in: path
        description: The zone for which the layout configuration should be cleared.
        required: true
        schema:
          type: string
      security:
      - api_token: []
      - cookie_auth: []
      - jwt_token: []
      x-codeSamples:
      - lang: Shell
        label: cURL
        source: 'curl -X DELETE ''{backend_url}/admin/layouts/{zone}/configuration'' \

          -H ''Authorization: Bearer {access_token}'''
      tags:
      - Layouts
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                description: The details of the layout configuration deletion result.
                required:
                - success
                properties:
                  success:
                    type: boolean
                    title: success
                    description: Whether the layout configuration was successfully cleared.
        '400':
          $ref: '#/components/responses/400_error'
        '401':
          $ref: '#/components/responses/unauthorized'
        '404':
          $ref: '#/components/responses/not_found_error'
        '409':
          $ref: '#/components/responses/invalid_state_error'
        '422':
          $ref: '#/components/responses/invalid_request_error'
        '500':
          $ref: '#/components/responses/500_error'
      x-workflow: clearLayoutConfigurationWorkflow
      x-events: []
      x-since: 2.17.2
components:
  examples:
    invalid_data_error:
      summary: Invalid Data Error
      value:
        message: first_name must be a string
        type: invalid_data
    not_allowed_error:
      summary: Not Allowed Error
      value:
        message: Discount must be set to dynamic
        type: not_allowed
    database_error:
      summary: Database Error
      value:
        code: api_error
        message: An error occured while hashing password
        type: database_error
    default_error:
      summary: Default Error
      value:
        code: unknown_error
        message: An unknown error occurred.
        type: unknown_error
    invalid_argument_error:
      summary: Invalid Argument Error
      value:
        message: cart.total must be defined
        type: unexpected_state
    unexpected_state_error:
      summary: Unexpected State Error
      value:
        message: cart.total must be defined
        type: unexpected_state
  schemas:
    Error:
      title: Response Error
      type: object
      properties:
        code:
          type: string
          description: A slug code to indicate the type of the error.
          enum:
          - invalid_state_error
          - invalid_request_error
          - api_error
          - unknown_error
        message:
          type: string
          description: Description of the error that occurred.
          example: first_name must be a string
        type:
          type: string
          description: A slug indicating the type of the error.
          enum:
          - QueryRunnerAlreadyReleasedError
          - TransactionAlreadyStartedError
          - TransactionNotStartedError
          - conflict
          - unauthorized
          - payment_authorization_error
          - duplicate_error
          - not_allowed
          - invalid_data
          - not_found
          - database_error
          - unexpected_state
          - invalid_argument
          - unknown_error
    AdminLayoutConfigurationResponse:
      type: object
      description: The details for a layout configuration response.
      x-schemaName: AdminLayoutConfigurationResponse
      required:
      - personal_configuration
      - default_configuration
      - active_scope
      properties:
        personal_configuration:
          $ref: '#/components/schemas/AdminLayoutConfiguration'
        default_configuration:
          $ref: '#/components/schemas/AdminLayoutConfiguration'
        active_scope:
          type: string
          description: The active scope of the layout configuration.
          enum:
          - default
          - personal
    AdminSetLayoutConfiguration:
      type: object
      description: The details of setting the layout configuration for a zone in the admin dashboard.
      x-schemaName: AdminSetLayoutConfiguration
      required:
      - configuration
      properties:
        is_default:
          type: boolean
          title: is_default
          description: Whether the layout configuration is set as the default for the zone.
        configuration:
          type: object
          description: The layout's configuration.
          required:
          - widgets
          properties:
            widgets:
              type: object
              description: The widgets configuration for the layout. Each key represents a widget's ID, and the value is an object containing the widget's configuration details.
              additionalProperties:
                type: object
                properties:
                  hidden:
                    type: boolean
                    title: hidden
                    description: Whether the widget is hidden in the layout.
                  section:
                    type: string
                    title: section
                    description: The section of the layout where the widget is placed.
                  order:
                    type: number
                    title: order
                    description: The widget's order.
    AdminLayoutConfiguration:
      type: object
      description: The layout configuration's details.
      x-schemaName: AdminLayoutConfiguration
      required:
      - id
      - zone
      - user_id
      - is_system_default
      - configuration
      - created_at
      - updated_at
      properties:
        id:
          type: string
          title: id
          description: The layout configuration's ID.
        zone:
          type: string
          title: zone
          description: The layout configuration's zone.
        user_id:
          type: string
          title: user_id
          description: The ID of the user who created the layout configuration.
        is_system_default:
          type: boolean
          title: is_system_default
          description: Whether the layout configuration is a system default.
        configuration:
          type: object
          description: The configuration's details.
          required:
          - widgets
          properties:
            widgets:
              type: object
              description: The configurations of the widgets in the layout. The object's keys are the widget IDs, and the values are objects containing the widget's configuration details.
              additionalProperties:
                type: object
                properties:
                  hidden:
                    type: boolean
                    title: hidden
                    description: Whether the widget is hidden.
                  section:
                    type: string
                    title: section
                    description: The section of the layout where the widget is placed.
                  order:
                    type: number
                    title: order
                    description: The widget's order.
        created_at:
          type: string
          format: date-time
          title: created_at
          description: The date the layout configuration was created.
        updated_at:
          type: string
          format: date-time
          title: updated_at
          description: The date the layout configuration was last updated.
  responses:
    invalid_request_error:
      description: Invalid Request Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: invalid_request_error
            message: Discount with code TEST already exists.
            type: duplicate_error
    unauthorized:
      description: User is not authorized. Must log in first
      content:
        text/plain:
          schema:
            type: string
            default: Unauthorized
            example: Unauthorized
    400_error:
      description: Client Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            not_allowed:
              $ref: '#/components/examples/not_allowed_error'
            invalid_data:
              $ref: '#/components/examples/invalid_data_error'
    invalid_state_error:
      description: Invalid State Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unknown_error
            message: The request conflicted with another request. You may retry the request with the provided Idempotency-Key.
            type: QueryRunnerAlreadyReleasedError
    500_error:
      description: Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            database:
              $ref: '#/components/examples/database_error'
            unexpected_state:
              $ref: '#/components/examples/unexpected_state_error'
            invalid_argument:
              $ref: '#/components/examples/invalid_argument_error'
            default_error:
              $ref: '#/components/examples/default_error'
    not_found_error:
      description: Not Found Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            message: Entity with id 1 was not found
            type: not_found
  securitySchemes:
    api_token:
      type: http
      x-displayName: API Token
      scheme: basic
    jwt_token:
      type: http
      x-displayName: JWT Token
      scheme: bearer
    cookie_auth:
      type: apiKey
      in: cookie
      name: connect.sid
      x-displayName: Cookie Session ID
    reset_password:
      type: http
      x-displayName: Reset Password Token
      scheme: bearer
      x-is-auth: false