Perforce Helix Swarm API — Reviews

naftiko: 1.0.0-alpha2
info:
  label: Perforce Helix Swarm API — Reviews
  description: 'Perforce Helix Swarm API — Reviews. 12 operations. Lead operation: Perforce Get Action Dashboard Reviews.
    Self-contained Naftiko capability covering one Perforce business surface.'
  tags:
  - Perforce
  - Reviews
  created: '2026-05-19'
  modified: '2026-05-19'
binds:
- namespace: env
  keys:
    PERFORCE_API_KEY: PERFORCE_API_KEY
capability:
  consumes:
  - type: http
    namespace: helix-swarm-reviews
    baseUri: ''
    description: Perforce Helix Swarm API — Reviews business capability. Self-contained, no shared references.
    resources:
    - name: dashboards-action
      path: /dashboards/action
      operations:
      - name: getactiondashboard
        method: GET
        description: Perforce Get Action Dashboard Reviews
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: reviews
      path: /reviews/
      operations:
      - name: listreviews
        method: GET
        description: Perforce List Reviews
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: after
          in: query
          type: integer
          description: A review ID to seek past for pagination.
        - name: max
          in: query
          type: integer
          description: Maximum number of reviews to return. Defaults to 1000.
        - name: fields
          in: query
          type: string
          description: Comma-separated list of fields to include in the response.
        - name: author[]
          in: query
          type: array
          description: Filter reviews by one or more authors.
        - name: change[]
          in: query
          type: array
          description: Filter reviews by one or more changelist IDs.
        - name: hasReviewers
          in: query
          type: boolean
          description: Filter by whether reviewers are assigned.
        - name: ids[]
          in: query
          type: array
          description: Fetch specific reviews by their IDs.
        - name: keywords
          in: query
          type: string
          description: Keywords to search for in reviews.
        - name: participants[]
          in: query
          type: array
          description: Filter reviews by one or more participants.
        - name: project[]
          in: query
          type: array
          description: Filter reviews by one or more projects.
        - name: state[]
          in: query
          type: array
          description: Filter reviews by state. Valid values include needsReview, needsRevision, approved, archived, and rejected.
        - name: passesTests
          in: query
          type: boolean
          description: Filter reviews by whether tests have passed.
        - name: notUpdatedSince
          in: query
          type: string
          description: Filter reviews not updated since the given date (YYYY-mm-dd).
        - name: hasVoted
          in: query
          type: string
          description: Filter reviews by vote direction.
        - name: myComments
          in: query
          type: boolean
          description: Filter reviews that the authenticated user has commented on.
      - name: createreview
        method: POST
        description: Perforce Create a Review
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: reviews-archive
      path: /reviews/archive/
      operations:
      - name: archiveinactivereviews
        method: POST
        description: Perforce Archive Inactive Reviews
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: reviews-id
      path: /reviews/{id}
      operations:
      - name: getreview
        method: GET
        description: Perforce Get Review Details
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The review ID.
          required: true
        - name: fields
          in: query
          type: string
          description: Comma-separated list of fields to include in the response.
      - name: updatereview
        method: PATCH
        description: Perforce Update Review Description
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The review ID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: reviews-id-changes
      path: /reviews/{id}/changes/
      operations:
      - name: addchangetoreview
        method: POST
        description: Perforce Add Change to Review
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The review ID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: reviews-id-cleanup
      path: /reviews/{id}/cleanup
      operations:
      - name: cleanupreview
        method: POST
        description: Perforce Clean up a Review
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The review ID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: false
    - name: reviews-id-obliterate
      path: /reviews/{id}/obliterate
      operations:
      - name: obliteratereview
        method: POST
        description: Perforce Obliterate a Review
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The review ID.
          required: true
    - name: reviews-id-state
      path: /reviews/{id}/state/
      operations:
      - name: transitionreviewstate
        method: PATCH
        description: Perforce Transition Review State
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The review ID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    - name: reviews-id-transitions
      path: /reviews/{id}/transitions
      operations:
      - name: getreviewtransitions
        method: GET
        description: Perforce Get Review Transitions
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The review ID.
          required: true
        - name: upVoters
          in: query
          type: string
          description: Comma-separated list of users assumed to have voted up.
    - name: reviews-id-vote
      path: /reviews/{id}/vote/
      operations:
      - name: setreviewvote
        method: POST
        description: Perforce Set Vote on Review
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
        inputParameters:
        - name: id
          in: path
          type: integer
          description: The review ID.
          required: true
        - name: body
          in: body
          type: object
          description: Request body (JSON).
          required: true
    authentication:
      type: basic
      username: '{{env.PERFORCE_USER}}'
      password: '{{env.PERFORCE_PASS}}'
  exposes:
  - type: rest
    namespace: helix-swarm-reviews-rest
    port: 8080
    description: REST adapter for Perforce Helix Swarm API — Reviews. One Spectral-compliant resource per consumed operation,
      prefixed with /v1.
    resources:
    - path: /v1/dashboards/action
      name: dashboards-action
      description: REST surface for dashboards-action.
      operations:
      - method: GET
        name: getactiondashboard
        description: Perforce Get Action Dashboard Reviews
        call: helix-swarm-reviews.getactiondashboard
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews
      name: reviews
      description: REST surface for reviews.
      operations:
      - method: GET
        name: listreviews
        description: Perforce List Reviews
        call: helix-swarm-reviews.listreviews
        with:
          after: rest.after
          max: rest.max
          fields: rest.fields
          author[]: rest.author[]
          change[]: rest.change[]
          hasReviewers: rest.hasReviewers
          ids[]: rest.ids[]
          keywords: rest.keywords
          participants[]: rest.participants[]
          project[]: rest.project[]
          state[]: rest.state[]
          passesTests: rest.passesTests
          notUpdatedSince: rest.notUpdatedSince
          hasVoted: rest.hasVoted
          myComments: rest.myComments
        outputParameters:
        - type: object
          mapping: $.
      - method: POST
        name: createreview
        description: Perforce Create a Review
        call: helix-swarm-reviews.createreview
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/archive
      name: reviews-archive
      description: REST surface for reviews-archive.
      operations:
      - method: POST
        name: archiveinactivereviews
        description: Perforce Archive Inactive Reviews
        call: helix-swarm-reviews.archiveinactivereviews
        with:
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/{id}
      name: reviews-id
      description: REST surface for reviews-id.
      operations:
      - method: GET
        name: getreview
        description: Perforce Get Review Details
        call: helix-swarm-reviews.getreview
        with:
          id: rest.id
          fields: rest.fields
        outputParameters:
        - type: object
          mapping: $.
      - method: PATCH
        name: updatereview
        description: Perforce Update Review Description
        call: helix-swarm-reviews.updatereview
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/{id}/changes
      name: reviews-id-changes
      description: REST surface for reviews-id-changes.
      operations:
      - method: POST
        name: addchangetoreview
        description: Perforce Add Change to Review
        call: helix-swarm-reviews.addchangetoreview
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/{id}/cleanup
      name: reviews-id-cleanup
      description: REST surface for reviews-id-cleanup.
      operations:
      - method: POST
        name: cleanupreview
        description: Perforce Clean up a Review
        call: helix-swarm-reviews.cleanupreview
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/{id}/obliterate
      name: reviews-id-obliterate
      description: REST surface for reviews-id-obliterate.
      operations:
      - method: POST
        name: obliteratereview
        description: Perforce Obliterate a Review
        call: helix-swarm-reviews.obliteratereview
        with:
          id: rest.id
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/{id}/state
      name: reviews-id-state
      description: REST surface for reviews-id-state.
      operations:
      - method: PATCH
        name: transitionreviewstate
        description: Perforce Transition Review State
        call: helix-swarm-reviews.transitionreviewstate
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/{id}/transitions
      name: reviews-id-transitions
      description: REST surface for reviews-id-transitions.
      operations:
      - method: GET
        name: getreviewtransitions
        description: Perforce Get Review Transitions
        call: helix-swarm-reviews.getreviewtransitions
        with:
          id: rest.id
          upVoters: rest.upVoters
        outputParameters:
        - type: object
          mapping: $.
    - path: /v1/reviews/{id}/vote
      name: reviews-id-vote
      description: REST surface for reviews-id-vote.
      operations:
      - method: POST
        name: setreviewvote
        description: Perforce Set Vote on Review
        call: helix-swarm-reviews.setreviewvote
        with:
          id: rest.id
          body: rest.body
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    namespace: helix-swarm-reviews-mcp
    port: 9090
    transport: http
    description: MCP adapter for Perforce Helix Swarm API — Reviews. One tool per consumed operation, routed inline through
      this capability's consumes block.
    tools:
    - name: perforce-get-action-dashboard-reviews
      description: Perforce Get Action Dashboard Reviews
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-swarm-reviews.getactiondashboard
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-list-reviews
      description: Perforce List Reviews
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-swarm-reviews.listreviews
      with:
        after: tools.after
        max: tools.max
        fields: tools.fields
        author[]: tools.author[]
        change[]: tools.change[]
        hasReviewers: tools.hasReviewers
        ids[]: tools.ids[]
        keywords: tools.keywords
        participants[]: tools.participants[]
        project[]: tools.project[]
        state[]: tools.state[]
        passesTests: tools.passesTests
        notUpdatedSince: tools.notUpdatedSince
        hasVoted: tools.hasVoted
        myComments: tools.myComments
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-create-review
      description: Perforce Create a Review
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: helix-swarm-reviews.createreview
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-archive-inactive-reviews
      description: Perforce Archive Inactive Reviews
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: helix-swarm-reviews.archiveinactivereviews
      with:
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-get-review-details
      description: Perforce Get Review Details
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-swarm-reviews.getreview
      with:
        id: tools.id
        fields: tools.fields
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-update-review-description
      description: Perforce Update Review Description
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: helix-swarm-reviews.updatereview
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-add-change-review
      description: Perforce Add Change to Review
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: helix-swarm-reviews.addchangetoreview
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-clean-up-review
      description: Perforce Clean up a Review
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: helix-swarm-reviews.cleanupreview
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-obliterate-review
      description: Perforce Obliterate a Review
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: helix-swarm-reviews.obliteratereview
      with:
        id: tools.id
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-transition-review-state
      description: Perforce Transition Review State
      hints:
        readOnly: false
        destructive: false
        idempotent: true
      call: helix-swarm-reviews.transitionreviewstate
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-get-review-transitions
      description: Perforce Get Review Transitions
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: helix-swarm-reviews.getreviewtransitions
      with:
        id: tools.id
        upVoters: tools.upVoters
      outputParameters:
      - type: object
        mapping: $.
    - name: perforce-set-vote-review
      description: Perforce Set Vote on Review
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: helix-swarm-reviews.setreviewvote
      with:
        id: tools.id
        body: tools.body
      outputParameters:
      - type: object
        mapping: $.