API Evangelist enhancements — AlphaLoops FMCSA Carrier Data API

overlay: 1.0.0
info:
  title: API Evangelist enhancements — AlphaLoops FMCSA Carrier Data API
  version: 1.0.0
extends: ../openapi/alphaloops-fmcsa-carrier-data-api-openapi.json

# generated: '2026-08-11'
# method: generated
# source: >-
#   Authored by API Evangelist against the live provider spec fetched from
#   https://runalphaloops.com/openapi.json on 2026-08-11. This overlay carries OUR enhancements
#   only — it never mutates the original, which is preserved verbatim at
#   openapi/_original/alphaloops-fmcsa-carrier-data-api-openapi.json.
#
# WHAT THIS OVERLAY FIXES, and why each item is a real defect rather than a preference:
#   1. tags is an empty array and NO operation is tagged, so the 25 operations have no navigable
#      grouping in any renderer or catalog. We add eight tags and tag every operation.
#   2. Pagination style is split between page/limit and offset/limit with no machine-readable
#      marker, and the provider warns about it only in prose. We annotate each affected operation
#      with x-pagination so a client can branch on it.
#   3. The collection array is named differently in nearly every response envelope. We record the
#      real key per operation as x-results-key.
#   4. Rate-limit headers are returned on every response and documented in prose, but declared
#      nowhere in the spec. We document them at the info level as x-rate-limit.
#   5. enrichContact is credit-metered with a 402 path; searchContacts can return 202. Both are
#      commercial/runtime facts absent from the contract. We annotate them.
#   6. 500 and 502 are documented in the provider's own error table but declared on no operation.
#      We note this at info level rather than inventing response objects.

actions:
  # --- 1. Tag vocabulary + external docs -----------------------------------------------------
  - target: $
    description: Add a tag vocabulary; the source spec declares an empty tags array.
    update:
      tags:
        - name: Carriers
          description: Carrier lookup, search, filtering and profile retrieval.
        - name: Authority
          description: Operating authority history and insurance filings.
        - name: Fleet
          description: VIN-level trucks and trailers.
        - name: Safety
          description: Roadside inspections, violations and crash history.
        - name: Risk
          description: Fraud, chameleon-carrier and financial-distress signals.
        - name: Contacts
          description: Decision-maker search and metered enrichment.
        - name: VINs
          description: VIN lookup and VIN-to-carrier association.
        - name: Signals
          description: Change events, news and market listings.
      externalDocs:
        description: AlphaLoops FMCSA API reference
        url: https://runalphaloops.com/fmcsa-api/docs

  # --- 2. Info-level runtime semantics --------------------------------------------------------
  - target: $.info
    description: >-
      Record the runtime contract the provider documents in prose but does not express in the spec.
    update:
      x-rate-limit:
        tier: Enterprise REST
        per_minute: 60
        per_day: 5000
        headers_on_every_response:
          - X-RateLimit-Limit
          - X-RateLimit-Remaining
          - X-RateLimit-Reset
          - X-DailyLimit-Limit
          - X-DailyLimit-Remaining
          - X-DailyLimit-Reset
        exhausted_status: 429
        retry_after: true
        source: https://runalphaloops.com/fmcsa-api/docs
      x-error-envelope:
        shape: '{"error": "...", "message": "..."}'
        rfc9457: false
        enumerated_error_values: false
      x-undeclared-responses:
        note: >-
          The provider's published error table documents 405, 500 and 502, none of which is
          declared on any operation in this spec. 405's stated rule ("only GET is supported")
          also contradicts the two POST operations the spec defines.
        statuses: [405, 500, 502]
      x-cors:
        preflight: 'OPTIONS -> 204'
        allow_origin: '*'
        caution: >-
          Wildcard origin with a static unscoped bearer key — browser use exposes the credential.
      x-pagination-warning: >-
        Two pagination styles coexist. page/limit is the default; trucks, trailers, inspections,
        authority and timeline use offset/limit instead.
      x-artifacts:
        conventions: conventions/alphaloops-conventions.yml
        errors: errors/alphaloops-problem-types.yml
        rate_limits: rate-limits/alphaloops-rate-limits.yml
        data_model: data-model/alphaloops-data-model.yml
        mcp_crosswalk: mcp/alphaloops-tool-crosswalk.yml

  # --- 3. Carriers -----------------------------------------------------------------------------
  - target: $.paths['/v1/carriers/{dot_number}'].get
    update:
      tags: [Carriers]
      x-field-projection: true
      x-results-key: null
  - target: $.paths['/v1/carriers/mc/{mc_number}'].get
    update:
      tags: [Carriers]
      x-field-projection: true
      x-mc-number-format-note: >-
        Provider examples show both bare ("183261") and prefixed ("MC-728261") forms; no canonical
        form is stated.
  - target: $.paths['/v1/carriers/search'].get
    update:
      tags: [Carriers]
      x-pagination: {style: page-limit, params: [page, limit], default_limit: 10, max_limit: 50}
      x-results-key: results
      x-required-query-param: company_name
      x-confidence-scored: true
  - target: $.paths['/v1/carriers/query'].post
    update:
      tags: [Carriers]
      x-pagination: {style: page-limit, params: [page, limit], default_limit: 25}
      x-results-key: results
      x-field-projection: {style: body-array, param: fields}
      x-capability: >-
        The most capable operation in the API — include/exclude filters, range objects, array
        membership, geo-radius, sorting.
  - target: $.paths['/v1/carriers/{dot_number}/overview'].get
    update:
      tags: [Carriers]
  - target: $.paths['/v1/carriers/{dot_number}/similar'].get
    update:
      tags: [Carriers]
      x-results-key: similar_carriers
      x-powered-by: carrier embedding model

  # --- 4. Authority + insurance ----------------------------------------------------------------
  - target: $.paths['/v1/carriers/{dot_number}/authority'].get
    update:
      tags: [Authority]
      x-pagination: {style: offset-limit, params: [offset, limit], default_limit: 50}
      x-results-key: authority_history
  - target: $.paths['/v1/carriers/{dot_number}/insurance'].get
    update:
      tags: [Authority]
      x-pagination: {style: page-limit, params: [page, limit]}
      x-results-key: insurance
  - target: $.paths['/v1/carriers/mc/{mc_number}/insurance'].get
    update:
      tags: [Authority]
      x-results-key: insurance

  # --- 5. Fleet ---------------------------------------------------------------------------------
  - target: $.paths['/v1/carriers/{dot_number}/trucks'].get
    update:
      tags: [Fleet]
      x-pagination: {style: offset-limit, params: [offset, limit], default_limit: 50}
      x-results-key: trucks
  - target: $.paths['/v1/carriers/{dot_number}/trailers'].get
    update:
      tags: [Fleet]
      x-pagination: {style: offset-limit, params: [offset, limit], default_limit: 50}
      x-results-key: trailers

  # --- 6. Safety ---------------------------------------------------------------------------------
  - target: $.paths['/v1/carriers/{dot_number}/inspections'].get
    update:
      tags: [Safety]
      x-pagination: {style: offset-limit, params: [offset, limit], default_limit: 50}
      x-results-key: inspections
  - target: $.paths['/v1/inspections/{inspection_id}/violations'].get
    update:
      tags: [Safety]
      x-pagination: {style: page-limit, params: [page, limit]}
      x-results-key: violations
  - target: $.paths['/v1/carriers/{dot_number}/crashes'].get
    update:
      tags: [Safety]
      x-pagination: {style: page-limit, params: [page, limit]}
      x-results-key: crashes
      x-enum-severity: [FATAL, INJURY, TOW, PROPERTY_DAMAGE]

  # --- 7. Risk + signals -------------------------------------------------------------------------
  - target: $.paths['/v1/carriers/{dot_number}/risk-signals'].get
    update:
      tags: [Risk]
  - target: $.paths['/v1/carriers/{dot_number}/connections'].get
    update:
      tags: [Risk]
      x-response-shape: graph
      x-results-key: [nodes, edges]
  - target: $.paths['/v1/carriers/{dot_number}/mc-sales'].get
    update:
      tags: [Risk]
      x-results-key: mc_sale
      x-missing-404: >-
        Unlike every other carrier sub-resource, this operation declares no 404 response. A client
        cannot distinguish an unknown DOT number from a carrier with no listing.
  - target: $.paths['/v1/carriers/{dot_number}/equipment-for-sale'].get
    update:
      tags: [Risk]
      x-pagination: {style: page-limit, params: [page, limit]}
      x-results-key: equipment
  - target: $.paths['/v1/carriers/{dot_number}/timeline'].get
    update:
      tags: [Signals]
      x-pagination: {style: offset-limit, params: [offset, limit], default_limit: 50}
      x-results-key: events
      x-change-feed: >-
        Change-data-capture over the carrier record (event_type, field_name, old_value, new_value,
        source). The documented polling substitute for the webhooks AlphaLoops sells but does not
        specify.
  - target: $.paths['/v1/carriers/{dot_number}/news'].get
    update:
      tags: [Signals]
      x-results-key: articles

  # --- 8. Contacts — the metered, async surface --------------------------------------------------
  - target: $.paths['/v1/contacts/search'].get
    update:
      tags: [Contacts]
      x-pagination: {style: page-limit, params: [page, limit]}
      x-results-key: contacts
      x-enum-levels: [c_suite, vp, director, manager]
      x-async: >-
        Can return 202 Accepted — contacts are fetched asynchronously and the client must re-issue
        the request after a delay. No Location header, job id, or recommended poll interval is
        published, so the client must choose its own backoff. This is a SUCCESS path, not an error.
      x-pii: true
  - target: $.paths['/v1/contacts/{contact_id}/enrich'].get
    update:
      tags: [Contacts]
      x-metered:
        unit: enrichment credit
        cost: 1 per new enrichment
        cached_cost: 0
        balance_header: X-Enrichment-Credits-Remaining
        balance_body_field: credits
        exhausted_status: 402
        retryable: false
      x-pii:
        returns: [work_email, personal_emails, phone_numbers, mobile_phone, location_name, experience, education]
        note: >-
          The only operation returning personal data about a named individual. Provider claims
          GDPR/CCPA compliance for the contact dataset; lawful basis for downstream use rests with
          the caller.

  # --- 9. VINs ------------------------------------------------------------------------------------
  - target: $.paths['/v1/vins'].get
    update:
      tags: [VINs]
      x-results-key: results
  - target: $.paths['/v1/vins'].post
    update:
      tags: [VINs]
      x-results-key: results
      x-batch: true
  - target: $.paths['/v1/inspections/vin/{vin}'].get
    update:
      tags: [VINs, Safety]
      x-results-key: [dot_numbers, locations]
      x-reverse-lookup: >-
        Resolves a VIN back to the carriers it has been associated with — the mechanism for
        spotting equipment moving between a revoked carrier and its successor.