GenLogs Mismatch alerts API

openapi: 3.2.0
info:
  title: GenLogs Mismatch alerts API
  version: 1.0.0
  description: 'GenLogs Truck Intelligence API. Ground-truth motor-carrier and shipper data from a nationwide roadside sensor network: carrier recommendations by lane, carrier and FMCSA profiles, carrier vetting, shipper lanes and facilities, onboarded-carrier contact management, mismatch observations, and alert webhooks. Base URL https://api.genlogs.io. Authentication uses an x-api-key header plus a short-lived Access-Token obtained from /auth/token; endpoint access is gated by named permissions.'
  contact:
    name: GenLogs
    url: https://docs.genlogs.io
    email: contact@genlogs.io
  x-provenance:
    method: searched
    source: https://docs.genlogs.io (per-endpoint embedded OpenAPI fragments + documented endpoints)
    assembled: '2026-07-19'
    operationIds: some operationIds normalized by API Evangelist where the provider fragments omitted them
servers:
- url: https://api.genlogs.io
  description: GenLogs Truck Intelligence API
security:
- ApiKeyAuth: []
  AccessToken: []
tags:
- name: Mismatch alerts
paths:
  /mismatch-observations:
    post:
      summary: Create mismatch observation alerts
      description: Creates one alert row per standalone USDOT or MC value, and one combined row per item in `pairs`. At least one of `usdots`, `mcs`, or `pairs` must be non-empty. `alert_name` is optional; when omitted or blank, stored as null. `logos` is optional and, when present, is normalized to lowercase, stored in `logos`, and used by mismatch detection. Logo matching remains case-insensitive. Unknown JSON properties are rejected.
      tags:
      - Mismatch alerts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExternalMismatchObservationsRequest'
      responses:
        '201':
          description: Mismatch alerts created successfully.
          content:
            application/json:
              schema:
                type: object
                required:
                - message
                - data
                properties:
                  message:
                    type: string
                  data:
                    type: object
                    properties:
                      created:
                        type: integer
                        description: Number of alerts inserted.
        '400':
          description: Bad request – validation error or empty usdots/mcs/pairs.
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
        '403':
          description: Forbidden – missing permission.
        '500':
          description: Internal Server Error.
      operationId: createMismatchObservation
    get:
      summary: List mismatch observations
      description: Returns mismatch observations for the authenticated customer only, ordered from newest to oldest. Paginated; default page size is 50. Returns 200 with an empty `mismatch_observations` array when none exist.
      tags:
      - Mismatch alerts
      parameters:
      - name: page
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          default: 1
        description: Page number (1-based).
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 50
        description: Number of items per page (max 500).
      responses:
        '200':
          description: Paginated list of mismatch observations for the customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MismatchObservationsListResponse'
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
        '403':
          description: Forbidden – missing permission.
      operationId: listMismatchObservations
  /mismatch-observations/{observation_id}:
    patch:
      summary: Update a mismatch observation
      description: Partial update of USDOT (`usdot`), MC (`mc`), `logos`, display name (`alert_name`), and/or `is_disabled`. Send at least one field. Requires permission `external-api-mismatch-observations` or admin. Only alerts belonging to the JWT `customer_id` can be updated; otherwise 403. `logos` values are normalized to lowercase before persistence and response. Logo matching remains case-insensitive. Returns the full updated observation (same shape as list items).
      tags:
      - Mismatch alerts
      parameters:
      - name: observation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Mismatch observation (alert) identifier.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MismatchObservationPatchRequest'
      responses:
        '200':
          description: Full updated mismatch observation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MismatchObservationItem'
        '400':
          description: 'Bad request – empty body, no updatable fields, invalid USDOT/MC, or validation error.

            '
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
        '403':
          description: Forbidden – missing permission, or observation belongs to another customer.
        '404':
          description: Mismatch observation not found or deleted.
      operationId: updateMismatchObservation
    delete:
      summary: Delete a mismatch observation
      description: Permanently removes the row (timestamp hard delete). This is separate from `is_disabled`, which only pauses processing. After delete, the observation no longer appears in GET list and cannot be PATCHed. Same permission as create/list/update. Returns 404 if the id is unknown, belongs to another customer, or is already deleted. Returns 404 if the id is unknown, belongs to another customer, or is already deleted.
      tags:
      - Mismatch alerts
      parameters:
      - name: observation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '204':
          description: Observation deleted successfully (no response body).
        '401':
          description: Unauthorized – Invalid or missing Access-Token.
        '403':
          description: Forbidden – missing permission.
        '404':
          description: Not found, wrong customer, or already deleted.
      operationId: deleteMismatchObservation
components:
  schemas:
    MismatchObservationPairRequest:
      type: object
      additionalProperties: false
      required:
      - mc
      - usdot
      properties:
        mc:
          type: string
          minLength: 1
          description: MC number for the combined alert row.
        usdot:
          type: string
          minLength: 1
          description: USDOT number for the combined alert row.
    ExternalMismatchObservationsRequest:
      type: object
      additionalProperties: false
      properties:
        usdots:
          type: array
          items:
            type: string
          description: USDOT numbers (strings). Each non-empty entry creates one alert.
          default: []
        mcs:
          type: array
          items:
            type: string
          description: MC numbers (strings). Each non-empty entry creates one alert.
          default: []
        pairs:
          type: array
          items:
            $ref: '#/components/schemas/MismatchObservationPairRequest'
          description: 'Paired MC/USDOT identifiers. Each item creates one combined alert row with both MC and USDOT in the stored criteria.

            '
          default: []
        logos:
          type: array
          nullable: true
          items:
            type: string
          description: 'Optional trailer logos list. Each value must be a non-empty string. Values are trimmed, deduplicated, and stored in lowercase format. Matching against the logos catalog.

            '
        alert_name:
          type: string
          nullable: true
          description: Optional display name; omitted or whitespace-only is stored as null.
    MismatchObservationItem:
      type: object
      required:
      - id
      - usdot
      - mc
      - is_disabled
      properties:
        id:
          type: string
          format: uuid
          description: Alert row identifier.
        alert_name:
          type: string
          nullable: true
          description: Optional display name; may be null if not set.
        usdot:
          type: string
          nullable: true
          description: USDOT value from stored criteria.
        mc:
          type: string
          nullable: true
          description: MC value from stored criteria.
        logos:
          type: array
          items:
            type: string
          description: Trailer logos from `logos`, returned in normalized lowercase format. Empty when not configured.
          default: []
        is_disabled:
          type: boolean
          description: Whether this mismatch observation alert is disabled.
        created_at:
          type: string
          format: date-time
          nullable: true
          description: Creation timestamp when available.
        last_run_at:
          type: string
          format: date-time
          nullable: true
          description: Last run timestamp in ISO-8601 format; null when not run yet.
    MismatchObservationsListResponse:
      type: object
      required:
      - mismatch_observations
      - page
      - page_size
      - total
      properties:
        mismatch_observations:
          type: array
          items:
            $ref: '#/components/schemas/MismatchObservationItem'
        page:
          type: integer
          minimum: 1
          description: Current page number.
        page_size:
          type: integer
          minimum: 1
          maximum: 500
          description: Page size used for this response.
        total:
          type: integer
          minimum: 0
          description: Total number of observations for this customer (all pages).
    MismatchObservationPatchRequest:
      type: object
      additionalProperties: false
      description: 'At least one property must be present (after applying ignore rules). Omitted fields are left unchanged. Empty string or whitespace-only `usdot` / `mc` values are ignored (they do not clear the field). JSON `null` for `usdot` / `mc` still clears that side of the criteria when present. USDOT/MC validation matches create rules (numeric after normalization).

        '
      properties:
        usdot:
          type: string
          nullable: true
          description: New USDOT value; null clears when paired with MC update rules.
        mc:
          type: string
          nullable: true
          description: New MC value; null clears when paired with USDOT update rules.
        logos:
          type: array
          nullable: true
          items:
            type: string
          description: 'Trailer logos list. Values are trimmed, deduplicated, and stored/returned in lowercase format. Matching against the logos catalog.

            '
        alert_name:
          type: string
          nullable: true
          description: Display name; blank or whitespace-only is stored as null.
        is_disabled:
          type: boolean
          description: Whether the observation is disabled.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key provided by GenLogs. Required on every request.
    AccessToken:
      type: apiKey
      in: header
      name: Access-Token
      description: Short-lived access token obtained from POST /auth/token (or refreshed via /auth/token/refresh).