> ## Documentation Index
> Fetch the complete documentation index at: https://spreecommerce.org/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Get the diagnostics report

> An anonymised description of this installation to attach to a bug
report: Spree and gem versions, runtime and infrastructure, settings
changed from their defaults, and recent Spree errors by class and code
location. It never contains names, emails, URLs, credentials or error
messages. `markdown` is the same report ready to paste into a GitHub
issue. Available to signed-in admins who can manage the store; a
secret API key gets a 404.




## OpenAPI

````yaml /api-reference/admin.yaml get /api/v3/admin/diagnostics
openapi: 3.0.3
info:
  title: Admin API
  contact:
    name: Spree Commerce
    url: https://spreecommerce.org
    email: hello@spreecommerce.org
  description: >
    Spree Admin API v3 - Administrative API for managing products, orders, and
    store settings.


    ## Authentication


    The Admin API requires a secret API key passed in the `x-spree-api-key`
    header.

    Secret API keys can be generated in the Spree admin dashboard.


    ## Response Format


    All responses are JSON. List endpoints return paginated responses with
    `data` and `meta` keys.

    Single resource endpoints return a flat JSON object.


    ## Resource IDs


    Every resource is identified by an opaque string ID (e.g. `prod_86Rf07xd4z`,

    `variant_k5nR8xLq`, `or_UkLWZg9DAJ`). Use these IDs everywhere — URL paths,

    request bodies, and Ransack filters all accept them directly.


    ## Error Handling


    Errors return a consistent format:

    ```json

    {
      "error": {
        "code": "validation_error",
        "message": "Validation failed",
        "details": { "name": ["can't be blank"] }
      }
    }

    ```
  version: v3
servers:
  - url: http://{defaultHost}
    variables:
      defaultHost:
        default: localhost:3000
security: []
tags:
  - name: Authentication
    description: Admin user login, logout, token refresh, and current user profile
  - name: Allowed Origins
    description: CORS allowlist for storefront and admin client origins
  - name: API Keys
    description: Secret and publishable API keys
  - name: Catalogs
  - name: Categories
    description: >-
      Hierarchical product categories — tree management, repositioning, and
      product assignments
  - name: Channels
    description: >-
      Sales channels, product publication across channels, and per-channel order
      routing rules
  - name: Collections
  - name: Commission Lines
  - name: Commission Rates
  - name: Companies
  - name: Custom Field Definitions
  - name: Custom Fields
    description: >-
      Custom field definitions for products, variants, customers, and other
      resources
  - name: Customer Groups
    description: >-
      Customer groups for segmenting customers (e.g. wholesale, VIP) used by
      pricing and promotions
  - name: Customers
    description: Customer profiles, addresses, credit cards, and store credits
  - name: Deliveries
  - name: Delivery Settings
    description: >-
      How orders ship — delivery methods and their rules, delivery profiles, and
      delivery zones
  - name: Email Templates
    description: >-
      Customer email templates, the email layout and shared partials: drafts,
      previews, publishing and history
  - name: Exports
    description: Async CSV exports of admin resources
  - name: Files
    description: Uploading the files that product media, imports, logos and documents use
  - name: Fulfillments
    description: Order fulfillments — shipments, fulfill, cancel, resume, split
  - name: Gift Cards
    description: Gift cards and gift card batches
  - name: Imports
    description: >-
      Async CSV imports of admin resources, with per-row status and failed-row
      retry
  - name: Integrations
  - name: Maintenance Tasks
    description: >-
      Operator-run data work — backfills, reindexes and upgrade steps — and the
      record of every run
  - name: Markets
    description: >-
      Markets — geographic groupings of countries used for pricing, tax, and
      fulfillment rules
  - name: Media
  - name: OAuth
  - name: Option Types
    description: >-
      Option types and option values used to build product variants (e.g. Size,
      Color)
  - name: Orders
    description: Orders, order items, applied gift cards, and applied store credits
  - name: Package Types
  - name: Payment Methods
    description: Configured payment providers and their available types
  - name: Payments
    description: Order payments — list, capture, void
  - name: Policies
    description: The store's legal documents — terms of service, privacy, returns, shipping
  - name: Price Lists
  - name: Pricing
    description: >-
      Prices and price lists for currency-, market-, and customer-group-specific
      pricing
  - name: Product Types
  - name: Products
    description: >-
      Products, taxons/categories, product custom field values, and bulk product
      operations
  - name: Promotions
    description: Promotions, promotion rules, promotion actions, and coupon codes
  - name: Purchase Orders
  - name: Reasons
    description: >-
      Merchant-owned vocabularies for why a return, claim, refund, cancellation
      or tax exemption happened
  - name: Refunds
    description: Order refunds
  - name: Reports
  - name: Seller Requirements
  - name: Sellers
  - name: Settings
    description: Store-level settings — store profile, tags, and configuration
  - name: Shipping Labels
  - name: Staff
    description: Admin users, roles, and invitations to the store
  - name: Stock
  - name: Stock Locations
    description: Warehouses and physical fulfillment locations
  - name: Stock Movements
  - name: Stock Transfers
  - name: Store Credits
    description: Prepaid customer balances across all customers, and each balance's ledger
  - name: Suppliers
  - name: Variants
    description: >-
      Product variants — the individual SKUs (size/color combinations) sold
      under a product
  - name: Webhooks
    description: Webhook endpoints and webhook delivery history
paths:
  /api/v3/admin/diagnostics:
    get:
      tags:
        - Settings
      summary: Get the diagnostics report
      description: |
        An anonymised description of this installation to attach to a bug
        report: Spree and gem versions, runtime and infrastructure, settings
        changed from their defaults, and recent Spree errors by class and code
        location. It never contains names, emails, URLs, credentials or error
        messages. `markdown` is the same report ready to paste into a GitHub
        issue. Available to signed-in admins who can manage the store; a
        secret API key gets a 404.
      parameters:
        - name: Authorization
          in: header
          required: true
          description: Bearer token for admin authentication
          schema:
            type: string
        - name: packages
          in: query
          required: false
          description: >-
            The caller's own `@spree/*` packages as comma-separated
            `name@version`, reported in a Dashboard section. Other entries are
            ignored.
          example: '@spree/dashboard@6.0.4,@spree/admin-sdk@6.0.4'
          schema:
            type: string
      responses:
        '200':
          description: diagnostics report
          content:
            application/json:
              example:
                spree_version: 6.0.3
                sections:
                  - key: platform
                    title: Spree
                    rows:
                      - label: Version
                        value: 6.0.3
                      - label: Gems
                        value: spree_api 6.0.3, spree_core 6.0.3
                      - label: Other gems built on Spree
                        value: '0'
                  - key: runtime
                    title: Runtime
                    rows:
                      - label: Ruby
                        value: 4.0.9 (arm64-darwin25)
                      - label: Rails
                        value: 8.1.4.1
                      - label: Environment
                        value: test
                      - label: Operating system
                        value: Linux 6.8.0 x86_64
                      - label: Web server
                        value: Puma 8.0.2
                  - key: infrastructure
                    title: Infrastructure
                    rows:
                      - label: Database
                        value: sqlite3 3.54.1
                      - label: Queue adapter
                        value: test
                      - label: Cache store
                        value: null_store
                      - label: File storage
                        value: test
                  - key: preferences
                    title: Changed settings
                    rows: []
                  - key: dashboard
                    title: Dashboard
                    rows:
                      - label: '@spree/dashboard'
                        value: 6.0.4
                errors: []
                generated_at: '2026-01-15T12:00:00.000Z'
                markdown: >-
                  <details>

                  <summary>Spree 6.0.3 diagnostics
                  (2026-01-15T12:00:00Z)</summary>


                  **Spree**


                  | | |

                  | --- | --- |

                  | Version | 6.0.3 |

                  | Gems | spree_api 6.0.3, spree_core 6.0.3 |

                  | Other gems built on Spree | 0 |


                  **Runtime**


                  | | |

                  | --- | --- |

                  | Ruby | 4.0.9 (arm64-darwin25) |

                  | Rails | 8.1.4.1 |

                  | Environment | test |

                  | Operating system | Linux 6.8.0 x86_64 |

                  | Web server | Puma 8.0.2 |


                  **Infrastructure**


                  | | |

                  | --- | --- |

                  | Database | sqlite3 3.54.1 |

                  | Queue adapter | test |

                  | Cache store | null_store |

                  | File storage | test |


                  **Dashboard**


                  | | |

                  | --- | --- |

                  | @spree/dashboard | 6.0.4 |


                  **Recent errors**


                  None recorded.


                  </details>
                issue_url: >-
                  https://github.com/spree/spree/issues/new?template=bug_report.yml&environment=%3Cdetails%3E%0A%3Csummary%3ESpree%206.0.3%20diagnostics%20%282026-01-15T12%3A00%3A00Z%29%3C%2Fsummary%3E%0A%0A%2A%2ASpree%2A%2A%0A%0A%7C%20%7C%20%7C%0A%7C%20---%20%7C%20---%20%7C%0A%7C%20Version%20%7C%206.0.3%20%7C%0A%7C%20Gems%20%7C%20spree_api%206.0.3%2C%20spree_core%206.0.3%20%7C%0A%7C%20Other%20gems%20built%20on%20Spree%20%7C%200%20%7C%0A%0A%2A%2ARuntime%2A%2A%0A%0A%7C%20%7C%20%7C%0A%7C%20---%20%7C%20---%20%7C%0A%7C%20Ruby%20%7C%204.0.9%20%28arm64-darwin25%29%20%7C%0A%7C%20Rails%20%7C%208.1.4.1%20%7C%0A%7C%20Environment%20%7C%20test%20%7C%0A%7C%20Operating%20system%20%7C%20Linux%206.8.0%20x86_64%20%7C%0A%7C%20Web%20server%20%7C%20Puma%208.0.2%20%7C%0A%0A%2A%2AInfrastructure%2A%2A%0A%0A%7C%20%7C%20%7C%0A%7C%20---%20%7C%20---%20%7C%0A%7C%20Database%20%7C%20sqlite3%203.54.1%20%7C%0A%7C%20Queue%20adapter%20%7C%20test%20%7C%0A%7C%20Cache%20store%20%7C%20null_store%20%7C%0A%7C%20File%20storage%20%7C%20test%20%7C%0A%0A%2A%2ADashboard%2A%2A%0A%0A%7C%20%7C%20%7C%0A%7C%20---%20%7C%20---%20%7C%0A%7C%20%40spree%2Fdashboard%20%7C%206.0.4%20%7C%0A%0A%2A%2ARecent%20errors%2A%2A%0A%0ANone%20recorded.%0A%0A%3C%2Fdetails%3E
                issue_prefilled: true
              schema:
                $ref: '#/components/schemas/Diagnostics'
        '401':
          description: unauthorized
          content:
            application/json:
              example:
                error:
                  code: authentication_required
                  message: Authentication required
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer_auth: []
      x-codeSamples:
        - lang: javascript
          label: Spree Admin SDK
          source: |-
            import { createAdminClient } from '@spree/admin-sdk'

            const client = createAdminClient({
              baseUrl: 'https://your-store.com',
              jwtToken: 'eyJhbGciOi...',
            })

            // Needs a client created with `jwtToken`: a secret key is refused.
            const report = await client.diagnostics.get()
            console.log(report.markdown)
components:
  schemas:
    Diagnostics:
      type: object
      properties:
        spree_version:
          type: string
        sections:
          type: array
          items:
            type: object
        errors:
          type: array
          items:
            type: object
        generated_at:
          type: string
        markdown:
          type: string
        issue_url:
          type: string
        issue_prefilled:
          type: boolean
      required:
        - spree_version
        - sections
        - errors
        - generated_at
        - markdown
        - issue_url
        - issue_prefilled
      x-typelizer: true
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: record_not_found
            message:
              type: string
              example: Record not found
            details:
              type: object
              description: Field-specific validation errors
              nullable: true
              example:
                name:
                  - is too short
                  - is required
                email:
                  - is invalid
          required:
            - code
            - message
      required:
        - error
      example:
        error:
          code: validation_error
          message: Validation failed
          details:
            name:
              - is too short
            email:
              - is invalid
  securitySchemes:
    bearer_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token for admin user authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.