openapi: 3.2.0
info:
  title: AlphaLoops FMCSA Carrier Data Carriers API
  version: 1.0.0
  description: 'Fleet intelligence API for looking up FMCSA-registered carriers by DOT number, MC number, or company name. Access carrier profiles with 200+ fields, safety data, authority history, fleet equipment, inspections, crashes, news, and decision-maker contacts.


    Base URL: https://api.runalphaloops.com


    API access is available exclusively on the Enterprise plan. Contact sales at https://runalphaloops.com/contact to get your API key.'
  contact:
    name: AlphaLoops
    url: https://runalphaloops.com/contact
    email: hello@runalphaloop.com
servers:
- url: https://api.runalphaloops.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Carriers
paths:
  /v1/carriers/{dot_number}:
    get:
      operationId: getCarrierByDot
      summary: Look up a carrier by DOT number
      description: Returns the full carrier profile with 200+ fields including identity, authority, safety, fleet, technology stack, and contacts. Use the fields parameter to project only the fields you need.
      parameters:
      - name: dot_number
        in: path
        required: true
        schema:
          type: string
        description: The carrier's USDOT number
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated list of fields to return (e.g. "legal_name,power_units,latitude,longitude"). Omit to return all fields.
      responses:
        '200':
          description: Full carrier profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/mc/{mc_number}:
    get:
      operationId: getCarrierByMc
      summary: Look up a carrier by MC/MX docket number
      description: Returns the full carrier profile (same fields as the DOT lookup). Supports the same ?fields= projection parameter.
      parameters:
      - name: mc_number
        in: path
        required: true
        schema:
          type: string
        description: The carrier's MC or MX docket number
      - name: fields
        in: query
        required: false
        schema:
          type: string
        description: Comma-separated list of fields to return. Omit to return all fields.
      responses:
        '200':
          description: Full carrier profile
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierProfile'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/search:
    get:
      operationId: searchCarriers
      summary: Match a company to a carrier by name
      description: Match a company to a carrier by name, domain, state, and city. Returns ranked results with a confidence score. At minimum, company_name is required.
      parameters:
      - name: company_name
        in: query
        required: true
        schema:
          type: string
        description: Company name to match against (fuzzy matching)
      - name: domain
        in: query
        required: false
        schema:
          type: string
        description: Company website domain (e.g. "swifttrans.com") — improves match accuracy
      - name: state
        in: query
        required: false
        schema:
          type: string
        description: State abbreviation (e.g. "TX", "CA")
      - name: city
        in: query
        required: false
        schema:
          type: string
        description: City name (e.g. "Phoenix", "Dallas")
      - $ref: '#/components/parameters/page'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 10
          maximum: 50
        description: 'Results per page (default: 10, max: 50)'
      responses:
        '200':
          description: Paginated search results with confidence scores
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierSearchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/authority:
    get:
      operationId: getCarrierAuthority
      summary: Get carrier operating authority history
      description: Returns all authority actions including grants, revocations, and reinstatements.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Authority history records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthorityResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/trucks:
    get:
      operationId: getCarrierTrucks
      summary: Get carrier truck (power unit) fleet
      description: Returns the carrier's registered truck fleet. Includes VIN, make, model, engine specs, weight, and manufacturing details.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: 'Results per page (default: 50, max: 200)'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Paginated truck fleet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrucksResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/trailers:
    get:
      operationId: getCarrierTrailers
      summary: Get carrier trailer fleet
      description: Returns the carrier's registered trailer fleet. Includes VIN, manufacturer, type, and reefer status.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: 'Results per page (default: 50, max: 200)'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Paginated trailer fleet
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrailersResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/inspections:
    get:
      operationId: getCarrierInspections
      summary: Get carrier inspection history
      description: Returns roadside inspection history with metadata and out-of-service counts. Use /v1/inspections/{inspection_id}/violations to get violation details for a specific inspection.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: 'Results per page (default: 50, max: 200)'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Paginated inspection records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InspectionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/crashes:
    get:
      operationId: getCarrierCrashes
      summary: Get carrier crash history
      description: Returns reported crash history with details, severity, and contributing factors.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: start_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter from date (ISO 8601, e.g. "2024-01-01")
      - name: end_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter to date (ISO 8601, e.g. "2024-12-31")
      - name: severity
        in: query
        required: false
        schema:
          type: string
          enum:
          - FATAL
          - INJURY
          - TOW
          - PROPERTY_DAMAGE
        description: Filter by severity
      - $ref: '#/components/parameters/page'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
          maximum: 100
        description: 'Results per page (default: 25, max: 100)'
      responses:
        '200':
          description: Paginated crash records
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CrashesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/news:
    get:
      operationId: getCarrierNews
      summary: Get carrier news and press mentions
      description: Returns recent news articles and press mentions related to the carrier.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: start_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter from date (ISO 8601)
      - name: end_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Filter to date (ISO 8601)
      - $ref: '#/components/parameters/page'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
          maximum: 100
        description: 'Results per page (default: 25, max: 100)'
      responses:
        '200':
          description: Paginated news articles
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NewsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/query:
    post:
      operationId: queryCarriers
      summary: Advanced filtered carrier search
      description: Filtered search with include/exclude conditions, geo-radius search, sorting, and field projection. No company name required — filter by state, fleet size, cargo type, technology, authority status, revenue, and more.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CarrierQueryRequest'
      responses:
        '200':
          description: Paginated, optionally field-projected carrier results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CarrierQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/insurance:
    get:
      operationId: getCarrierInsurance
      summary: Get carrier insurance filings
      description: Retrieve insurance filings (BIPD, cargo, bond) for a carrier from the FMCSA insurance table. Includes policy numbers, coverage limits, and insurer details.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 500
        description: 'Results per page (default: 50, max: 500)'
      - $ref: '#/components/parameters/page'
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - effective_date
          - insurance_type_code
          - bipd_maximum_dollar_limit
          - insurance_company_name
          default: effective_date
        description: Sort field
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        description: Sort direction
      - name: insurance_type
        in: query
        required: false
        schema:
          type: string
        description: Filter by insurance type code (e.g. BIPD, CARGO, BOND)
      - name: insurer
        in: query
        required: false
        schema:
          type: string
        description: Partial match on insurance company name
      - name: min_coverage
        in: query
        required: false
        schema:
          type: integer
        description: Minimum BIPD dollar limit
      - name: date_from
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Effective date start (ISO date)
      - name: date_to
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Effective date end (ISO date)
      responses:
        '200':
          description: Paginated insurance filings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsuranceResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/mc/{mc_number}/insurance:
    get:
      operationId: getCarrierInsuranceByMc
      summary: Get carrier insurance filings by MC number
      description: Retrieve insurance filings by MC docket number. Same response shape and filters as the DOT-based insurance endpoint.
      parameters:
      - name: mc_number
        in: path
        required: true
        schema:
          type: string
        description: MC docket number (numeric)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 500
        description: 'Results per page (default: 50, max: 500)'
      - $ref: '#/components/parameters/page'
      - name: sort_by
        in: query
        required: false
        schema:
          type: string
          enum:
          - effective_date
          - insurance_type_code
          - bipd_maximum_dollar_limit
          - insurance_company_name
          default: effective_date
        description: Sort field
      - name: sort_order
        in: query
        required: false
        schema:
          type: string
          enum:
          - asc
          - desc
          default: desc
        description: Sort direction
      - name: insurance_type
        in: query
        required: false
        schema:
          type: string
        description: Filter by insurance type code
      - name: insurer
        in: query
        required: false
        schema:
          type: string
        description: Partial match on insurance company name
      - name: min_coverage
        in: query
        required: false
        schema:
          type: integer
        description: Minimum BIPD dollar limit
      responses:
        '200':
          description: Paginated insurance filings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsuranceResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/timeline:
    get:
      operationId: getCarrierTimeline
      summary: Get carrier change-event and authority timeline
      description: Merged chronological feed of carrier change events and authority history. Combines field-level changes from monthly FMCSA census diffs (contact, address, fleet, operations, authority, people) with authority history records.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: 'Max results (default: 50, max: 200)'
      - $ref: '#/components/parameters/offset'
      - name: category
        in: query
        required: false
        schema:
          type: string
        description: 'Comma-separated categories: contact, address, fleet, operations, authority, people'
      - name: date_from
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Start date (ISO date)
      - name: date_to
        in: query
        required: false
        schema:
          type: string
          format: date
        description: End date (ISO date)
      responses:
        '200':
          description: Merged timeline of change events and authority actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TimelineResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/mc-sales:
    get:
      operationId: getCarrierMcSales
      summary: Get authority-for-sale listings for a carrier
      description: 'Returns any authority-for-sale listings (Facebook groups, Telegram channels, BizBuySell, etc.) linked to this carrier''s DOT number, with seller info, asking prices, post URLs, and matching reasoning. Returns found: false with mc_sale: null when no listings are linked.'
      parameters:
      - name: dot_number
        in: path
        required: true
        schema:
          type: integer
        description: The carrier's USDOT number
      responses:
        '200':
          description: 'Authority-for-sale listings, or a found: false sentinel when none are linked'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McSalesResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/equipment-for-sale:
    get:
      operationId: getCarrierEquipmentForSale
      summary: Get carrier fleet VINs listed for sale
      description: Cross-references the VINs this carrier has been inspected with against a marketplace dataset of trucks and trailers currently (or recently) listed for sale. Returns one row per matching VIN, sorted by most recent inspection date. Empty results are common.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 25
          maximum: 200
        description: 'Results per page (default: 25, max: 200)'
      - $ref: '#/components/parameters/page'
      responses:
        '200':
          description: Paginated equipment-marketplace matches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EquipmentForSaleResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/connections:
    get:
      operationId: getCarrierConnections
      summary: Get a carrier's relationship graph
      description: Retrieve a carrier's corporate connections graph — shared officers, addresses, phones, emails, and equipment linking it to other carriers.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 50
          maximum: 200
        description: 'Max results (default: 50, max: 200)'
      responses:
        '200':
          description: Connection graph nodes and edges
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/risk-signals:
    get:
      operationId: getCarrierRiskSignals
      summary: Get aggregated carrier risk signals
      description: Aggregated carrier risk assessment in a single call. Returns an AI-generated risk score (0-10) and level, plus six signal categories — authority-for-sale listings, equipment-for-sale marketplace matches, financial-distress indicators, fraud/chameleon patterns, historical authority/insurance/change-event patterns, and recent news sentiment. Each category carries a derived level of "high", "medium", "clear", or "unknown". The risk summary is cached; pass force_refresh=true to force regeneration.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: force_refresh
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: Set to true to bypass the cached risk summary and regenerate it from current signals (slower).
      - name: include_equipment
        in: query
        required: false
        schema:
          type: boolean
          default: true
        description: Set to false to skip the equipment-marketplace VIN lookup for a faster response.
      responses:
        '200':
          description: Scored risk header plus six derived signal categories
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RiskSignalsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/similar:
    get:
      operationId: getSimilarCarriers
      summary: Find carriers similar to a given carrier
      description: Find carriers similar to the specified carrier based on fleet size, location, cargo type, and other attributes.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
        description: 'Max results (default: 20, max: 100)'
      responses:
        '200':
          description: Ranked list of similar carriers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimilarResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
  /v1/carriers/{dot_number}/overview:
    get:
      operationId: getCarrierOverview
      summary: Get an AI-generated carrier overview
      description: Returns an AI-generated summary overview of a carrier including key highlights.
      parameters:
      - $ref: '#/components/parameters/dotNumber'
      responses:
        '200':
          description: AI-generated overview and highlights
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OverviewResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
      tags:
      - Carriers
components:
  schemas:
    TimelineEvent:
      type: object
      properties:
        id:
          oneOf:
          - type: integer
          - type: string
        dot_number:
          type: string
        detected_at:
          type: string
          format: date
        category:
          type: string
          enum:
          - contact
          - address
          - fleet
          - operations
          - authority
          - people
        event_type:
          type: string
        headline:
          type: string
        field_name:
          type: string
          nullable: true
        old_value:
          type: string
          nullable: true
        new_value:
          type: string
          nullable: true
        metadata:
          type: object
          nullable: true
          additionalProperties: true
        source:
          type: string
    CarrierSearchResult:
      type: object
      properties:
        dot_number:
          type: string
        legal_name:
          type: string
        dba_name:
          type: string
          nullable: true
        physical_city:
          type: string
        physical_state:
          type: string
        confidence:
          type: number
          description: Match confidence score 0.0–1.0
    ConnectionsResponse:
      type: object
      properties:
        dot_number:
          type: string
        total_nodes:
          type: integer
        total_edges:
          type: integer
        nodes:
          type: array
          items:
            $ref: '#/components/schemas/ConnectionNode'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/ConnectionEdge'
    FleetComposition:
      type: object
      properties:
        owned:
          type: integer
        leased:
          type: integer
    ConnectionNode:
      type: object
      properties:
        id:
          type: string
          description: DOT number
        label:
          type: string
        state:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        isFocal:
          type: boolean
          description: True for the queried carrier
      additionalProperties: true
    CarrierQueryRequest:
      type: object
      description: Filter body for POST /v1/carriers/query. All fields optional.
      properties:
        include:
          type: object
          description: Filter conditions to include. Supports scalar equality, arrays, range objects ({ min, max }), and a location object ({ latitude, longitude, radius_miles }).
          additionalProperties: true
          example:
            state: TX
            power_units:
              min: 50
            cargo_type:
            - Van
            - Reefer
            operating_authority_status: Active
            location:
              latitude: 29.76
              longitude: -95.37
              radius_miles: 100
        exclude:
          type: object
          description: Filter conditions to exclude (same shape as include).
          additionalProperties: true
        fields:
          type: array
          items:
            type: string
          description: Fields to return on each result (e.g. ["dot_number", "legal_name", "power_units"]).
        sort_by:
          type: string
          description: 'Sort field: power_units, drivers, date_added, safety_rating, annual_revenue, distance, etc.'
        sort_order:
          type: string
          enum:
          - asc
          - desc
          default: desc
        limit:
          type: integer
          default: 25
        page:
          type: integer
          default: 1
    AuthorityRecord:
      type: object
      properties:
        docket_number:
          type: string
        sub_number:
          type: string
        authority_type:
          type: string
        original_action:
          type: string
        original_served_date:
          type: string
          format: date
        disposition_action:
          type: string
        disposition_decided_date:
          type: string
          format: date
        disposition_served_date:
          type: string
          format: date
    GrowthMetrics:
      type: object
      properties:
        power_units_12m:
          type: integer
          description: Net power unit change over 12 months
        drivers_12m:
          type: integer
          description: Net driver change over 12 months
        power_units_24m:
          type: integer
          description: Net power unit change over 24 months
        drivers_24m:
          type: integer
          description: Net driver change over 24 months
    TrailersResponse:
      type: object
      properties:
        dot_number:
          type: string
        total_trailers:
          type: integer
        trailers:
          type: array
          items:
            $ref: '#/components/schemas/Trailer'
        limit:
          type: integer
        offset:
          type: integer
        total_results:
          type: integer
    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        total_results:
          type: integer
        total_pages:
          type: integer
    McSaleListing:
      type: object
      properties:
        seller_name:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        asking_price:
          type: string
          nullable: true
        authority_age:
          type: string
          nullable: true
        post_url:
          type: string
          nullable: true
        source_file:
          type: string
          nullable: true
        confidence:
          type: number
          nullable: true
          description: 0–1 match confidence for this observation
        reasoning:
          type: string
          nullable: true
    CarrierSearchResponse:
      type: object
      properties:
        total_results:
          type: integer
        results:
          type: array
          items:
            $ref: '#/components/schemas/CarrierSearchResult'
        pagination:
          $ref: '#/components/schemas/Pagination'
    Address:
      type: object
      properties:
        street:
          type: string
        city:
          type: string
        state:
          type: string
        zip:
          type: string
    OverviewResponse:
      type: object
      properties:
        dot_number:
          type: string
        overview:
          type: string
        highlights:
          type: array
          items:
            type: string
    InsuranceResponse:
      type: object
      properties:
        dot_number:
          type: string
        mc_number:
          type: integer
        total_policies:
          type: integer
        insurance:
          type: array
          items:
            $ref: '#/components/schemas/InsurancePolicy'
        pagination:
          $ref: '#/components/schemas/Pagination'
    NewsResponse:
      type: object
      properties:
        dot_number:
          type: string
        total_results:
          type: integer
        articles:
          type: array
          items:
            $ref: '#/components/schemas/NewsArticle'
    EquipmentForSaleResponse:
      type: object
      properties:
        dot_number:
          type: string
        total_listings:
          type: integer
        equipment:
          type: array
          items:
            $ref: '#/components/schemas/EquipmentForSaleItem'
        pagination:
          $ref: '#/components/schemas/Pagination'
    NewsArticle:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        url:
          type: string
          format: uri
        source:
          type: string
        date:
          type: string
          format: date-time
        type:
          type: string
        sentiment:
          type: string
          enum:
          - positive
          - negative
          - neutral
        image_url:
          type: string
          format: uri
          nullable: true
        categories:
          type: array
          items:
            type: string
        topics:
          type: array
          items:
            type: string
        people:
          type: array
          items:
            type: string
        companies:
          type: array
          items:
            type: string
    RiskSignalLevel:
      type: string
      enum:
      - high
      - medium
      - clear
      - unknown
      description: Derived severity for a single signal category.
    TrucksResponse:
      type: object
      properties:
        dot_number:
          type: string
        total_trucks:
          type: integer
        trucks:
          type: array
          items:
            $ref: '#/components/schemas/Truck'
        limit:
          type: integer
        offset:
          type: integer
        total_results:
          type: integer
    InspectionsResponse:
      type: object
      properties:
        dot_number:
          type: string
        total_inspections:
          type: integer
        inspections:
          type: array
          items:
            $ref: '#/components/schemas/Inspection'
        limit:
          type: integer
        offset:
          type: integer
        total_results:
          type: integer
    EquipmentForSaleItem:
      type: object
      description: A fleet VIN matched to a marketplace listing. equipment_type determines which extra fields are populated.
      properties:
        equipment_type:
          type: string
          enum:
          - truck
          - trailer
        vin:
          type: string
        last_seen_in_inspection:
          type: string
          format: date
          nullable: true
        inspection_count:
          type: integer
        listing_title:
          type: string
          nullable: true
        manufacturer:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        model_year:
          type: integer
          nullable: true
        price:
          type: number
          nullable: true
        category:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
      additionalProperties: true
    TimelineResponse:
      type: object
      properties:
        dot_number:
          type: string
        total:
          type: integer
        category_counts:
          type: object
          additionalProperties:
            type: integer
        limit:
          type: integer
        offset:
          type: integer
        events:
          type: array
          items:
            $ref: '#/components/schemas/TimelineEvent'
    Error:
      type: object
      properties:
        error:
          type: string
          description: Short error type
        message:
          type: string
          description: Human-readable description
      required:
      - error
      - message
    CompanyOfficer:
      type: object
      properties:
        name:
          type: string
        title:
          type: string
        email:
          type: string
          format: email
    InsurancePolicy:
      type: object
      properties:
        id:
          type: integer
        docket_number:
          type: string
        dot_number:
          type: string
        mc_number:
          type: integer
          nullable: true
        insurance_type:
          type: object
          properties:
            code:
              type: string
            description:
              type: string
        bipd:
          type: object
          properties:
            class_code:
              type: string
              nullable: true
            class_description:
              type: string
              nullable: true
            maximum_dollar_limit:
              type: integer
              nullable: true
            underlying_dollar_limit:
              type: integer
              nullable: true
        policy_number:
          type: string
          nullable: true
        effective_date:
          type: string
          format: date
        form:
          type: object
          properties:
            code:
              type: string
            description:
              type: string
        insurance_company_name:
          type: string
    Crash:
      type: object
      properties:
        crash_id:
          type: string
        report_number:
          type: string
        date:
          type: string
          format: date
        state:
          type: string
        city:
          type: string
        location:
          type: string
        fatalities:
          type: integer
        injuries:
          type: integer
        tow_away:
          type: boolean
        hazmat_released:
          type: boolean
        severity:
          type: string
          enum:
          - FATAL
          - INJURY
          - TOW
          - PROPERTY_DAMAGE
        vehicle_configuration:
          type: string
        cargo_body_type:
          type: string
        road_surface_condition:
          type: string
        trafficway:
          type: string
        weather_condition:
          type: string
        light_condition:
          type: string
        vehicles_in_accident:
          type: integer
        truck_or_bus:
          type: string
        gvw_rating:
          type: string
        federal_recordable:
          type: boolean
    Trailer:
      type: object
      properties:
        vin:
          type: string
        dot_number:
          type: string
        manufacturer:
          type: string
        model_year:
          type: integer
        trailer_type:
          type: string
        reefer:
          type: boolean
        license_plate:
          type: string
    RiskSignalsResponse:
      type: object
      properties:
        dot_number:
          type: string
        carrier_name:
          type: string
          nullable: true
        location:
          type: object
          properties:
            city:
              type: string
              nullable: true
            state:
              type: string
              nullable: true
        risk_score:
          type: number
          nullable: true
          description: AI-generated 0–10 risk score
        risk_level:
          type: string
          description: CRITICAL, HIGH, MEDIUM, LOW, CLEAR, or UNKNOWN
        summary:
          type: string
          nullable: true
        generated_at:
          type: string
          format: date-time
          nullable: true
        cached:
          type: boolean
          nullable: true
        summary_available:
          type: boolean
          description: False when the upstream summary service was unavailable and a carrier-stored fallback was used.
        signals:
          type: object
          properties:
            authority_for_sale:
              type: object
              properties:
                level:
                  $ref: '#/components/schemas/RiskSignalLevel'
                subtitle:
                  type: string
                evidence_summary:
                  type: string
                  nullable: true
                mc_sale:
                  type: object
                  nullable: true
                  additionalProperties: true
            equipment_for_sale:
              type: object
              properties:
                level:
                  $ref: '#/components/schemas/RiskSignalLevel'
                subtitle:
                  type: string
                match_count:
                  type: integer
                matches:
                  type: array
                  nullable: true
                  items:
                    type: object
                    additionalProperties: true
            financial_risk:
              type: object
              properties:
                level:
                  $ref: '#/components/schemas/RiskSignalLevel'
                subtitle:
                  type: string
                confidence:
                  type: string
                  nullable: true
                issues:
                  type: array
                  items:
                    type: string
                details:
                  type: string
                  nullable: true
                source:
                  type: string
                  nullable: true
                source_domains:
                  type: array
                  items:
                    type: string
            fraud_signals:
              type: object
              properties:
                level:
                  $ref: '#/components/schemas/RiskSignalLevel'
                subtitle:
                  type: string
                is_chameleon:
                  type: boolean
                confidence:
                  type: string
                  nullable: true
                indicators:
                  type: array
                  items:
                    type: string
                details:
                  type: string
                  nullable: true
                relationship_risk_summary:
                  type: string
                  nullable: true
            historical_patterns:
              type: object
              properties:
                level:
                  $ref: '#/components/schemas/RiskSignalLevel'
                subtitle:
                  type: string
                triggered_combos:
                  type: array
                  items:
                    $ref: '#/components/schemas/RiskTriggeredCombo'
                insurance:
                  type: object
                  nullable: true
                  additionalProperties: true
                authority:
                  type: object
                  nullable: true
                  additionalProperties: true
                change_events:
                  type: object
                  nullable: true
                  additionalProperties: true
            recent_activity:
              type: object
              properties:
                level:
                  $ref: '#/components/schemas/RiskSignalLevel'
                subtitle:
                  type: string
                negative_article_count:
                  type: integer
                article_count:
                  type: integer
    ConnectionEdge:
      type: object
      properties:
        source:
          type: string
        target:
          type: string
        connectionType:
          type: string
          description: shared_officer, shared_address, shared_phone, shared_email, shared_truck, shared_trailer, shared_surname
        sharedCount:
          type: integer
      additionalProperties: true
    TechnologyStack:
      type: object
      properties:
        eld_provider:
          type: string
          description: ELD/telematics provider name
        tms:
          type: string
          description: Transportation management system
        fuel_card:
          type: string
          description: Fuel card provider
    McSalesResponse:
      type: object
      properties:
        dot_number:
          type: integer
        found:
          type: boolean
        mc_sale:
          type: object
          nullable: true
          properties:
            mc_numbers:
              type: array
              items:
                type: string
            carrier:
              type: object
              properties:
                legal_name:
                  type: string
                  nullable: true
                dba_name:
                  type: string
                  nullable: true
                state:
                  type: string
                  nullable: true
                city:
                  type: string
                  nullable: true
                phone:
                  type: string
                  nullable: true
                email:
                  type: string
                  nullable: true
                officers:
                  type: array
                  items:
                    type: string
            summary:
              type: object
              properties:
                occurrence_count:
                  type: integer
                avg_confidence:
                  type: number
                  nullable: true
                max_confidence:
                  type: number
                  nullable: true
            listings:
              type: array
              items:
                $ref: '#/components/schemas/McSaleListing'
            first_seen:
              type: string
              format: date-time
              nullable: true
            last_seen:
              type: string
              format: date-time
              nullable: true
    CarrierQueryResponse:
      type: object
      properties:
        total_results:
          type: integer
        results:
          type: array
          description: Carrier objects projected to the requested fields (or default fields when fields is omitted). When a geo-radius filter is used, each result includes distance_miles.
          items:
            type: object
            additionalProperties: true
        pagination:
          $ref: '#/components/schemas/Pagination'
    AuthorityResponse:
      type: object
      properties:
        dot_number:
          type: string
        total_records:
          type: integer
        limit:
          type: integer
        offset:
          type: integer
        authority_history:
          type: array
          items:
            $ref: '#/components/schemas/AuthorityRecord'
    Inspection:
      type: object
      properties:
        inspection_id:
          type: string
        report_number:
          type: string
        date:
          type: string
          format: date
        state:
          type: string
        level:
          type: integer
        start_time:
          type: string
        end_time:
          type: string
        location:
          type: string
        facility:
          type: string
        carrier_name:
          type: string
        shipper_name:
          type: string
        gross_vehicle_weight:
          type: integer
        violations_total:
          type: integer
        driver_violations:
          type: integer
        vehicle_violations:
          type: integer
        hazmat_violations:
          type: integer
        oos_total:
          type: integer
        oos_driver:
          type: boolean
        oos_vehicle:
          type: boolean
        oos_hazmat:
          type: boolean
        traffic_enforcement:
          type: boolean
        size_weight_enforcement:
          type: boolean
    RiskTriggeredCombo:
      type: object
      properties:
        key:
          type: string
          description: Stable combo identifier (e.g. sold_mc_signature_30d)
        label:
          type: string
          description: Human-readable description
        severity:
          type: string
          enum:
          - high
          - medium
    SimilarResponse:
      type: object
      properties:
        dot_number:
          type: string
        similar_carriers:
          type: array
          items:
            $ref: '#/components/schemas/SimilarCarrier'
    Truck:
      type: object
      properties:
        vin:
          type: string
        dot_number:
          type: string
        cab_type:
          type: string
        make:
          type: string
        model:
          type: string
        model_year:
          type: integer
        engine_manufacturer:
          type: string
        engine_model:
          type: string
        engine_displacement:
          type: string
        engine_type:
          type: string
        engine_cylinders:
          type: integer
        license_plate:
          type: string
        manufactured_by:
          type: string
        manufactured_in:
          type: string
        gross_weight:
          type: integer
        body_type:
          type: string
        brake_system_type:
          type: string
        plant_city:
          type: string
        plant_state:
          type: string
    CarrierProfile:
      type: object
      description: Full carrier profile with 200+ fields. Key fields shown below — use ?fields= to project specific fields.
      properties:
        dot_number:
          type: string
        legal_name:
          type: string
        dba_name:
          type: string
          nullable: true
        mc_number:
          type: string
          nullable: true
        operating_authority_status:
          type: string
          enum:
          - AUTHORIZED
          - NOT AUTHORIZED
          - REVOKED
          - PENDING
        authority_types:
          type: array
          items:
            type: string
        authority_based_carrier_type:
          type: string
        carrier_type:
          type: string
        carrier_operation:
          type: string
          enum:
          - INTERSTATE
          - INTRASTATE
        safety_rating:
          type: string
        phone:
          type: string
        fax:
          type: string
          nullable: true
        cell_phone:
          type: string
          nullable: true
        timezone:
          type: string
        date_added:
          type: string
          format: date
        company_description:
          type: string
          nullable: true
        physical_address:
          $ref: '#/components/schemas/Address'
        latitude:
          type: number
        longitude:
          type: number
        power_units:
          type: integer
        day_cabs:
          type: integer
        sleeper_cabs:
          type: integer
        drivers:
          type: integer
        drivers_added_24m:
          type: integer
        trucks_added_24m:
          type: integer
        avg_truck_age_years:
          type: number
        fleet_composition:
          $ref: '#/components/schemas/FleetComposition'
        oos_rate:
          type: number
          description: Out-of-service rate percentage
        driver_oos_total:
          type: integer
        vehicle_oos_total:
          type: integer
        driver_oos_last_year:
          type: integer
        vehicle_oos_last_year:
          type: integer
        accidents_by_year:
          type: object
          additionalProperties:
            type: integer
        inspections_by_year:
          type: object
          additionalProperties:
            type: integer
        growth:
          $ref: '#/components/schemas/GrowthMetrics'
        services:
          type: array
          items:
            type: string
        cargo:
          type: array
          items:
            type: string
        trailers_by_type:
          type: object
          additionalProperties:
            type: integer
        technology:
          $ref: '#/components/schemas/TechnologyStack'
        company_officers:
          type: array
          items:
            $ref: '#/components/schemas/CompanyOfficer'
    SimilarCarrier:
      type: object
      properties:
        dot_number:
          type: string
        legal_name:
          type: string
        state:
          type: string
          nullable: true
        power_units:
          type: integer
          nullable: true
        similarity_score:
          type: number
      additionalProperties: true
    CrashesResponse:
      type: object
      properties:
        dot_number:
          type: string
        total_crashes:
          type: integer
        crashes:
          type: array
          items:
            $ref: '#/components/schemas/Crash'
        pagination:
          $ref: '#/components/schemas/Pagination'
  responses:
    BadRequest:
      description: Invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Carrier does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    RateLimited:
      description: Too many requests. Check X-RateLimit-Remaining and Retry-After headers.
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    offset:
      name: offset
      in: query
      required: false
      schema:
        type: integer
        default: 0
      description: 'Number of results to skip (default: 0)'
    limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        default: 50
      description: 'Results per page (default: 50)'
    page:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
      description: 'Page number (default: 1)'
    dotNumber:
      name: dot_number
      in: path
      required: true
      schema:
        type: string
      description: The carrier's USDOT number
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'API key provided by AlphaLoops. Include as: Authorization: Bearer YOUR_API_KEY'