Perforce Projects API

openapi: 3.1.0
info:
  title: Perforce Helix Swarm Activity Projects API
  version: '9'
  description: 'REST API for Perforce Helix Swarm (P4 Code Review), providing programmatic

    access to code reviews, changelists, comments, activity streams, and project

    management. Helix Swarm enables collaborative code review workflows

    integrated with Helix Core version control.


    The API uses HTTP Basic authentication with Perforce credentials or API

    tickets. All endpoints are prefixed with /api/v9. As of Swarm 2022.2,

    API versions older than v9 are no longer supported. Version v11 extends

    the API but does not yet cover all features, so v9 is recommended for

    full functionality.'
  contact:
    name: Perforce Support
    url: https://www.perforce.com/support
  license:
    name: Proprietary
    url: https://www.perforce.com/terms-use
  termsOfService: https://www.perforce.com/terms-use
servers:
- url: '{scheme}://{host}/api/v9'
  description: Helix Swarm server instance
  variables:
    scheme:
      default: https
      enum:
      - https
      - http
      description: The protocol scheme.
    host:
      default: swarm.example.com
      description: The hostname of your Helix Swarm instance.
security:
- basicAuth: []
tags:
- name: Projects
  description: Endpoints for managing Swarm projects.
paths:
  /projects/:
    get:
      operationId: listProjects
      summary: Perforce List Projects
      description: Retrieves a list of Swarm projects with their configuration, branches, members, and settings.
      tags:
      - Projects
      parameters:
      - name: fields
        in: query
        description: Comma-separated list of fields to include in the response.
        schema:
          type: string
        example: example_value
      - name: workflow
        in: query
        description: Filter projects using a specific workflow.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: A list of projects.
          content:
            application/json:
              schema:
                type: object
                properties:
                  projects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
              examples:
                Listprojects200Example:
                  summary: Default listProjects 200 response
                  x-microcks-default: true
                  value:
                    projects:
                    - id: abc123
                      name: Example Title
                      description: A sample description.
                      members:
                      - {}
                      owners:
                      - {}
                      subgroups:
                      - {}
                      branches:
                      - {}
                      deleted: true
                      deploy: example_value
                      emailFlags: user@example.com
                      jobview: example_value
                      minimumUpVotes: 10
                      private: true
                      retainDefaultReviewers: true
                      tests: example_value
                      workflow: example_value
                      defaults: example_value
                      readme: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createProject
      summary: Perforce Create a Project
      description: Creates a new Swarm project with the specified configuration.
      tags:
      - Projects
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - name
              - members
              properties:
                name:
                  type: string
                  description: The project name.
                members:
                  type: array
                  items:
                    type: string
                  description: Array of project member usernames.
                subgroups:
                  type: array
                  items:
                    type: string
                  description: Array of subgroup names.
                owners:
                  type: array
                  items:
                    type: string
                  description: Array of project owner usernames.
                description:
                  type: string
                  description: The project description.
                private:
                  type: boolean
                  default: false
                  description: Whether the project is private.
            examples:
              CreateprojectRequestExample:
                summary: Default createProject request
                x-microcks-default: true
                value:
                  name: Example Title
                  members:
                  - example_value
                  subgroups:
                  - example_value
                  owners:
                  - example_value
                  description: A sample description.
                  private: true
      responses:
        '200':
          description: The newly created project.
          content:
            application/json:
              schema:
                type: object
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
              examples:
                Createproject200Example:
                  summary: Default createProject 200 response
                  x-microcks-default: true
                  value:
                    project:
                      id: abc123
                      name: Example Title
                      description: A sample description.
                      members:
                      - example_value
                      owners:
                      - example_value
                      subgroups:
                      - example_value
                      branches:
                      - id: abc123
                        name: Example Title
                        paths: {}
                        moderators: {}
                      deleted: true
                      deploy: example_value
                      emailFlags: user@example.com
                      jobview: example_value
                      minimumUpVotes: 10
                      private: true
                      retainDefaultReviewers: true
                      tests: example_value
                      workflow: example_value
                      defaults: example_value
                      readme: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /projects/{id}:
    get:
      operationId: getProject
      summary: Perforce Get Project Details
      description: Retrieves detailed information for a specific Swarm project.
      tags:
      - Projects
      parameters:
      - name: id
        in: path
        required: true
        description: The project identifier.
        schema:
          type: string
        example: abc123
      - name: fields
        in: query
        description: Comma-separated list of fields to include in the response.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Project details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
              examples:
                Getproject200Example:
                  summary: Default getProject 200 response
                  x-microcks-default: true
                  value:
                    project:
                      id: abc123
                      name: Example Title
                      description: A sample description.
                      members:
                      - example_value
                      owners:
                      - example_value
                      subgroups:
                      - example_value
                      branches:
                      - id: abc123
                        name: Example Title
                        paths: {}
                        moderators: {}
                      deleted: true
                      deploy: example_value
                      emailFlags: user@example.com
                      jobview: example_value
                      minimumUpVotes: 10
                      private: true
                      retainDefaultReviewers: true
                      tests: example_value
                      workflow: example_value
                      defaults: example_value
                      readme: example_value
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateProject
      summary: Perforce Update a Project
      description: Updates an existing Swarm project's configuration.
      tags:
      - Projects
      parameters:
      - name: id
        in: path
        required: true
        description: The project identifier.
        schema:
          type: string
        example: abc123
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: Updated project name.
                members:
                  type: array
                  items:
                    type: string
                  description: Updated list of project members.
                owners:
                  type: array
                  items:
                    type: string
                  description: Updated list of project owners.
                description:
                  type: string
                  description: Updated project description.
                private:
                  type: boolean
                  description: Updated privacy setting.
            examples:
              UpdateprojectRequestExample:
                summary: Default updateProject request
                x-microcks-default: true
                value:
                  name: Example Title
                  members:
                  - example_value
                  owners:
                  - example_value
                  description: A sample description.
                  private: true
      responses:
        '200':
          description: The updated project.
          content:
            application/json:
              schema:
                type: object
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
              examples:
                Updateproject200Example:
                  summary: Default updateProject 200 response
                  x-microcks-default: true
                  value:
                    project:
                      id: abc123
                      name: Example Title
                      description: A sample description.
                      members:
                      - example_value
                      owners:
                      - example_value
                      subgroups:
                      - example_value
                      branches:
                      - id: abc123
                        name: Example Title
                        paths: {}
                        moderators: {}
                      deleted: true
                      deploy: example_value
                      emailFlags: user@example.com
                      jobview: example_value
                      minimumUpVotes: 10
                      private: true
                      retainDefaultReviewers: true
                      tests: example_value
                      workflow: example_value
                      defaults: example_value
                      readme: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteProject
      summary: Perforce Delete a Project
      description: Deletes a Swarm project. Only project owners or administrators can perform this action.
      tags:
      - Projects
      parameters:
      - name: id
        in: path
        required: true
        description: The project identifier.
        schema:
          type: string
        example: abc123
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The ID of the deleted project.
              examples:
                Deleteproject200Example:
                  summary: Default deleteProject 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: A human-readable error message.
    Unauthorized:
      description: Authentication is required or the provided credentials are invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: A human-readable error message.
    BadRequest:
      description: The request was malformed or missing required parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
                description: A human-readable error message.
              details:
                type: object
                description: Additional details about the validation error.
  schemas:
    Project:
      type: object
      description: A project in Helix Swarm, grouping branches, members, and review settings.
      properties:
        id:
          type: string
          description: The project identifier.
          example: abc123
        name:
          type: string
          description: The project display name.
          example: Example Title
        description:
          type: string
          description: The project description.
          example: A sample description.
        members:
          type: array
          items:
            type: string
          description: List of project member usernames.
          example: []
        owners:
          type: array
          items:
            type: string
          description: List of project owner usernames.
          example: []
        subgroups:
          type: array
          items:
            type: string
          description: List of associated Perforce groups.
          example: []
        branches:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              name:
                type: string
              paths:
                type: array
                items:
                  type: string
              moderators:
                type: array
                items:
                  type: string
          description: Branch definitions for the project.
          example: []
        deleted:
          type: boolean
          description: Whether the project has been deleted.
          example: true
        deploy:
          type: object
          description: Deploy configuration for the project.
          example: example_value
        emailFlags:
          type: object
          description: Email notification settings.
          example: user@example.com
        jobview:
          type: string
          description: A Perforce jobview expression for the project.
          example: example_value
        minimumUpVotes:
          type: integer
          description: Minimum number of up votes required for approval.
          example: 10
        private:
          type: boolean
          description: Whether the project is private.
          example: true
        retainDefaultReviewers:
          type: boolean
          description: Whether to retain default reviewers on review updates.
          example: true
        tests:
          type: object
          description: Test configuration for the project.
          example: example_value
        workflow:
          type: string
          description: The workflow identifier associated with the project.
          example: example_value
        defaults:
          type: object
          description: Default settings for the project.
          example: example_value
        readme:
          type: string
          description: The project readme content.
          example: example_value
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using Perforce username and password or ticket. The password can be a standard Perforce password or a Swarm-generated API ticket.
externalDocs:
  description: Helix Swarm API Documentation
  url: https://help.perforce.com/helix-core/helix-swarm/swarm/current/Content/Swarm/swarm-apidoc_endpoints.html