openapi: 3.0.1
info:
  title: StackHawk Api Authentication Applications API
  description: The StackHawk Public API provides programmatic access to the StackHawk application and API security testing platform. Manage applications, environments, scan configurations, scan results, findings, repositories, teams, policies, and security reports. Authentication requires obtaining a JWT token via the /api/v1/auth/login endpoint using an API key from the StackHawk platform settings.
  version: 0.0.1
  contact:
    url: https://www.stackhawk.com/
    email: support@stackhawk.com
  termsOfService: https://www.stackhawk.com/terms/
servers:
- url: https://api.stackhawk.com
  description: StackHawk API
security:
- BearerAuth: []
tags:
- name: Applications
  description: Manage applications and environments
paths:
  /api/v1/org/{orgId}/app:
    post:
      operationId: createApplication
      summary: Create Application
      description: Create a new application in the specified organization.
      tags:
      - Applications
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
        description: Organization ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewApplicationRequest'
      responses:
        '200':
          description: Created application
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
  /api/v1/app/{orgId}/list:
    get:
      operationId: listApplications
      summary: List Applications
      description: List all applications for an organization.
      tags:
      - Applications
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of applications
          content:
            application/json:
              schema:
                type: object
                properties:
                  applications:
                    type: array
                    items:
                      $ref: '#/components/schemas/Application'
  /api/v2/org/{orgId}/apps:
    get:
      operationId: listApplicationsV2
      summary: List Applications V2
      description: Paginated list of applications for an organization (v2).
      tags:
      - Applications
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: pageToken
        in: query
        schema:
          type: string
      - name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Paginated applications
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedApplications'
  /api/v1/app/{appId}:
    get:
      operationId: getApplication
      summary: Get Application
      description: Retrieve details for a specific application.
      tags:
      - Applications
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Application details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
    post:
      operationId: updateApplication
      summary: Update Application
      description: Update application settings.
      tags:
      - Applications
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationUpdateRequest'
      responses:
        '200':
          description: Updated application
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
    delete:
      operationId: deleteApplication
      summary: Delete Application
      description: Delete a StackHawk application.
      tags:
      - Applications
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Application deleted
  /api/v1/app/{appId}/env:
    post:
      operationId: createEnvironment
      summary: Create Environment
      description: Create a new environment for an application.
      tags:
      - Applications
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewEnvironmentRequest'
      responses:
        '200':
          description: Created environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
  /api/v1/app/{appId}/env/list:
    get:
      operationId: listEnvironments
      summary: List Environments
      description: List all environments for an application.
      tags:
      - Applications
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of environments
          content:
            application/json:
              schema:
                type: object
                properties:
                  environments:
                    type: array
                    items:
                      $ref: '#/components/schemas/Environment'
  /api/v2/org/{orgId}/envs:
    get:
      operationId: listEnvironmentsV2
      summary: List Environments V2
      description: Paginated list of environments for an organization (v2).
      tags:
      - Applications
      parameters:
      - name: orgId
        in: path
        required: true
        schema:
          type: string
      - name: pageToken
        in: query
        schema:
          type: string
      - name: pageSize
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: Paginated environments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEnvironments'
  /api/v1/app/{appId}/env/{envId}:
    post:
      operationId: updateEnvironment
      summary: Update Environment
      description: Update environment configuration.
      tags:
      - Applications
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      - name: envId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnvironmentUpdateRequest'
      responses:
        '200':
          description: Updated environment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Environment'
    delete:
      operationId: deleteEnvironment
      summary: Delete Environment
      description: Delete an application environment.
      tags:
      - Applications
      parameters:
      - name: appId
        in: path
        required: true
        schema:
          type: string
      - name: envId
        in: path
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Environment deleted
components:
  schemas:
    Environment:
      type: object
      properties:
        envId:
          type: string
        appId:
          type: string
        name:
          type: string
        autoTag:
          type: boolean
    PaginatedEnvironments:
      type: object
      properties:
        environments:
          type: array
          items:
            $ref: '#/components/schemas/Environment'
        nextPageToken:
          type: string
    Application:
      type: object
      properties:
        applicationId:
          type: string
        name:
          type: string
        description:
          type: string
        organizationId:
          type: string
    ApplicationUpdateRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
    NewApplicationRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        description:
          type: string
    NewEnvironmentRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
        autoTag:
          type: boolean
    PaginatedApplications:
      type: object
      properties:
        applications:
          type: array
          items:
            $ref: '#/components/schemas/Application'
        nextPageToken:
          type: string
    EnvironmentUpdateRequest:
      type: object
      properties:
        name:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained via /api/v1/auth/login