> ## Documentation Index
> Fetch the complete documentation index at: https://docs.go.aiinsurance.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Delete Folder

> Recursively soft-deletes a folder: the folder itself, every live
descendant folder, and every file placed inside the subtree. Deleted
items disappear from all listings and their stored objects are
reclaimed. The response reports how many folders and files the cascade
removed.

**Required permission:** `company.file:delete`




## OpenAPI

````yaml /openapi/generated-external-api.yaml delete /api/v1/companies/{companyId}/folders/{folderId}
openapi: 3.0.3
info:
  title: AI Insurance External API
  description: External API for AI Insurance platform
  version: 1.0.0
  contact:
    email: support@aiinsurance.io
servers:
  - url: https://go.aiinsurance.io
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/companies/{companyId}/folders/{folderId}:
    delete:
      tags:
        - Company Files
      summary: Delete Folder
      description: |
        Recursively soft-deletes a folder: the folder itself, every live
        descendant folder, and every file placed inside the subtree. Deleted
        items disappear from all listings and their stored objects are
        reclaimed. The response reports how many folders and files the cascade
        removed.

        **Required permission:** `company.file:delete`
      operationId: deleteFolder
      parameters:
        - $ref: '#/components/parameters/companyId'
        - $ref: '#/components/parameters/folderId'
      responses:
        '200':
          description: Folder deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Id of the deleted folder
                  deleted:
                    type: boolean
                    description: Always `true` on success
                  deletedFolders:
                    type: integer
                    description: >-
                      Live folders soft-deleted (the folder itself plus
                      descendants)
                  deletedFiles:
                    type: integer
                    description: >-
                      Live files soft-deleted because their placement was in the
                      subtree
              examples:
                success:
                  summary: Folder subtree deleted
                  value:
                    id: 550e8400-e29b-41d4-a716-446655440001
                    deleted: true
                    deletedFolders: 2
                    deletedFiles: 3
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Folder not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  summary: Folder does not exist
                  value:
                    error:
                      code: NotFound
                      message: 'Folder not found: 550e8400-e29b-41d4-a716-446655440001'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Company identifier
    folderId:
      name: folderId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Folder identifier
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingApiKey:
              summary: Missing API key
              value:
                error:
                  code: AuthenticationError
                  message: API key authentication required
                  userMessages:
                    - API key authentication required
            invalidApiKey:
              summary: >-
                Invalid API key (e.g. unknown key, or a Bearer token used
                instead of an API key)
              value:
                error:
                  code: AuthenticationError
                  message: Invalid API key
                  userMessages:
                    - Invalid API key
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            insufficientPermissions:
              summary: Insufficient permissions
              value:
                error:
                  code: AuthorizationError
                  message: User is not authorized to perform the requested action
                  userMessages:
                    - User is not authorized to perform the requested action
            companyMismatch:
              summary: A valid API key naming another company in the URL
              value:
                error:
                  code: AuthorizationError
                  message: API key is not scoped to the requested company
                  userMessages:
                    - API key is not scoped to the requested company
    InternalServerError:
      description: Internal Server Error - Unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internalError:
              summary: Unexpected server error
              value:
                error:
                  code: UncaughtActionError
                  message: Uncaught error occurred in <actionName>
                  userMessages:
                    - An unexpected error occurred. Please try again later.
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response for all external API endpoints
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: VALIDATION_ERROR
            message:
              type: string
              description: Human-readable error message
              example: 'submissionId: Required field is missing'
            userMessages:
              type: array
              description: >-
                Clean, verbatim-displayable messages — one entry per failure,
                free of error-code tags, field paths, and internal noise.
                Suitable for showing to end users as-is.
              items:
                type: string
              example:
                - Exposures of type 'company' require an address
            details:
              type: array
              description: Additional details for validation errors (field-level errors)
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: The field that caused the error
                    example: submissionId
                  message:
                    type: string
                    description: Description of the field error
                    example: Required field is missing
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key authentication. Send your raw API key as the `Authorization`
        header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do
        NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key`
        header; those are not accepted.

````