# method: generated
# source: https://help.dext.com/en/articles/272702-data-health-insights-api
# note: Faithful OpenAPI generated from Dext's published Data Health & Insights API
#       documentation. Only documented operations, parameters, auth, and the
#       documented rate-limit (429) behaviour are captured. Response object
#       schemas are left as open objects where the docs do not enumerate fields
#       (no field names were invented).
openapi: 3.0.3
info:
  title: Dext Data Health & Insights API
  version: '1.0'
  description: >-
    Read-only REST API for accounting/bookkeeping practices to extract client
    data-health metrics and activity statistics from Dext. Authenticate with a
    bearer token created in Practice settings > Data Health > API tokens.
    Rate limited to 60 requests per minute.
  contact:
    name: Dext Support
    url: https://help.dext.com/
servers:
  - url: https://api.precision.dext.com
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Clients
    description: Practice client data-health metrics and activity statistics
paths:
  /clients:
    get:
      tags: [Clients]
      operationId: listClients
      summary: List clients
      description: Returns a summarised list of all clients the token has access to.
      responses:
        '200':
          description: A summarised list of clients.
          headers:
            X-RateLimit-Limit:
              schema: { type: integer }
              description: Request ceiling per minute (60).
            X-RateLimit-Remaining:
              schema: { type: integer }
              description: Requests remaining in the current window.
          content:
            application/json:
              schema:
                type: array
                items: { $ref: '#/components/schemas/ClientSummary' }
        '401':
          description: Missing or invalid bearer token.
        '429':
          $ref: '#/components/responses/RateLimited'
  /clients/{clientId}:
    get:
      tags: [Clients]
      operationId: getClient
      summary: Get client detail
      description: >-
        Returns detailed information for a single client, including data-health
        metrics, VAT details, and bank reconciliation data.
      parameters:
        - name: clientId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Detailed client record.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ClientDetail' }
        '401':
          description: Missing or invalid bearer token.
        '404':
          description: Client not found or not accessible to this token.
        '429':
          $ref: '#/components/responses/RateLimited'
  /clients/{clientId}/activity-stats:
    get:
      tags: [Clients]
      operationId: getClientActivityStats
      summary: Get client activity statistics
      description: >-
        Returns rolling annual, monthly-average, and quarterly-average activity
        statistics for a single client.
      parameters:
        - name: clientId
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: Rolling activity statistics for the client.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ActivityStats' }
        '401':
          description: Missing or invalid bearer token.
        '404':
          description: Client not found or not accessible to this token.
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        API token created in Practice settings > Data Health > API tokens,
        sent as `Authorization: Bearer <token>`. The token value is shown once
        on creation and cannot be retrieved afterwards.
  responses:
    RateLimited:
      description: >-
        Rate limit exceeded (more than 60 requests per minute).
      headers:
        X-RateLimit-Limit:
          schema: { type: integer }
        X-RateLimit-Remaining:
          schema: { type: integer }
  schemas:
    ClientSummary:
      type: object
      description: >-
        Summarised client record as returned by the list endpoint. Field names
        are not enumerated in the public documentation.
    ClientDetail:
      type: object
      description: >-
        Detailed client record including data-health metrics, VAT details, and
        bank reconciliation data. Field names are not enumerated in the public
        documentation.
    ActivityStats:
      type: object
      description: >-
        Rolling annual, monthly-average, and quarterly-average activity
        statistics. Field names are not enumerated in the public documentation.