Cloud Foundry Audit Events API

openapi: 3.2.0
info:
  title: Cloud Foundry V3 Audit Events API
  description: '# Welcome to the Experimental Cloud Foundry V3 API Docs!'
  version: latest
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  contact:
    name: Cloud Foundry
    url: https://www.cloudfoundry.org/
servers:
- url: https://api.example.local
  description: Cloud Foundry V3 API server
security:
- oauth:
  - cloud_controller.read
  - cloud_controller.write
tags:
- name: Audit Events
  description: Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions.
paths:
  /v3/audit_events:
    get:
      summary: List audit events
      description: Retrieve all audit events the user has access to.
      operationId: listAuditEvents
      tags:
      - Audit Events
      parameters:
      - $ref: '#/components/parameters/Page'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/OrderBy'
      - $ref: '#/components/parameters/CreatedAts'
      - $ref: '#/components/parameters/UpdatedAts'
      - name: types
        in: query
        schema:
          type: array
          items:
            type: string
            enum:
            - audit.app.apply_manifest
            - audit.app.build.create
            - audit.app.copy-bits
            - audit.app.create
            - audit.app.delete-request
            - audit.app.deployment.cancel
            - audit.app.deployment.create
            - audit.app.deployment.continue
            - audit.app.droplet.create
            - audit.app.droplet.delete
            - audit.app.droplet.download
            - audit.app.droplet.mapped
            - audit.app.droplet.upload
            - audit.app.environment.show
            - audit.app.environment_variables.show
            - audit.app.map-route
            - audit.app.package.create
            - audit.app.package.delete
            - audit.app.package.download
            - audit.app.package.upload
            - audit.app.process.crash
            - audit.app.process.create
            - audit.app.process.delete
            - audit.app.process.ready
            - audit.app.process.not-ready
            - audit.app.process.rescheduling
            - audit.app.process.scale
            - audit.app.process.terminate_instance
            - audit.app.process.update
            - audit.app.restage
            - audit.app.restart
            - audit.app.revision.create
            - audit.app.revision.environment_variables.show
            - audit.app.ssh-authorized
            - audit.app.ssh-unauthorized
            - audit.app.start
            - audit.app.stop
            - audit.app.task.cancel
            - audit.app.task.create
            - audit.app.unmap-route
            - audit.app.update
            - audit.app.upload-bits
            - audit.organization.create
            - audit.organization.delete-request
            - audit.organization.update
            - audit.route.create
            - audit.route.delete-request
            - audit.route.share
            - audit.route.transfer-owner
            - audit.route.unshare
            - audit.route.update
            - audit.service.create
            - audit.service.delete
            - audit.service.update
            - audit.service_binding.create
            - audit.service_binding.delete
            - audit.service_binding.show
            - audit.service_binding.start_create
            - audit.service_binding.start_delete
            - audit.service_binding.update
            - audit.service_broker.create
            - audit.service_broker.delete
            - audit.service_broker.update
            - audit.service_dashboard_client.create
            - audit.service_dashboard_client.delete
            - audit.service_instance.bind_route
            - audit.service_instance.create
            - audit.service_instance.delete
            - audit.service_instance.purge
            - audit.service_instance.share
            - audit.service_instance.show
            - audit.service_instance.start_create
            - audit.service_instance.start_delete
            - audit.service_instance.start_update
            - audit.service_instance.unbind_route
            - audit.service_instance.unshare
            - audit.service_instance.update
            - audit.service_key.create
            - audit.service_key.delete
            - audit.service_key.show
            - audit.service_key.start_create
            - audit.service_key.start_delete
            - audit.service_key.update
            - audit.service_plan.create
            - audit.service_plan.delete
            - audit.service_plan.update
            - audit.service_plan_visibility.create
            - audit.service_plan_visibility.delete
            - audit.service_plan_visibility.update
            - audit.service_route_binding.create
            - audit.service_route_binding.delete
            - audit.service_route_binding.start_create
            - audit.service_route_binding.start_delete
            - audit.service_route_binding.update
            - audit.space.create
            - audit.space.delete-request
            - audit.space.update
            - audit.user.organization_auditor_add
            - audit.user.organization_auditor_remove
            - audit.user.organization_billing_manager_add
            - audit.user.organization_billing_manager_remove
            - audit.user.organization_manager_add
            - audit.user.organization_manager_remove
            - audit.user.organization_user_add
            - audit.user.organization_user_remove
            - audit.user.space_auditor_add
            - audit.user.space_auditor_remove
            - audit.user.space_developer_add
            - audit.user.space_developer_remove
            - audit.user.space_manager_add
            - audit.user.space_manager_remove
            - audit.user.space_supporter_add
            - audit.user.space_supporter_remove
            - audit.user_provided_service_instance.create
            - audit.user_provided_service_instance.delete
            - audit.user_provided_service_instance.show
            - audit.user_provided_service_instance.update
            - app.crash
            - blob.remove_orphan
        description: Comma-delimited list of event types to filter by
      - name: target_guids
        in: query
        schema:
          type: array
          items:
            type: string
        description: Comma-delimited list of target guids to filter by. Also supports filtering by exclusion.
      - name: space_guids
        in: query
        schema:
          type: array
          items:
            type: string
        description: Comma-delimited list of space guids to filter by
      - name: organization_guids
        in: query
        schema:
          type: array
          items:
            type: string
        description: Comma-delimited list of organization guids to filter by
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEventList'
              examples:
                default:
                  summary: default
                  value:
                    pagination:
                      total_results: 1
                      total_pages: 1
                      first:
                        href: https://api.example.org?page=1&per_page=2
                      last:
                        href: https://api.example.org?page=1&per_page=2
                      next: null
                      previous: null
                    resources:
                    - guid: 123e4567-e89b-12d3-a456-426614174000
                      created_at: '2016-06-08T16:41:23Z'
                      updated_at: '2016-06-08T16:41:26Z'
                      type: audit.app.update
                      actor:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                        type: user
                        name: admin
                      target:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                        type: app
                        name: my-app
                      data:
                        request:
                          recursive: true
                      space:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                      organization:
                        guid: 123e4567-e89b-12d3-a456-426614174000
                      links:
                        self:
                          href: https://api.example.org//a595fe2f-01ff-4965-a50c-290258ab8582
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '500':
          $ref: '#/components/responses/500'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
  /v3/audit_events/{guid}:
    get:
      summary: Get an audit event
      description: Retrieve a specific audit event.
      operationId: getAuditEvent
      tags:
      - Audit Events
      parameters:
      - $ref: '#/components/parameters/Guid'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuditEvent'
              examples:
                default:
                  summary: default
                  value:
                    guid: 123e4567-e89b-12d3-a456-426614174000
                    created_at: '2016-06-08T16:41:23Z'
                    updated_at: '2016-06-08T16:41:26Z'
                    type: audit.app.update
                    actor:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                      type: user
                      name: admin
                    target:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                      type: app
                      name: my-app
                    data:
                      request:
                        recursive: true
                    space:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                    organization:
                      guid: 123e4567-e89b-12d3-a456-426614174000
                    links:
                      self:
                        href: https://api.example.org/v3/audit_events/a595fe2f-01ff-4965-a50c-290258ab8582
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    Pagination:
      type: object
      properties:
        total_results:
          type: integer
          description: The total number of results available
        total_pages:
          type: integer
          description: The total number of pages available
        first:
          allOf:
          - $ref: '#/components/schemas/Link'
          - description: The first page of results
        last:
          allOf:
          - $ref: '#/components/schemas/Link'
          - description: The last page of results
        next:
          oneOf:
          - $ref: '#/components/schemas/Link'
          - type: 'null'
          description: The next page of results
        previous:
          oneOf:
          - $ref: '#/components/schemas/Link'
          - type: 'null'
          description: The previous page of results
      description: 'Pagination is a technique used to divide a large set of results into smaller, more manageable sets. This allows clients to retrieve results in smaller chunks, reducing the amount of data transferred and improving performance.

        The pagination object is a JSON object that contains information about the pagination state of the results. It includes the total number of results available, the total number of pages available, and links to the first, last, next, and previous pages of results.

        '
    Link:
      type: object
      properties:
        href:
          type: string
          description: The URL of the link
        method:
          type: string
          description: An optional field containing the HTTP method to be used when following the URL
      required:
      - href
      description: 'Each link is keyed by its type and will include a href for the URL and an optional method for links that cannot be followed using GET.

        '
    AuditEvent:
      type: object
      allOf:
      - $ref: '#/components/schemas/BaseSchema'
      - properties:
          type:
            type: string
            description: The type of the event
          actor:
            type: object
            properties:
              guid:
                type: string
                description: The unique identifier for the actor (user or system resource that performed the action)
              type:
                type: string
                description: The actor type
              name:
                type: string
                description: The name of the actor
          target:
            type: object
            properties:
              guid:
                type: string
                description: The unique identifier for the target (resource that the event acted upon)
              type:
                type: string
                description: The target type
              name:
                type: string
                description: The name of the target
          data:
            type: object
            description: Additional information about event
          space:
            type:
            - object
            - 'null'
            properties:
              guid:
                type: string
                description: Unique identifier for the space where the event occurred; if the event did not occur within a space, the `space` field will be `null`
          organization:
            type:
            - object
            - 'null'
            properties:
              guid:
                type: string
                description: Unique identifier for the organization where the event occurred; if the event did not occur within an organization, the `organization` field will be `null`
          links:
            type: object
            properties:
              self:
                $ref: '#/components/schemas/Link'
                description: The URL to get this audit event
      description: 'Audit events help Cloud Foundry operators monitor actions taken against resources (such as apps) via user or system actions.

        '
    AuditEventList:
      type: object
      properties:
        pagination:
          $ref: '#/components/schemas/Pagination'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/AuditEvent'
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      description: 'An error response will always return a list of error objects. Errors appear on the job resource for asynchronous operations.

        Clients should use the code and title fields for programmatically handling specific errors. The message in the detail field is subject to change over time.

        '
    Error:
      type: object
      properties:
        code:
          type: integer
          description: A numeric code for this error
        detail:
          type: string
          description: Detailed description of the error
        title:
          type: string
          description: Name of the error
    BaseSchema:
      type: object
      properties:
        guid:
          type: string
          format: uuid
          description: The unique identifier for the resource
        created_at:
          type: string
          format: date-time
          description: The ISO8601 compatible date and time when resource was created
        updated_at:
          type: string
          format: date-time
          description: The ISO8601 compatible date and time when resource was last updated
      description: 'A resource represents an individual object within the system, such as an app or a service. It is represented as a JSON object.

        A resource consists of several required resource fields and other attributes specific to the resource.

        See Resources and Experimental Resources for specific resources.

        '
  responses:
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    UnprocessableEntity:
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    NotFound:
      description: Not Found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    BadGateway:
      description: Bad Gateway
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Conflict
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    '500':
      description: Internal Server Error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
    BadRequest:
      description: Bad Request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
        text/html:
          schema:
            type: string
    ServiceUnavailable:
      description: Service Unavailable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
  parameters:
    OrderBy:
      name: order_by
      in: query
      required: false
      schema:
        type: string
      description: 'Value to sort by. Defaults to ascending; prepend with `-` to sort descending.

        '
      example: created_at
    CreatedAts:
      name: created_ats
      in: query
      required: false
      schema:
        type: string
      description: 'Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators).

        '
      example: '2021-01-01T00:00:00Z'
    PerPage:
      name: per_page
      in: query
      required: false
      schema:
        type: integer
      description: Number of results per page, valid values are 1 through 5000
      example: 50
    Page:
      name: page
      in: query
      required: false
      schema:
        type: integer
      description: Page to display; valid values are integers >= 1
      example: 1
    UpdatedAts:
      name: updated_ats
      in: query
      required: false
      schema:
        type: string
      description: 'Timestamp to filter by. When filtering on equality, several comma-delimited timestamps may be passed. Also supports filtering with [relational operators](#relational-operators).

        '
      example: '2021-01-01T00:00:00Z'
    Guid:
      name: guid
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The unique identifier for the resource
  securitySchemes:
    oauth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://uaa.cloudfoundry.local/api-oauth/dialog
          scopes:
            cloud_controller.admin: This scope provides read and write access to all resources
            cloud_controller.admin_read_only: This scope provides read only access to all resources
            cloud_controller.global_auditor: This scope provides read access to all resources
            cloud_controller.read: Read access to the Cloud Controller
            cloud_controller.write: Write access to the Cloud Controller
            cloud_controller.update_build_state: This scope allows its bearer to update the state of a build; currently only used when updating builds
            cloud_controller_service_permissions.read: This scope provides read only access for service instance permissions
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT token authentication