openapi: 3.0.1
info:
  title: Endor Labs REST API
  description: >-
    The Endor Labs REST API is a uniform resource API over namespaces. Every
    resource kind (Project, PackageVersion, DependencyMetadata, Finding, Policy,
    ScanResult, Metric, and more) is addressed under
    /v1/namespaces/{namespace}/{resource}, with consistent list (GET), get
    (GET /{uuid}), create (POST), update (PATCH /{uuid}), and delete
    (DELETE /{uuid}) semantics. List endpoints share a common set of
    list_parameters (filter, mask, page_size, page_token, sort, count, group).
    Authentication is a bearer access token obtained by exchanging an API key and
    secret at POST /v1/auth/api-key.
  termsOfService: https://www.endorlabs.com/terms
  contact:
    name: Endor Labs Support
    url: https://docs.endorlabs.com/rest-api/
  version: '1.0'
servers:
  - url: https://api.endorlabs.com/v1
security:
  - bearerAuth: []
tags:
  - name: Authentication
    description: Exchange API key and secret for a bearer access token.
  - name: Namespaces
    description: Tenants and child namespaces a token may access.
  - name: Projects
    description: Project resources - the root of scanned source code.
  - name: Packages
    description: PackageVersion and dependency resources.
  - name: Findings
    description: Detected problems requiring remediation.
  - name: Policies
    description: Governance rules over resources.
  - name: Scan Results
    description: Scan execution results and metrics.
paths:
  /auth/api-key:
    post:
      operationId: exchangeApiKey
      tags:
        - Authentication
      summary: Exchange an API key and secret for an access token.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApiKeyRequest'
      responses:
        '200':
          description: A bearer access token with the same scopes as the API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /namespaces/{namespace}/projects:
    get:
      operationId: listProjects
      tags:
        - Projects
      summary: List Project resources in a namespace.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Mask'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
        - $ref: '#/components/parameters/SortPath'
        - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: A list of Project resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createProject
      tags:
        - Projects
      summary: Create a Project resource in a namespace.
      parameters:
        - $ref: '#/components/parameters/Namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Project'
      responses:
        '200':
          description: The created Project resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /namespaces/{namespace}/projects/{uuid}:
    get:
      operationId: getProject
      tags:
        - Projects
      summary: Get a Project resource by UUID.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: The requested Project resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Project'
        '404':
          $ref: '#/components/responses/NotFound'

  /namespaces/{namespace}/package-versions:
    get:
      operationId: listPackageVersions
      tags:
        - Packages
      summary: List PackageVersion resources in a namespace.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Mask'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
        - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: A list of PackageVersion resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageVersionList'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /namespaces/{namespace}/package-versions/{uuid}:
    get:
      operationId: getPackageVersion
      tags:
        - Packages
      summary: Get a PackageVersion resource by UUID.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: The requested PackageVersion resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PackageVersion'
        '404':
          $ref: '#/components/responses/NotFound'

  /namespaces/{namespace}/findings:
    get:
      operationId: listFindings
      tags:
        - Findings
      summary: List Finding resources in a namespace.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Mask'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
        - $ref: '#/components/parameters/SortPath'
        - $ref: '#/components/parameters/Count'
      responses:
        '200':
          description: A list of Finding resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FindingList'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /namespaces/{namespace}/findings/{uuid}:
    get:
      operationId: getFinding
      tags:
        - Findings
      summary: Get a Finding resource by UUID.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: The requested Finding resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Finding'
        '404':
          $ref: '#/components/responses/NotFound'

  /namespaces/{namespace}/policies:
    get:
      operationId: listPolicies
      tags:
        - Policies
      summary: List Policy resources in a namespace.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Mask'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: A list of Policy resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PolicyList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createPolicy
      tags:
        - Policies
      summary: Create a Policy resource in a namespace.
      parameters:
        - $ref: '#/components/parameters/Namespace'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
      responses:
        '200':
          description: The created Policy resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /namespaces/{namespace}/policies/{uuid}:
    get:
      operationId: getPolicy
      tags:
        - Policies
      summary: Get a Policy resource by UUID.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: The requested Policy resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updatePolicy
      tags:
        - Policies
      summary: Update a Policy resource by UUID.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Uuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Policy'
      responses:
        '200':
          description: The updated Policy resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Policy'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deletePolicy
      tags:
        - Policies
      summary: Delete a Policy resource by UUID.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: The Policy resource was deleted.
        '404':
          $ref: '#/components/responses/NotFound'

  /namespaces/{namespace}/scan-results:
    get:
      operationId: listScanResults
      tags:
        - Scan Results
      summary: List ScanResult resources in a namespace.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Filter'
        - $ref: '#/components/parameters/Mask'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: A list of ScanResult resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResultList'
        '401':
          $ref: '#/components/responses/Unauthorized'

  /namespaces/{namespace}/scan-results/{uuid}:
    get:
      operationId: getScanResult
      tags:
        - Scan Results
      summary: Get a ScanResult resource by UUID.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/Uuid'
      responses:
        '200':
          description: The requested ScanResult resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScanResult'
        '404':
          $ref: '#/components/responses/NotFound'

  /namespaces/{namespace}/namespaces:
    get:
      operationId: listNamespaces
      tags:
        - Namespaces
      summary: List child namespaces under a namespace.
      parameters:
        - $ref: '#/components/parameters/Namespace'
        - $ref: '#/components/parameters/PageSize'
        - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: A list of Namespace resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NamespaceList'
        '401':
          $ref: '#/components/responses/Unauthorized'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer access token obtained from POST /v1/auth/api-key by exchanging
        an Endor Labs API key and secret.
  parameters:
    Namespace:
      name: namespace
      in: path
      required: true
      description: The tenant namespace (tenant_meta.namespace) that scopes the resource.
      schema:
        type: string
    Uuid:
      name: uuid
      in: path
      required: true
      description: The UUID of the resource.
      schema:
        type: string
    Filter:
      name: list_parameters.filter
      in: query
      required: false
      description: Endor query-language filter expression applied to the resource list.
      schema:
        type: string
    Mask:
      name: list_parameters.mask
      in: query
      required: false
      description: Comma-separated field mask selecting which fields to return.
      schema:
        type: string
    PageSize:
      name: list_parameters.page_size
      in: query
      required: false
      description: Maximum number of resources to return per page.
      schema:
        type: integer
        format: int32
    PageToken:
      name: list_parameters.page_token
      in: query
      required: false
      description: Opaque token to retrieve the next page of results.
      schema:
        type: string
    SortPath:
      name: list_parameters.sort.path
      in: query
      required: false
      description: Field path to sort the result set by.
      schema:
        type: string
    Count:
      name: list_parameters.count
      in: query
      required: false
      description: When true, return only the count of matching resources.
      schema:
        type: boolean
  responses:
    Unauthorized:
      description: Missing or invalid bearer access token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    ApiKeyRequest:
      type: object
      required:
        - key
        - secret
      properties:
        key:
          type: string
          description: The API key identifier.
        secret:
          type: string
          description: The API key secret.
    TokenResponse:
      type: object
      properties:
        token:
          type: string
          description: The bearer access token.
        expiration_time:
          type: string
          format: date-time
    TenantMeta:
      type: object
      properties:
        namespace:
          type: string
          description: The namespace the resource belongs to.
    ResourceMeta:
      type: object
      properties:
        name:
          type: string
        kind:
          type: string
        description:
          type: string
        version:
          type: string
        create_time:
          type: string
          format: date-time
        update_time:
          type: string
          format: date-time
    Project:
      type: object
      properties:
        uuid:
          type: string
        meta:
          $ref: '#/components/schemas/ResourceMeta'
        tenant_meta:
          $ref: '#/components/schemas/TenantMeta'
        spec:
          type: object
          properties:
            git:
              type: object
              properties:
                http_clone_url:
                  type: string
                full_name:
                  type: string
            platform_source:
              type: string
              description: Source platform, e.g. GITHUB, GITLAB.
    ProjectList:
      type: object
      properties:
        list:
          type: object
          properties:
            objects:
              type: array
              items:
                $ref: '#/components/schemas/Project'
            response:
              $ref: '#/components/schemas/ListResponse'
    PackageVersion:
      type: object
      properties:
        uuid:
          type: string
        meta:
          $ref: '#/components/schemas/ResourceMeta'
        tenant_meta:
          $ref: '#/components/schemas/TenantMeta'
        spec:
          type: object
          properties:
            ecosystem:
              type: string
            package_name:
              type: string
            version:
              type: string
            project_uuid:
              type: string
    PackageVersionList:
      type: object
      properties:
        list:
          type: object
          properties:
            objects:
              type: array
              items:
                $ref: '#/components/schemas/PackageVersion'
            response:
              $ref: '#/components/schemas/ListResponse'
    Finding:
      type: object
      properties:
        uuid:
          type: string
        meta:
          $ref: '#/components/schemas/ResourceMeta'
        tenant_meta:
          $ref: '#/components/schemas/TenantMeta'
        spec:
          type: object
          properties:
            finding_categories:
              type: array
              items:
                type: string
            level:
              type: string
              description: Severity level, e.g. FINDING_LEVEL_CRITICAL.
            summary:
              type: string
            explanation:
              type: string
            target_uuid:
              type: string
            project_uuid:
              type: string
            finding_metadata:
              type: object
              properties:
                vulnerability:
                  type: object
                  description: Vulnerability detail when the finding is a vulnerability.
                reachability:
                  type: string
                  description: Reachability assessment for the finding.
    FindingList:
      type: object
      properties:
        list:
          type: object
          properties:
            objects:
              type: array
              items:
                $ref: '#/components/schemas/Finding'
            response:
              $ref: '#/components/schemas/ListResponse'
    Policy:
      type: object
      properties:
        uuid:
          type: string
        meta:
          $ref: '#/components/schemas/ResourceMeta'
        tenant_meta:
          $ref: '#/components/schemas/TenantMeta'
        spec:
          type: object
          properties:
            policy_type:
              type: string
            resource_kinds:
              type: array
              items:
                type: string
            query_statements:
              type: array
              items:
                type: string
            rule:
              type: string
            disable:
              type: boolean
    PolicyList:
      type: object
      properties:
        list:
          type: object
          properties:
            objects:
              type: array
              items:
                $ref: '#/components/schemas/Policy'
            response:
              $ref: '#/components/schemas/ListResponse'
    ScanResult:
      type: object
      properties:
        uuid:
          type: string
        meta:
          $ref: '#/components/schemas/ResourceMeta'
        tenant_meta:
          $ref: '#/components/schemas/TenantMeta'
        spec:
          type: object
          properties:
            project_uuid:
              type: string
            type:
              type: string
            status:
              type: string
            start_time:
              type: string
              format: date-time
            end_time:
              type: string
              format: date-time
    ScanResultList:
      type: object
      properties:
        list:
          type: object
          properties:
            objects:
              type: array
              items:
                $ref: '#/components/schemas/ScanResult'
            response:
              $ref: '#/components/schemas/ListResponse'
    Namespace:
      type: object
      properties:
        uuid:
          type: string
        meta:
          $ref: '#/components/schemas/ResourceMeta'
        tenant_meta:
          $ref: '#/components/schemas/TenantMeta'
    NamespaceList:
      type: object
      properties:
        list:
          type: object
          properties:
            objects:
              type: array
              items:
                $ref: '#/components/schemas/Namespace'
            response:
              $ref: '#/components/schemas/ListResponse'
    ListResponse:
      type: object
      properties:
        next_page_token:
          type: string
        count:
          type: integer
          format: int32
    Error:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string