Shovels API — Permits

naftiko: 1.0.0-alpha2
info:
  label: Shovels API — Permits
  description: 'Shovels API — Permits. 2 operations. Lead operation: Search Permits. Self-contained Naftiko capability covering
    one Shovels business surface.'
  tags:
  - Shovels
  - Permits
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    SHOVELS_API_KEY: SHOVELS_API_KEY
capability:
  consumes:
  - type: http
    namespace: shovels-permits
    baseUri: https://api.shovels.ai/v2
    description: Shovels API — Permits business capability. Self-contained, no shared references.
    resources:
    - name: permits-search
      path: /permits/search
      operations:
      - name: searchpermits
        method: GET
        description: Search Permits
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: geo_id
          in: query
          type: string
          description: Location filter (address, city, zip code, county, jurisdiction, or state geo_id)
          required: true
        - name: permit_from
          in: query
          type: string
          description: Return permits issued on or after this date (YYYY-MM-DD)
          required: true
        - name: permit_to
          in: query
          type: string
          description: Return permits issued on or before this date (YYYY-MM-DD)
          required: true
        - name: status
          in: query
          type: string
          description: Filter by permit status (issued, approved, completed, expired, cancelled)
        - name: tags
          in: query
          type: string
          description: Filter by permit tags (comma-separated list)
        - name: min_job_value
          in: query
          type: number
          description: Minimum job value in dollars
        - name: max_job_value
          in: query
          type: number
          description: Maximum job value in dollars
        - name: property_type
          in: query
          type: string
          description: Filter by property type (residential, commercial, industrial)
        - name: cursor
          in: query
          type: string
          description: Pagination cursor for next page
        - 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 (capped at 10,000)
    - name: permits-id
      path: /permits/{id}
      operations:
      - name: getpermitbyid
        method: GET
        description: Get Permit By ID
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: string
          description: Unique permit ID
          required: true
    authentication:
      type: apikey
      key: X-API-Key
      value: '{{env.SHOVELS_API_KEY}}'
      placement: header
  exposes:
  - type: rest
    namespace: shovels-permits-rest
    port: 8080
    description: REST adapter for Shovels API — Permits. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/permits/search
      name: permits-search
      description: REST surface for permits-search.
      operations:
      - method: GET
        name: searchpermits
        description: Search Permits
        call: shovels-permits.searchpermits
        with:
          geo_id: rest.geo_id
          permit_from: rest.permit_from
          permit_to: rest.permit_to
          status: rest.status
          tags: rest.tags
          min_job_value: rest.min_job_value
          max_job_value: rest.max_job_value
          property_type: rest.property_type
          cursor: rest.cursor
          size: rest.size
          include_count: rest.include_count
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/permits/{id}
      name: permits-id
      description: REST surface for permits-id.
      operations:
      - method: GET
        name: getpermitbyid
        description: Get Permit By ID
        call: shovels-permits.getpermitbyid
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: shovels-permits-mcp
    port: 9090
    transport: http
    description: MCP adapter for Shovels API — Permits. One tool per consumed operation, routed inline through this capability's
      consumes block.
    tools:
    - name: search-permits
      description: Search Permits
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shovels-permits.searchpermits
      with:
        geo_id: tools.geo_id
        permit_from: tools.permit_from
        permit_to: tools.permit_to
        status: tools.status
        tags: tools.tags
        min_job_value: tools.min_job_value
        max_job_value: tools.max_job_value
        property_type: tools.property_type
        cursor: tools.cursor
        size: tools.size
        include_count: tools.include_count
      outputParameters:
      - type: object
        mapping: $.
    - name: get-permit-id
      description: Get Permit By ID
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: shovels-permits.getpermitbyid
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.