Perforce Activity API

openapi: 3.2.0
info:
  title: Perforce Helix Swarm Activity 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.'
  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: Activity
  description: Endpoints for viewing and creating activity stream entries.
paths:
  /activity:
    get:
      operationId: listActivity
      summary: Perforce List Activity Entries
      description: Retrieves a list of activity entries from the activity stream, optionally filtered by changelist, stream, or type.
      tags:
      - Activity
      parameters:
      - name: change
        in: query
        description: Filter activity by changelist ID.
        schema:
          type: integer
        example: 10
      - name: stream
        in: query
        description: Filter by activity stream name, such as user-alice, review-1234, or project-myproject.
        schema:
          type: string
        example: example_value
      - name: type
        in: query
        description: Filter by activity type.
        schema:
          type: string
          enum:
          - change
          - comment
          - job
          - review
        example: change
      - name: after
        in: query
        description: An activity ID to seek past for pagination.
        schema:
          type: integer
        example: 10
      - name: max
        in: query
        description: Maximum number of entries to return. Defaults to 100.
        schema:
          type: integer
          default: 100
        example: 10
      - name: fields
        in: query
        description: Comma-separated list of fields to include in the response.
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: A list of activity entries.
          content:
            application/json:
              schema:
                type: object
                properties:
                  activity:
                    type: array
                    items:
                      $ref: '#/components/schemas/Activity'
                  lastSeen:
                    type: integer
                    description: The ID of the last entry for pagination.
              examples:
                Listactivity200Example:
                  summary: Default listActivity 200 response
                  x-microcks-default: true
                  value:
                    activity:
                    - id: abc123
                      action: example_value
                      change: 10
                      date: '2026-01-15T10:30:00Z'
                      description: A sample description.
                      link: https://www.example.com
                      streams:
                      - {}
                      target: example_value
                      topic: example_value
                      type: example_value
                      user: example_value
                    lastSeen: 10
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createActivity
      summary: Perforce Create Activity Entry
      description: Creates a new entry in the activity stream.
      tags:
      - Activity
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
              - type
              - user
              - action
              - target
              properties:
                type:
                  type: string
                  description: The activity classification type.
                user:
                  type: string
                  description: The username of the user performing the action.
                action:
                  type: string
                  description: A past-tense description of the activity.
                target:
                  type: string
                  description: The object receiving the action.
                topic:
                  type: string
                  description: An optional comment thread identifier.
                description:
                  type: string
                  description: Contextual information about the activity.
                change:
                  type: integer
                  description: A related changelist ID.
                streams[]:
                  type: array
                  items:
                    type: string
                  description: Stream names where the activity should appear.
                link:
                  type: string
                  format: uri
                  description: A URL for the activity target.
            examples:
              CreateactivityRequestExample:
                summary: Default createActivity request
                x-microcks-default: true
                value:
                  type: example_value
                  user: example_value
                  action: example_value
                  target: example_value
                  topic: example_value
                  description: A sample description.
                  change: 10
                  streams[]:
                  - example_value
                  link: https://www.example.com
      responses:
        '200':
          description: The newly created activity entry.
          content:
            application/json:
              schema:
                type: object
                properties:
                  activity:
                    $ref: '#/components/schemas/Activity'
              examples:
                Createactivity200Example:
                  summary: Default createActivity 200 response
                  x-microcks-default: true
                  value:
                    activity:
                      id: abc123
                      action: example_value
                      change: 10
                      date: '2026-01-15T10:30:00Z'
                      description: A sample description.
                      link: https://www.example.com
                      streams:
                      - example_value
                      target: example_value
                      topic: example_value
                      type: example_value
                      user: example_value
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    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.
    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.
  schemas:
    Activity:
      type: object
      description: An entry in the Helix Swarm activity stream recording an action performed by a user.
      properties:
        id:
          type: integer
          description: The unique activity entry identifier.
          example: abc123
        action:
          type: string
          description: A past-tense description of the action performed.
          example: example_value
        change:
          type: integer
          description: The related changelist ID, if applicable.
          example: 10
        date:
          type: string
          format: date-time
          description: The date and time the activity occurred.
          example: '2026-01-15T10:30:00Z'
        description:
          type: string
          description: Contextual information about the activity.
          example: A sample description.
        link:
          type: string
          format: uri
          description: A URL linking to the activity target.
          example: https://www.example.com
        streams:
          type: array
          items:
            type: string
          description: The activity streams this entry appears in.
          example: []
        target:
          type: string
          description: The object that received the action.
          example: example_value
        topic:
          type: string
          description: An associated comment thread topic.
          example: example_value
        type:
          type: string
          description: The activity type classification.
          example: example_value
        user:
          type: string
          description: The username of the user who performed the action.
          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