Numbers API — Batch

naftiko: "1.0.0-alpha2"

info:
  label: "Numbers API — Batch"
  description: >-
    Numbers API — Batch. 1 operation. Lead operation: return facts for
    multiple numbers in one request using comma-separated values and
    `min..max` ranges (up to 100 numbers), returned as a JSON map keyed by
    number. Self-contained Naftiko capability covering one Numbers API
    business surface.
  tags:
    - Numbers API
    - Batch
    - Numbers
  created: "2026-05-30"
  modified: "2026-05-30"

binds: []

capability:

  consumes:
    - type: http
      namespace: "numbers-batch"
      baseUri: "http://numbersapi.com"
      description: "Numbers API — Batch business capability. Self-contained, no shared references."
      resources:
        - name: "number-range-batch"
          path: "/{numberRange}/batch"
          operations:
            - name: "getBatchFacts"
              method: GET
              description: "Return facts for multiple numbers in a single response (up to 100)."
              inputParameters:
                - name: "numberRange"
                  in: path
                  type: string
                  required: true
                  description: "Comma-separated list of integers and inclusive `min..max` ranges (e.g. `1..3,10`)."
                - name: "type"
                  in: query
                  type: string
                  required: false
                  description: "Fact type to apply to all numbers in the batch (trivia, math, year)."
                - name: "json"
                  in: query
                  type: boolean
                  required: false
                  description: "Return each value as a JSON Fact object instead of plain text."
                - name: "fragment"
                  in: query
                  type: boolean
                  required: false
                  description: "Return facts as sentence fragments."
                - name: "notfound"
                  in: query
                  type: string
                  required: false
                  description: "Not-found behavior: default, floor, ceil."
                - name: "default"
                  in: query
                  type: string
                  required: false
                  description: "Custom default message."
              outputRawFormat: json
              outputParameters:
                - name: result
                  type: object
                  value: "$."

  exposes:
    - type: rest
      namespace: "numbers-batch-rest"
      port: 8080
      description: "REST adapter for Numbers API — Batch. One Spectral-compliant resource per consumed operation, prefixed with /v1."
      resources:
        - path: "/v1/numbers/batches/{number-range}"
          name: "number-range-batch"
          description: "REST surface for batch fact lookups."
          operations:
            - method: GET
              name: "getBatchFacts"
              description: "Return facts for multiple numbers in a single response."
              call: "numbers-batch.getBatchFacts"
              with:
                numberRange: "rest.numberRange"
                type: "rest.type"
                json: "rest.json"
                fragment: "rest.fragment"
                notfound: "rest.notfound"
                default: "rest.default"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      namespace: "numbers-batch-mcp"
      port: 9090
      transport: http
      description: "MCP adapter for Numbers API — Batch. One tool per consumed operation, routed inline through this capability's consumes block."
      tools:
        - name: "get-batch-facts"
          description: "Return facts for multiple numbers in a single response."
          hints:
            readOnly: true
            destructive: false
            idempotent: true
          call: "numbers-batch.getBatchFacts"
          with:
            numberRange: "tools.numberRange"
            type: "tools.type"
            json: "tools.json"
            fragment: "tools.fragment"
            notfound: "tools.notfound"
            default: "tools.default"
          outputParameters:
            - type: object
              mapping: "$."