Postman Spec Hub Publish

naftiko: "1.0.0-alpha2"

info:
  title: Postman Spec Hub Publish
  description: >-
    Publishes the OpenAPI / AsyncAPI / GraphQL spec generated by a
    Naftiko capability's expose surface into Postman's Spec Hub so the
    same spec is governable, versionable, and consumable by Postman's
    35M+ developer community. Closes the loop between "Naftiko shipped a
    REST or event-driven expose" and "developers can find it in Postman."
  tags:
    - Naftiko
    - Postman
    - Partnership
    - Spec-Hub
    - OpenAPI
    - AsyncAPI
    - Publication
  created: '2026-05-15'
  modified: '2026-05-15'

binds:
  - namespace: postman-env
    description: Postman API key.
    keys:
      POSTMAN_API_KEY: POSTMAN_API_KEY

capability:
  consumes:
    - namespace: postman
      type: http
      baseUri: https://api.getpostman.com
      authentication:
        type: bearer
        token: '{{POSTMAN_API_KEY}}'
      resources:
        - name: list-apis
          path: '/apis'
          operations:
            - name: list-apis
              method: GET
              inputParameters:
                - { name: workspaceId, in: query, type: string, required: false }
            - name: create-api
              method: POST
        - name: api
          path: '/apis/{{api_id}}'
          operations:
            - name: get-api
              method: GET
              inputParameters:
                - { name: api_id, in: path, required: true }
            - name: update-api
              method: PUT
              inputParameters:
                - { name: api_id, in: path, required: true }
            - name: delete-api
              method: DELETE
              inputParameters:
                - { name: api_id, in: path, required: true }
        - name: api-versions
          path: '/apis/{{api_id}}/versions'
          operations:
            - name: list-api-versions
              method: GET
              inputParameters:
                - { name: api_id, in: path, required: true }
            - name: create-api-version
              method: POST
              inputParameters:
                - { name: api_id, in: path, required: true }

  exposes:
    - type: rest
      address: 0.0.0.0
      port: 8080
      namespace: postman-spec-hub-publish-rest
      description: REST surface for publishing Naftiko-generated specs into Postman Spec Hub.
      resources:
        - name: apis
          path: '/apis'
          operations:
            - name: list-apis
              method: GET
              inputParameters:
                - { name: workspaceId, in: query, type: string, required: false }
              call: postman.list-apis
            - name: create-api
              method: POST
              call: postman.create-api
        - name: api
          path: '/apis/{api_id}'
          operations:
            - name: get-api
              method: GET
              inputParameters:
                - { name: api_id, in: path, type: string, required: true }
              call: postman.get-api
            - name: update-api
              method: PUT
              inputParameters:
                - { name: api_id, in: path, type: string, required: true }
              call: postman.update-api
            - name: delete-api
              method: DELETE
              inputParameters:
                - { name: api_id, in: path, type: string, required: true }
              call: postman.delete-api
        - name: api-versions
          path: '/apis/{api_id}/versions'
          operations:
            - name: list-api-versions
              method: GET
              inputParameters:
                - { name: api_id, in: path, type: string, required: true }
              call: postman.list-api-versions
            - name: create-api-version
              method: POST
              inputParameters:
                - { name: api_id, in: path, type: string, required: true }
              call: postman.create-api-version

    - type: mcp
      address: 0.0.0.0
      port: 3010
      namespace: postman-spec-hub-publish-mcp
      description: MCP server for publishing Naftiko-generated specs into Postman Spec Hub.
      tools:
        - name: list-apis
          description: List Postman Spec Hub API entries (optionally per workspace).
          hints: { readOnly: true }
          inputParameters:
            - { name: workspaceId, type: string, required: false, description: Filter to a workspace UUID. }
          call: postman.list-apis
        - name: create-api
          description: Publish a new API definition into Postman Spec Hub (typically a Naftiko-built REST or event-driven expose).
          hints: { destructiveHint: false }
          call: postman.create-api
        - name: get-api
          description: Get a single Postman Spec Hub API entry.
          hints: { readOnly: true }
          inputParameters:
            - { name: api_id, type: string, required: true, description: Postman API UID. }
          call: postman.get-api
        - name: update-api
          description: Update a Postman Spec Hub API entry.
          hints: { destructiveHint: true }
          inputParameters:
            - { name: api_id, type: string, required: true, description: Postman API UID. }
          call: postman.update-api
        - name: delete-api
          description: Delete a Postman Spec Hub API entry.
          hints: { destructiveHint: true }
          inputParameters:
            - { name: api_id, type: string, required: true, description: Postman API UID. }
          call: postman.delete-api
        - name: list-api-versions
          description: List versions of a Postman Spec Hub API entry.
          hints: { readOnly: true }
          inputParameters:
            - { name: api_id, type: string, required: true, description: Postman API UID. }
          call: postman.list-api-versions
        - name: create-api-version
          description: Publish a new version of a Postman Spec Hub API entry.
          hints: { destructiveHint: false }
          inputParameters:
            - { name: api_id, type: string, required: true, description: Postman API UID. }
          call: postman.create-api-version