Shovels API — Contractors

naftiko: 1.0.0-alpha2
info:
  label: Shovels API — Contractors
  description: 'Shovels API — Contractors. 5 operations. Lead operation: Search Contractors. Self-contained Naftiko capability
    covering one Shovels business surface.'
  tags:
  - Shovels
  - Contractors
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SHOVELS_API_KEY: SHOVELS_API_KEY
capability:
  consumes:
  - type: http
    namespace: shovels-contractors
    baseUri: https://api.shovels.ai/v2
    description: Shovels API — Contractors business capability. Self-contained, no shared references.
    resources:
    - name: contractors-search
      path: /contractors/search
      operations:
      - name: searchcontractors
        method: GET
        description: Search Contractors
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: geo_id
          in: query
          type: string
          description: Location filter for the search area
          required: true
        - name: permit_from
          in: query
          type: string
          description: Return permits that started on or after this date (YYYY-MM-DD)
          required: true
        - name: permit_to
          in: query
          type: string
          description: Return permits that started on or before this date (YYYY-MM-DD)
          required: true
        - name: name
          in: query
          type: string
          description: Filter by contractor name
        - name: tags
          in: query
          type: string
          description: Filter by permit tags (contractor specialties)
        - name: classification
          in: query
          type: string
          description: Filter by contractor classification
        - name: min_inspection_pass_rate
          in: query
          type: number
          description: Minimum inspection pass rate (0-1)
        - name: cursor
          in: query
          type: string
          description: Pagination cursor
        - name: size
          in: query
          type: integer
          description: Number of results per page (1-100, default 50)
        - name: include_count
          in: query
          type: boolean
          description: Include total count in response
    - name: contractors-id
      path: /contractors/{id}
      operations:
      - name: getcontractorbyid
        method: GET
        description: Get Contractor By ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Unique contractor ID
          required: true
    - name: contractors-id-employees
      path: /contractors/{id}/employees
      operations:
      - name: getcontractoremployees
        method: GET
        description: Get Contractor Employees
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Unique contractor ID
          required: true
        - name: cursor
          in: query
          type: string
          description: Pagination cursor
        - name: size
          in: query
          type: integer
          description: Number of results per page
    - name: contractors-id-metrics
      path: /contractors/{id}/metrics
      operations:
      - name: getcontractormetrics
        method: GET
        description: Get Contractor Metrics
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Unique contractor ID
          required: true
    - name: contractors-id-permits
      path: /contractors/{id}/permits
      operations:
      - name: getcontractorpermits
        method: GET
        description: Get Contractor Permits
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Unique contractor ID
          required: true
        - name: cursor
          in: query
          type: string
          description: Pagination cursor
        - name: size
          in: query
          type: integer
          description: Number of results per page
    authentication:
      type: apikey
      key: X-API-Key
      value: '{{env.SHOVELS_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: shovels-contractors-rest
    port: 8080
    description: REST adapter for Shovels API — Contractors. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/contractors/search
      name: contractors-search
      description: REST surface for contractors-search.
      operations:
      - method: GET
        name: searchcontractors
        description: Search Contractors
        call: shovels-contractors.searchcontractors
        with:
          geo_id: rest.geo_id
          permit_from: rest.permit_from
          permit_to: rest.permit_to
          name: rest.name
          tags: rest.tags
          classification: rest.classification
          min_inspection_pass_rate: rest.min_inspection_pass_rate
          cursor: rest.cursor
          size: rest.size
          include_count: rest.include_count
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contractors/{id}
      name: contractors-id
      description: REST surface for contractors-id.
      operations:
      - method: GET
        name: getcontractorbyid
        description: Get Contractor By ID
        call: shovels-contractors.getcontractorbyid
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contractors/{id}/employees
      name: contractors-id-employees
      description: REST surface for contractors-id-employees.
      operations:
      - method: GET
        name: getcontractoremployees
        description: Get Contractor Employees
        call: shovels-contractors.getcontractoremployees
        with:
          id: rest.id
          cursor: rest.cursor
          size: rest.size
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contractors/{id}/metrics
      name: contractors-id-metrics
      description: REST surface for contractors-id-metrics.
      operations:
      - method: GET
        name: getcontractormetrics
        description: Get Contractor Metrics
        call: shovels-contractors.getcontractormetrics
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/contractors/{id}/permits
      name: contractors-id-permits
      description: REST surface for contractors-id-permits.
      operations:
      - method: GET
        name: getcontractorpermits
        description: Get Contractor Permits
        call: shovels-contractors.getcontractorpermits
        with:
          id: rest.id
          cursor: rest.cursor
          size: rest.size
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: shovels-contractors-mcp
    port: 9090
    transport: http
    description: MCP adapter for Shovels API — Contractors. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: search-contractors
      description: Search Contractors
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shovels-contractors.searchcontractors
      with:
        geo_id: tools.geo_id
        permit_from: tools.permit_from
        permit_to: tools.permit_to
        name: tools.name
        tags: tools.tags
        classification: tools.classification
        min_inspection_pass_rate: tools.min_inspection_pass_rate
        cursor: tools.cursor
        size: tools.size
        include_count: tools.include_count
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contractor-id
      description: Get Contractor By ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shovels-contractors.getcontractorbyid
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contractor-employees
      description: Get Contractor Employees
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shovels-contractors.getcontractoremployees
      with:
        id: tools.id
        cursor: tools.cursor
        size: tools.size
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contractor-metrics
      description: Get Contractor Metrics
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shovels-contractors.getcontractormetrics
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: get-contractor-permits
      description: Get Contractor Permits
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shovels-contractors.getcontractorpermits
      with:
        id: tools.id
        cursor: tools.cursor
        size: tools.size
      outputParameters:
      - type: object
        mapping: $.