naftiko: 1.0.0-alpha2
info:
  label: Webex Cloud Calling — Numbers
  description: 'Webex Cloud Calling — Numbers. 11 operations. Lead operation: Validate phone numbers. Self-contained Naftiko
    capability covering one Webex business surface.'
  tags:
  - Webex
  - Numbers
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    WEBEX_API_KEY: WEBEX_API_KEY
capability:
  consumes:
  - type: http
    namespace: cloud-calling-numbers
    baseUri: ''
    description: Webex Cloud Calling — Numbers business capability. Self-contained, no shared references.
    resources:
    - name: telephony-config-actions-validateNumbers-invoke
      path: /telephony/config/actions/validateNumbers/invoke
      operations:
      - name: validatephonenumbers
        method: POST
        description: Validate phone numbers
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: query
          type: string
          description: Organization of the Route Group.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: telephony-config-jobs-numbers-manageNumbers
      path: /telephony/config/jobs/numbers/manageNumbers
      operations:
      - name: listmanagenumbersjobs
        method: GET
        description: List Manage Numbers Jobs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: query
          type: string
          description: Retrieve list of Manage Number jobs for this organization.
        - name: start
          in: query
          type: number
          description: Start at the zero-based offset in the list of jobs. Default is 0.
        - name: max
          in: query
          type: number
          description: Limit the number of jobs returned to this maximum count. Default is 2000.
      - name: initiatenumberjobs
        method: POST
        description: Initiate Number Jobs
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: telephony-config-jobs-numbers-manageNumbers-jobId
      path: /telephony/config/jobs/numbers/manageNumbers/{jobId}
      operations:
      - name: getmanagenumbersjobstatus
        method: GET
        description: Get Manage Numbers Job Status
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: jobId
          in: path
          type: string
          description: Retrieve job details for this `jobId`.
          required: true
    - name: telephony-config-jobs-numbers-manageNumbers-jobId-actions-pause-invoke
      path: /telephony/config/jobs/numbers/manageNumbers/{jobId}/actions/pause/invoke
      operations:
      - name: pausethemanagenumbersjob
        method: POST
        description: Pause the Manage Numbers Job
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: jobId
          in: path
          type: string
          description: Pause the Manage Numbers job for this `jobId`.
          required: true
        - name: orgId
          in: query
          type: string
          description: Pause the Manage Numbers job for this organization.
    - name: telephony-config-jobs-numbers-manageNumbers-jobId-actions-resume-invoke
      path: /telephony/config/jobs/numbers/manageNumbers/{jobId}/actions/resume/invoke
      operations:
      - name: resumethemanagenumbersjob
        method: POST
        description: Resume the Manage Numbers Job
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: jobId
          in: path
          type: string
          description: Resume the Manage Numbers job for this `jobId`.
          required: true
        - name: orgId
          in: query
          type: string
          description: Resume the Manage Numbers job for this organization.
    - name: telephony-config-jobs-numbers-manageNumbers-jobId-errors
      path: /telephony/config/jobs/numbers/manageNumbers/{jobId}/errors
      operations:
      - name: listmanagenumbersjoberrors
        method: GET
        description: List Manage Numbers Job errors
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: jobId
          in: path
          type: string
          description: Retrieve the error details for this `jobId`.
          required: true
        - name: orgId
          in: query
          type: string
          description: Retrieve list of jobs for this organization.
        - name: start
          in: query
          type: number
          description: Specifies the error offset from the first result that you want to fetch.
        - name: max
          in: query
          type: number
          description: Specifies the maximum number of records that you want to fetch.
    - name: telephony-config-locations-locationId-numbers
      path: /telephony/config/locations/{locationId}/numbers
      operations:
      - name: addphonenumberstoalocation
        method: POST
        description: Add Phone Numbers to a location
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: locationId
          in: path
          type: string
          description: LocationId to which numbers should be added.
          required: true
        - name: orgId
          in: query
          type: string
          description: Organization of the Route Group.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: managenumberstateinalocation
        method: PUT
        description: Manage Number State in a location
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: locationId
          in: path
          type: string
          description: '`LocationId` to which numbers should be added.'
          required: true
        - name: orgId
          in: query
          type: string
          description: Organization of the Route Group.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
      - name: removephonenumbersfromalocation
        method: DELETE
        description: Remove phone numbers from a location
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: locationId
          in: path
          type: string
          description: '`LocationId` to which numbers should be added.'
          required: true
        - name: orgId
          in: query
          type: string
          description: Organization of the Route Group.
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: telephony-config-numbers
      path: /telephony/config/numbers
      operations:
      - name: getphonenumbersforanorganizationwithgivencriteria
        method: GET
        description: Get Phone Numbers for an Organization with Given Criteria
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: orgId
          in: query
          type: string
          description: List numbers for this organization.
        - name: locationId
          in: query
          type: string
          description: Return the list of phone numbers for this location within the given organization. The maximum length
            is 36.
        - name: max
          in: query
          type: number
          description: Limit the number of phone numbers returned to this maximum count. The default is 2000.
        - name: start
          in: query
          type: number
          description: Start at the zero-based offset in the list of matching phone numbers. The default is 0.
        - name: phoneNumber
          in: query
          type: string
          description: Search for this `phoneNumber`.
        - name: available
          in: query
          type: boolean
          description: Search among the available phone numbers. This parameter cannot be used along with `ownerType` parameter
            when set to `true`.
        - name: order
          in: query
          type: string
          description: Sort the list of phone numbers based on the following:`lastName`,`dn`,`extension`. Sorted by number
            and extension in ascending order.
        - name: ownerName
          in: query
          type: string
          description: Return the list of phone numbers that are owned by the given `ownerName`. Maximum length is 255.
        - name: ownerId
          in: query
          type: string
          description: Returns only the matched number/extension entries assigned to the feature with the specified UUID or
            `broadsoftId`.
        - name: ownerType
          in: query
          type: string
          description: 'Returns the list of phone numbers of the given `ownerType`. Possible input values:'
        - name: extension
          in: query
          type: string
          description: Returns the list of phone numbers with the given extension.
        - name: numberType
          in: query
          type: string
          description: Returns the filtered list of phone numbers that contain a given type of number. `available` or `state`
            query parameters cannot be used when `numberType=EXTENSIO
        - name: phoneNumberType
          in: query
          type: string
          description: 'Returns the filtered list of phone numbers of the given `phoneNumberType`. Response excludes any extensions
            without numbers. Possible input values:'
        - name: state
          in: query
          type: string
          description: 'Returns the list of phone numbers with the matching state. Response excludes any extensions without
            numbers. Possible input values:'
        - name: details
          in: query
          type: boolean
          description: Returns the overall count of the phone numbers along with other details for a given organization.
        - name: tollFreeNumbers
          in: query
          type: boolean
          description: Returns the list of toll-free phone numbers.
        - name: restrictedNonGeoNumbers
          in: query
          type: boolean
          description: Returns the list of restricted non-geographical numbers.
        - name: includedTelephonyTypes
          in: query
          type: string
          description: Returns the list of phone numbers that are of given `includedTelephonyTypes`. By default, if this query
            parameter is not provided, it will list both PSTN and Mo
        - name: serviceNumber
          in: query
          type: boolean
          description: Returns the list of service phone numbers.
    authentication:
      type: bearer
      token: '{{env.WEBEX_API_KEY}}'
  exposes:
  - type: rest
    namespace: cloud-calling-numbers-rest
    port: 8080
    description: REST adapter for Webex Cloud Calling — Numbers. One Spectral-compliant resource per consumed operation, prefixed
      with /v1.
    resources:
    - path: /v1/telephony/config/actions/validatenumbers/invoke
      name: telephony-config-actions-validatenumbers-invoke
      description: REST surface for telephony-config-actions-validateNumbers-invoke.
      operations:
      - method: POST
        name: validatephonenumbers
        description: Validate phone numbers
        call: cloud-calling-numbers.validatephonenumbers
        with:
          orgId: rest.orgId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/telephony/config/jobs/numbers/managenumbers
      name: telephony-config-jobs-numbers-managenumbers
      description: REST surface for telephony-config-jobs-numbers-manageNumbers.
      operations:
      - method: GET
        name: listmanagenumbersjobs
        description: List Manage Numbers Jobs
        call: cloud-calling-numbers.listmanagenumbersjobs
        with:
          orgId: rest.orgId
          start: rest.start
          max: rest.max
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: initiatenumberjobs
        description: Initiate Number Jobs
        call: cloud-calling-numbers.initiatenumberjobs
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/telephony/config/jobs/numbers/managenumbers/{jobid}
      name: telephony-config-jobs-numbers-managenumbers-jobid
      description: REST surface for telephony-config-jobs-numbers-manageNumbers-jobId.
      operations:
      - method: GET
        name: getmanagenumbersjobstatus
        description: Get Manage Numbers Job Status
        call: cloud-calling-numbers.getmanagenumbersjobstatus
        with:
          jobId: rest.jobId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/telephony/config/jobs/numbers/managenumbers/{jobid}/actions/pause/invoke
      name: telephony-config-jobs-numbers-managenumbers-jobid-actions-pause-invoke
      description: REST surface for telephony-config-jobs-numbers-manageNumbers-jobId-actions-pause-invoke.
      operations:
      - method: POST
        name: pausethemanagenumbersjob
        description: Pause the Manage Numbers Job
        call: cloud-calling-numbers.pausethemanagenumbersjob
        with:
          jobId: rest.jobId
          orgId: rest.orgId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/telephony/config/jobs/numbers/managenumbers/{jobid}/actions/resume/invoke
      name: telephony-config-jobs-numbers-managenumbers-jobid-actions-resume-invoke
      description: REST surface for telephony-config-jobs-numbers-manageNumbers-jobId-actions-resume-invoke.
      operations:
      - method: POST
        name: resumethemanagenumbersjob
        description: Resume the Manage Numbers Job
        call: cloud-calling-numbers.resumethemanagenumbersjob
        with:
          jobId: rest.jobId
          orgId: rest.orgId
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/telephony/config/jobs/numbers/managenumbers/{jobid}/errors
      name: telephony-config-jobs-numbers-managenumbers-jobid-errors
      description: REST surface for telephony-config-jobs-numbers-manageNumbers-jobId-errors.
      operations:
      - method: GET
        name: listmanagenumbersjoberrors
        description: List Manage Numbers Job errors
        call: cloud-calling-numbers.listmanagenumbersjoberrors
        with:
          jobId: rest.jobId
          orgId: rest.orgId
          start: rest.start
          max: rest.max
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/telephony/config/locations/{locationid}/numbers
      name: telephony-config-locations-locationid-numbers
      description: REST surface for telephony-config-locations-locationId-numbers.
      operations:
      - method: POST
        name: addphonenumberstoalocation
        description: Add Phone Numbers to a location
        call: cloud-calling-numbers.addphonenumberstoalocation
        with:
          locationId: rest.locationId
          orgId: rest.orgId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: PUT
        name: managenumberstateinalocation
        description: Manage Number State in a location
        call: cloud-calling-numbers.managenumberstateinalocation
        with:
          locationId: rest.locationId
          orgId: rest.orgId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
      - method: DELETE
        name: removephonenumbersfromalocation
        description: Remove phone numbers from a location
        call: cloud-calling-numbers.removephonenumbersfromalocation
        with:
          locationId: rest.locationId
          orgId: rest.orgId
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/telephony/config/numbers
      name: telephony-config-numbers
      description: REST surface for telephony-config-numbers.
      operations:
      - method: GET
        name: getphonenumbersforanorganizationwithgivencriteria
        description: Get Phone Numbers for an Organization with Given Criteria
        call: cloud-calling-numbers.getphonenumbersforanorganizationwithgivencriteria
        with:
          orgId: rest.orgId
          locationId: rest.locationId
          max: rest.max
          start: rest.start
          phoneNumber: rest.phoneNumber
          available: rest.available
          order: rest.order
          ownerName: rest.ownerName
          ownerId: rest.ownerId
          ownerType: rest.ownerType
          extension: rest.extension
          numberType: rest.numberType
          phoneNumberType: rest.phoneNumberType
          state: rest.state
          details: rest.details
          tollFreeNumbers: rest.tollFreeNumbers
          restrictedNonGeoNumbers: rest.restrictedNonGeoNumbers
          includedTelephonyTypes: rest.includedTelephonyTypes
          serviceNumber: rest.serviceNumber
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: cloud-calling-numbers-mcp
    port: 9090
    transport: http
    description: MCP adapter for Webex Cloud Calling — Numbers. One tool per consumed operation, routed inline through this
      capability's consumes block.
    tools:
    - name: validate-phone-numbers
      description: Validate phone numbers
      hints:
        readOnly: true
        destructive: false
        idempotent: false
      call: cloud-calling-numbers.validatephonenumbers
      with:
        orgId: tools.orgId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: list-manage-numbers-jobs
      description: List Manage Numbers Jobs
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: cloud-calling-numbers.listmanagenumbersjobs
      with:
        orgId: tools.orgId
        start: tools.start
        max: tools.max
      outputParameters:
      - type: object
        mapping: $.
    - name: initiate-number-jobs
      description: Initiate Number Jobs
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: cloud-calling-numbers.initiatenumberjobs
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-manage-numbers-job-status
      description: Get Manage Numbers Job Status
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: cloud-calling-numbers.getmanagenumbersjobstatus
      with:
        jobId: tools.jobId
      outputParameters:
      - type: object
        mapping: $.
    - name: pause-manage-numbers-job
      description: Pause the Manage Numbers Job
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: cloud-calling-numbers.pausethemanagenumbersjob
      with:
        jobId: tools.jobId
        orgId: tools.orgId
      outputParameters:
      - type: object
        mapping: $.
    - name: resume-manage-numbers-job
      description: Resume the Manage Numbers Job
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: cloud-calling-numbers.resumethemanagenumbersjob
      with:
        jobId: tools.jobId
        orgId: tools.orgId
      outputParameters:
      - type: object
        mapping: $.
    - name: list-manage-numbers-job-errors
      description: List Manage Numbers Job errors
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: cloud-calling-numbers.listmanagenumbersjoberrors
      with:
        jobId: tools.jobId
        orgId: tools.orgId
        start: tools.start
        max: tools.max
      outputParameters:
      - type: object
        mapping: $.
    - name: add-phone-numbers-location
      description: Add Phone Numbers to a location
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: cloud-calling-numbers.addphonenumberstoalocation
      with:
        locationId: tools.locationId
        orgId: tools.orgId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: manage-number-state-location
      description: Manage Number State in a location
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: cloud-calling-numbers.managenumberstateinalocation
      with:
        locationId: tools.locationId
        orgId: tools.orgId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: remove-phone-numbers-location
      description: Remove phone numbers from a location
      hints:
        readOnly: false
        destructive: true
        idempotent: true
      call: cloud-calling-numbers.removephonenumbersfromalocation
      with:
        locationId: tools.locationId
        orgId: tools.orgId
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: get-phone-numbers-organization-given
      description: Get Phone Numbers for an Organization with Given Criteria
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: cloud-calling-numbers.getphonenumbersforanorganizationwithgivencriteria
      with:
        orgId: tools.orgId
        locationId: tools.locationId
        max: tools.max
        start: tools.start
        phoneNumber: tools.phoneNumber
        available: tools.available
        order: tools.order
        ownerName: tools.ownerName
        ownerId: tools.ownerId
        ownerType: tools.ownerType
        extension: tools.extension
        numberType: tools.numberType
        phoneNumberType: tools.phoneNumberType
        state: tools.state
        details: tools.details
        tollFreeNumbers: tools.tollFreeNumbers
        restrictedNonGeoNumbers: tools.restrictedNonGeoNumbers
        includedTelephonyTypes: tools.includedTelephonyTypes
        serviceNumber: tools.serviceNumber
      outputParameters:
      - type: object
        mapping: $.