openapi: 3.0.4
info:
  title: P0 Inventory Export API
  version: 1.0.0
  description: >-
    Read-only endpoints to list your P0 environments and export their access
    inventory as JSON. Both endpoints require the `assessment.read` permission,
    which is included in the Owner role that every API key carries.
servers:
  - url: https://api.p0.app/o/{orgId}
    variables:
      orgId:
        default: demo-org
        description: The organization ID
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
  parameters:
    assessmentId:
      name: assessmentId
      in: path
      required: true
      description: The environment ID returned by the list endpoint. An environment ID is also its assessment ID.
      schema:
        type: string
  responses:
    UnauthorizedError:
      description: The caller could not be authenticated.
    NotFoundError:
      description: No environment matches the given ID.
    NoCompletedAssessmentError:
      description: The environment has no completed assessment to export.
    TooManyRequestsError:
      description: Too many inventory exports are in progress. Back off and retry shortly.
  schemas:
    AssessmentScope:
      type: object
      description: A single scope covered by an environment's assessment.
      properties:
        id:
          type: string
          description: The identifier of the scoped target, such as a project, account, or subscription ID.
        integration:
          type: string
          description: The cloud integration the scope belongs to.
          example: gcloud
        type:
          type: string
          description: The kind of target the scope covers.
          example: project
    Environment:
      type: object
      description: An environment in the organization. Environments are backed by IAM assessments.
      properties:
        id:
          type: string
          description: The environment ID. Pass this as the `assessmentId` path parameter to export the environment's inventory.
        name:
          type: string
          description: The display name of the environment.
          example: Prod
        targets:
          type: array
          description: The assessment scopes the environment covers.
          items:
            $ref: "#/components/schemas/AssessmentScope"
    EnvironmentList:
      type: object
      properties:
        environments:
          type: array
          items:
            $ref: "#/components/schemas/Environment"
    InventoryEntity:
      type: object
      description: >-
        A single inventory entity. Every entity carries a stable `key` alongside
        its own fields. The remaining fields vary by entity type and by cloud
        provider.
      required:
        - key
      properties:
        key:
          type: string
          description: The entity's stable identifier in the inventory graph.
      additionalProperties: true
    InventoryExport:
      type: object
      description: >-
        The environment's inventory, grouped by entity type. Each entity appears
        once per group; entities that span multiple assessment scopes are
        de-duplicated by key.
      properties:
        credentials:
          type: array
          description: Keys, tokens, and other credentials discovered in the environment.
          items:
            $ref: "#/components/schemas/InventoryEntity"
        identities:
          type: array
          description: Users, service accounts, and groups.
          items:
            $ref: "#/components/schemas/InventoryEntity"
        grants:
          type: array
          description: Access grants that bind a principal to a privilege set on one or more resources. These appear as entitlements in the inventory UI.
          items:
            $ref: "#/components/schemas/InventoryEntity"
        resources:
          type: array
          description: Cloud resources such as buckets, databases, and compute instances.
          items:
            $ref: "#/components/schemas/InventoryEntity"
paths:
  /assessment:
    get:
      summary: List environments
      description: Returns every environment in the organization, along with the assessment scopes each environment covers.
      security:
        - bearerAuth: []
      responses:
        200:
          description: The environments in the organization.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EnvironmentList"
        401:
          $ref: "#/components/responses/UnauthorizedError"
  /assessment/{assessmentId}/export:
    get:
      summary: Export inventory
      description: >-
        Exports the inventory of an environment's latest completed assessment as
        a single JSON document, grouped by entity type. The response is streamed
        and gzip-compressed, so it scales to large environments. The
        `X-P0-Assessment-Job-Id` response header identifies the assessment job
        the inventory came from.
      parameters:
        - $ref: "#/components/parameters/assessmentId"
      security:
        - bearerAuth: []
      responses:
        200:
          description: The environment's inventory, grouped by entity type.
          headers:
            X-P0-Assessment-Job-Id:
              description: The ID of the assessment job the inventory came from.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InventoryExport"
        401:
          $ref: "#/components/responses/UnauthorizedError"
        404:
          $ref: "#/components/responses/NotFoundError"
        422:
          $ref: "#/components/responses/NoCompletedAssessmentError"
        429:
          $ref: "#/components/responses/TooManyRequestsError"
