Decisiv Faults API

openapi: 3.2.0
info:
  title: Decisiv Faults API
  version: 0.48.24
  contact:
    name: Decisiv Support
    email: support@decisiv.com
    url: https://www.decisiv.com
  license:
    name: Proprietary
    identifier: proprietary
    url: https://www.decisiv.com/terms-of-use/
  termsOfService: https://www.decisiv.com/terms-of-use
  description: 'Operations tagged Faults across 2 of this provider''s published API definitions: decisiv-service-management-openapi.yml, decisiv-telematics-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://srm-api.staging.decisivapps.com
- url: https://srm-api.decisivapps.com
security:
- OAuth2AuthorizationCode: []
  AccessToken: []
- OAuth2Password: []
  AccessToken: []
tags:
- name: Faults
paths:
  /service_management/{srm_account_id}/v1/cases/{case_id}/faults:
    get:
      summary: List all Faults for a specific Case in the requested account
      tags:
      - Faults
      parameters:
      - name: srm_account_id
        in: path
        description: The account ID for SRM
        required: true
        schema:
          type: string
      - name: case_id
        in: path
        schema:
          type: string
          format: uuid
        description: The case UUID
        required: true
      - name: page[number]
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
        description: Sets the desired `page` when encountering larger result sets
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
          default: 25
          minimum: 1
        description: Sets the desired maximum number of results per page
      responses:
        '200':
          description: Returns list of Faults for a case
          content:
            application/vnd.api+json:
              example:
                data:
                - id: 1e4797e6-cdb0-4bc1-9cd0-41050e53df17
                  type: faults
                  attributes:
                    triggered_at: 2025-04-10 13:30:41 UTC
                    spn: '3456'
                    fmi: '19'
                    fault_code: '1223'
                    sensor_readings:
                    - name: AFTRT 1 Intake NOx
                      description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
                      value: '115.8'
                      unit_of_measure: ppm
                      classification_header: Engine Operation
                      key_data: false
                      localize: false
                    guidance:
                    - name: AFTRT 2 NOx
                      description: Aftertreatment 1
                      value: '15.8'
                      classification_header: Engine Operation
                    location:
                      heading: '251'
                      altitude: '3649'
                      latitude: '-58.28'
                      longitude: '152.41'
                    details:
                      components:
                        name: ECU
                        description: 'The #1 on the Engine CA is to identify that this is the first PA being used for the particular function, Engine. It may only be used for the NAME Function of 0'
                        version: Engine
                      occurrences: '3'
                      odometer_unit: mi
                      odometer_value: '23993123'
                      severity_level: '2'
                    active: false
                    diagnostic_reading_id: null
                    severity: 2
                    created_by: user
                    updated_by: user
                  relationships:
                    diagnostic_reading:
                      data:
                        type: diagnostic_readings
                        id: 447e4535-78bf-4661-a06f-8dbd39d4f3fb
                    asset:
                      data:
                        type: assets
                        id: 3fdd7ee5-ce1a-45b6-a938-b3e367952e0b
              schema:
                $ref: '#/components/schemas/faults'
        '400':
          description: This response may occur when an invalid request has been provided to the server.  The request may be corrected by the consumer and resubmitted.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Filter not allowed
                  detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
                  code: decisiv:filters:001
                  status: '400'
                  source:
                    parameter: filter[filter_name]
              schema:
                $ref: '#/components/schemas/errors_response'
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response'
        '404':
          description: This response may occur when the requested resource is not found.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Record not found
                  detail: The requested record or one of its relationships could not be found
                  code: '404'
                  status: '404'
              schema:
                $ref: '#/components/schemas/errors_response'
        '424':
          description: This response may occur when there is an unresolved data dependency or configuration required inside of the Decisiv Platform preventing access to the requested action.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Failed Dependency
                  detail: Failed Dependency
                  code: '424'
                  status: '424'
              schema:
                $ref: '#/components/schemas/errors_response'
        '504':
          description: This response may occur when there is an unexpected system timeout.
          content:
            application/vnd.api+json:
              example:
                errors:
                - code: '504'
                  detail: Gateway timeout error
                  status: '504'
                  title: Gateway timeout error
              schema:
                $ref: '#/components/schemas/errors_response'
    servers:
    - url: https://srm-api.staging.decisivapps.com
    - url: https://srm-api.decisivapps.com
  /telematics/{srm_account_id}/v1/faults:
    get:
      operationId: listFaults
      summary: List all faults for the requested account
      description: Retrieve all faults for a specific SRM account.
      tags:
      - Faults
      parameters:
      - name: srm_account_id
        in: path
        description: The account ID for SRM
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Returns list of Faults
          content:
            application/vnd.api+json:
              example:
                data:
                - id: 44e10524-07a3-4008-8bcd-08950f3b00e8
                  type: faults
                  attributes:
                    triggered_at: '2025-03-11T18:48:34Z'
                    spn: '3456'
                    fmi: '19'
                    fault_code: '1223'
                    sensor_readings:
                    - name: AFTRT 1 Intake NOx
                      description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
                      value: '115.8'
                      unit_of_measure: ppm
                      classification_header: Engine Operation
                      key_data: false
                      localize: false
                    guidance:
                    - name: AFTRT 2 NOx
                      description: Take to the closest dealer immediately!
                      value: '15.8'
                      classification_header: Engine Operation
                    location:
                      heading: '251'
                      altitude: '3649'
                      latitude: '-58.28'
                      longitude: '152.41'
                    details:
                      component:
                        name: ECU
                        description: Component description
                        version: Engine
                      occurrences: 3
                      odometer_unit: mi
                      odometer_value: 23993123
                      severity_level: Severe
                      description: Fault description
                    active: false
                    severity: 2
                    external_resources:
                    - href: https://telematics-source.oem-system.com/videos/28972.mp4
                      title: Interactive Video
                      description: Video to accelerate repair time and uptime.
                      classification_header: Repair Information
                      type: video
                  relationships:
                    diagnostic_reading:
                      data:
                        type: diagnostic_readings
                        id: 3cad1e59-8eed-410f-9a15-527d11cba0d0
                    source_account:
                      data:
                        type: srm_accounts
                        id: dc8beef2-e304-11ea-86c2-1f9b5bc5281b
                    asset:
                      data:
                        type: assets
                        id: 73b781e9-d724-4c8c-89fe-b289abade626
                  links:
                    self: https://srm-api.decisivapps.com/telematics/v1/faults/44e10524-07a3-4008-8bcd-08950f3b00e8
              schema:
                $ref: '#/components/schemas/faults'
        '400':
          description: This response may occur when an invalid request has been provided to the server.  The request may be corrected by the consumer and resubmitted.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Filter not allowed
                  detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
                  code: decisiv:filters:001
                  status: '400'
                  source:
                    parameter: filter[filter_name]
              schema:
                $ref: '#/components/schemas/errors_response'
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response'
        '404':
          description: This response may occur when the requested resource is not found.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Record not found
                  detail: The requested record or one of its relationships could not be found
                  code: '404'
                  status: '404'
              schema:
                $ref: '#/components/schemas/errors_response'
        '424':
          description: This response may occur when there is an unresolved data dependency or configuration required inside of the Decisiv Platform preventing access to the requested action.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Failed Dependency
                  detail: Failed Dependency
                  code: '424'
                  status: '424'
              schema:
                $ref: '#/components/schemas/errors_response'
        '504':
          description: This response may occur when there is an unexpected system timeout.
          content:
            application/vnd.api+json:
              example:
                errors:
                - code: '504'
                  detail: Gateway timeout error
                  status: '504'
                  title: Gateway timeout error
              schema:
                $ref: '#/components/schemas/errors_response'
    post:
      operationId: createFault
      summary: Create a new fault
      description: Create a new fault record for a specific SRM account.
      tags:
      - Faults
      parameters:
      - name: srm_account_id
        in: path
        description: The account ID for SRM
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Creates a new Fault record
          content:
            application/vnd.api+json:
              example:
                data:
                  id: 44e10524-07a3-4008-8bcd-08950f3b00e8
                  type: faults
                  attributes:
                    triggered_at: '2025-03-11T18:48:34Z'
                    spn: '3456'
                    fmi: '19'
                    fault_code: '1223'
                    sensor_readings:
                    - name: AFTRT 1 Intake NOx
                      description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
                      value: '115.8'
                      unit_of_measure: ppm
                      classification_header: Engine Operation
                      key_data: false
                      localize: false
                    guidance:
                    - name: AFTRT 2 NOx
                      description: Take to the closest dealer immediately!
                      value: '15.8'
                      classification_header: Engine Operation
                    location:
                      heading: '251'
                      altitude: '3649'
                      latitude: '-58.28'
                      longitude: '152.41'
                    details:
                      component:
                        name: ECU
                        description: Component description
                        version: Engine
                      occurrences: 3
                      odometer_unit: mi
                      odometer_value: 23993123
                      severity_level: Severe
                      description: Fault description
                    active: false
                    severity: 2
                    external_resources:
                    - href: https://telematics-source.oem-system.com/videos/28972.mp4
                      title: Interactive Video
                      description: Video to accelerate repair time and uptime.
                      classification_header: Repair Information
                      type: video
                  relationships:
                    diagnostic_reading:
                      data:
                        type: diagnostic_readings
                        id: 3cad1e59-8eed-410f-9a15-527d11cba0d0
                    source_account:
                      data:
                        type: srm_accounts
                        id: dc8beef2-e304-11ea-86c2-1f9b5bc5281b
                    asset:
                      data:
                        type: assets
                        id: 73b781e9-d724-4c8c-89fe-b289abade626
                  links:
                    self: https://srm-api.decisivapps.com/telematics/v1/faults/44e10524-07a3-4008-8bcd-08950f3b00e8
              schema:
                $ref: '#/components/schemas/fault'
        '400':
          description: Invalid Filter / Missing required key / Missing required value / Incorrect attribute for the resource type / Invalid Attribute Value on External Resources Type
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
              examples:
                Invalid Filter:
                  value:
                    errors:
                    - title: Filter not allowed
                      detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
                      code: decisiv:filters:001
                      status: '400'
                      source:
                        parameter: filter[filter_name]
                Missing required key:
                  value:
                    errors:
                    - status: '400'
                      code: decisiv:request_attributes:001
                      title: Missing required attribute key
                      detail: Required key not provided in request body
                      source:
                        pointer: /data/attributes/content
                Missing required value:
                  value:
                    errors:
                    - status: '400'
                      code: decisiv:request_attributes:002
                      title: Missing required attribute value
                      detail: Required key must be populated
                      source:
                        pointer: /data/attributes/content
                Incorrect attribute for the resource type:
                  value:
                    errors:
                    - status: '400'
                      code: decisiv:resource:002
                      title: Invalid JSON:API Resource specified in request
                      detail: '''{{invalid_resource}}'' is an invalid resource'
                      source:
                        pointer: /data/type
                Invalid Attribute Value on External Resources Type:
                  value:
                    errors:
                    - status: '400'
                      title: Invalid Attribute Value
                      detail: Invalid {{attribute_name}} value provided - {{reason}}
                      code: decisiv:request_attributes:010
                      source:
                        pointer: /data/attributes/external_resources/0/type
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response'
        '429':
          description: This response will often be associated as a result of an over abundance of calls by a specific Application, Account, or IP Address resulting in a required cool off period.
          content:
            application/vnd.api+json:
              example:
                errors:
                - code: '429'
                  detail: The maximum number of requests for this application has been far exceeded with the given credentials.
                  status: '429'
                  title: Too Many Requests
              schema:
                $ref: '#/components/schemas/errors_response'
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/create_fault'
            examples:
              Create fault:
                value:
                  data:
                    type: faults
                    attributes:
                      triggered_at: '2025-03-11T18:48:34Z'
                      spn: '3456'
                      fmi: '19'
                      fault_code: '1223'
                      sensor_readings:
                      - name: AFTRT 1 Intake NOx
                        description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
                        value: '115.8'
                        unit_of_measure: ppm
                        classification_header: Engine Operation
                        key_data: false
                        localize: false
                      guidance:
                      - name: AFTRT 2 NOx
                        description: Take to the closest dealer immediately!
                        value: '15.8'
                        classification_header: Engine Operation
                      location:
                        heading: '251'
                        altitude: '3649'
                        latitude: '-58.28'
                        longitude: '152.41'
                      details:
                        component:
                          name: ECU
                          description: Component description
                          version: Engine
                        occurrences: 3
                        odometer_unit: mi
                        odometer_value: 23993123
                        severity_level: Severe
                        description: Fault description
                      active: false
                      severity: 2
                      external_resources:
                      - href: https://telematics-source.oem-system.com/videos/28972.mp4
                        title: Interactive Video
                        description: Video to accelerate repair time and uptime.
                        classification_header: Repair Information
                        type: video
                    relationships:
                      diagnostic_reading:
                        data:
                          type: diagnostic_readings
                          id: 3cad1e59-8eed-410f-9a15-527d11cba0d0
    servers:
    - url: https://srm-api.staging.decisivapps.com
    - url: https://srm-api.decisivapps.com
  /telematics/{srm_account_id}/v1/faults/{uuid}:
    get:
      operationId: getFault
      summary: Get details for a specific fault
      description: Retrieve details for a specific fault by UUID.
      tags:
      - Faults
      parameters:
      - name: srm_account_id
        in: path
        description: The account ID for SRM
        required: true
        schema:
          type: string
      - name: uuid
        in: path
        schema:
          type: string
          format: uuid
        description: The fault UUID
        required: true
      responses:
        '200':
          description: Returns details for the requested fault
          content:
            application/vnd.api+json:
              example:
                data:
                  id: 44e10524-07a3-4008-8bcd-08950f3b00e8
                  type: faults
                  attributes:
                    triggered_at: '2025-03-11T18:48:34Z'
                    spn: '3456'
                    fmi: '19'
                    fault_code: '1223'
                    sensor_readings:
                    - name: AFTRT 1 Intake NOx
                      description: Aftertreatment 1 Intake NOx, Range -200 to 3012.75
                      value: '115.8'
                      unit_of_measure: ppm
                      classification_header: Engine Operation
                      key_data: false
                      localize: false
                    guidance:
                    - name: AFTRT 2 NOx
                      description: Take to the closest dealer immediately!
                      value: '15.8'
                      classification_header: Engine Operation
                    location:
                      heading: '251'
                      altitude: '3649'
                      latitude: '-58.28'
                      longitude: '152.41'
                    details:
                      component:
                        name: ECU
                        description: Component description
                        version: Engine
                      occurrences: 3
                      odometer_unit: mi
                      odometer_value: 23993123
                      severity_level: Severe
                      description: Fault description
                    active: false
                    severity: 2
                    external_resources:
                    - href: https://telematics-source.oem-system.com/videos/28972.mp4
                      title: Interactive Video
                      description: Video to accelerate repair time and uptime.
                      classification_header: Repair Information
                      type: video
                  relationships:
                    diagnostic_reading:
                      data:
                        type: diagnostic_readings
                        id: 3cad1e59-8eed-410f-9a15-527d11cba0d0
                    source_account:
                      data:
                        type: srm_accounts
                        id: dc8beef2-e304-11ea-86c2-1f9b5bc5281b
                    asset:
                      data:
                        type: assets
                        id: 73b781e9-d724-4c8c-89fe-b289abade626
                  links:
                    self: https://srm-api.decisivapps.com/telematics/v1/faults/44e10524-07a3-4008-8bcd-08950f3b00e8
              schema:
                $ref: '#/components/schemas/fault'
        '400':
          description: This response may occur when an invalid request has been provided to the server.  The request may be corrected by the consumer and resubmitted.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Filter not allowed
                  detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
                  code: decisiv:filters:001
                  status: '400'
                  source:
                    parameter: filter[filter_name]
              schema:
                $ref: '#/components/schemas/errors_response'
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response'
        '404':
          description: This response may occur when the requested resource is not found.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Record not found
                  detail: The requested record or one of its relationships could not be found
                  code: '404'
                  status: '404'
              schema:
                $ref: '#/components/schemas/errors_response'
        '424':
          description: This response may occur when there is an unresolved data dependency or configuration required inside of the Decisiv Platform preventing access to the requested action.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Failed Dependency
                  detail: Failed Dependency
                  code: '424'
                  status: '424'
              schema:
                $ref: '#/components/schemas/errors_response'
        '504':
          description: This response may occur when there is an unexpected system timeout.
          content:
            application/vnd.api+json:
              example:
                errors:
                - code: '504'
                  detail: Gateway timeout error
                  status: '504'
                  title: Gateway timeout error
              schema:
                $ref: '#/components/schemas/errors_response'
    servers:
    - url: https://srm-api.staging.decisivapps.com
    - url: https://srm-api.decisivapps.com
components:
  schemas:
    error_response:
      type: object
      properties:
        status:
          type: string
        title:
          type: string
        detail:
          type:
          - string
          - 'null'
        code:
          type:
          - string
          - 'null'
        source:
          type: object
          properties:
            parameter:
              type:
              - string
              - 'null'
            pointer:
              type:
              - string
              - 'null'
        links:
          type: object
          description: Links related to this error (e.g. documentation reference).
          additionalProperties:
            type: string
            format: uri
      required:
      - status
      - title
    properties-attributes:
      type: object
      properties:
        triggered_at:
          type: string
          format: date-time
          description: Date / Time when the diagnostic was triggered in `ISO8601` format
        spn:
          type:
          - string
          - 'null'
          description: SPN value. *Must be sent together with `fmi`. Either the SPN/FMI pair or `fault_code` is required.*
        fmi:
          type:
          - string
          - 'null'
          description: FMI value. *Must be sent together with `spn`. Either the SPN/FMI pair or `fault_code` is required.*
        fault_code:
          type:
          - string
          - 'null'
          description: Fault code value. *Required when SPN/FMI pair is not provided.*
        severity:
          type:
          - integer
          - 'null'
          minimum: 0
          maximum: 100
          description: Fault severity, ranging from `0` (lowest) to `100` (highest)
        active:
          type: boolean
          description: Indicates whether this fault is still active
        sensor_readings:
          type: array
          description: Sensor readings captured when the fault was triggered
          items:
            type: object
            properties:
              name:
                type:

# --- truncated at 32 KB (56 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/decisiv/refs/heads/main/openapi/decisiv-faults-api-openapi.yml