> ## 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.

# Update File Placement (Move / Categorize per Entity)

> Updates ONE placement's organization — the folder it sits in (`folderId`)
and/or its free-text `category` label. Folder location and category are
per placement, so this is the way to re-folder or re-categorize a file
that is shared across several entities: address the placement to change
by its id (from
[List File Placements](#tag/Company-Files/GET/api/v1/companies/{companyId}/files/{fileId}/placements)
or the share response) — the file's other placements are untouched. The
owner-less
[Rename, Move, or Categorize File](#tag/Company-Files/PATCH/api/v1/companies/{companyId}/files/{fileId})
endpoint returns `409 Conflict` for these fields once a file is shared;
it also works on single-placement files, where either endpoint can be
used.

Send only the fields you want to change — at least one must be present.
Set `folderId` to a folder id to move the placement into that folder
(the folder must belong to the placement's owner), or to `null` for the
owner's top level. Set `category` to any non-blank string (max 255
characters; leading and trailing whitespace is trimmed) or to `null` to
clear it — categories are free-text, there is no configured list to
match against. `displayName` lives on the file itself (one name
everywhere) — rename it via the file PATCH.

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




## OpenAPI

````yaml /openapi/generated-external-api.yaml patch /api/v1/companies/{companyId}/files/{fileId}/placements/{placementId}
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}/files/{fileId}/placements/{placementId}:
    patch:
      tags:
        - Company Files
      summary: Update File Placement (Move / Categorize per Entity)
      description: >
        Updates ONE placement's organization — the folder it sits in
        (`folderId`)

        and/or its free-text `category` label. Folder location and category are

        per placement, so this is the way to re-folder or re-categorize a file

        that is shared across several entities: address the placement to change

        by its id (from

        [List File
        Placements](#tag/Company-Files/GET/api/v1/companies/{companyId}/files/{fileId}/placements)

        or the share response) — the file's other placements are untouched. The

        owner-less

        [Rename, Move, or Categorize
        File](#tag/Company-Files/PATCH/api/v1/companies/{companyId}/files/{fileId})

        endpoint returns `409 Conflict` for these fields once a file is shared;

        it also works on single-placement files, where either endpoint can be

        used.


        Send only the fields you want to change — at least one must be present.

        Set `folderId` to a folder id to move the placement into that folder

        (the folder must belong to the placement's owner), or to `null` for the

        owner's top level. Set `category` to any non-blank string (max 255

        characters; leading and trailing whitespace is trimmed) or to `null` to

        clear it — categories are free-text, there is no configured list to

        match against. `displayName` lives on the file itself (one name

        everywhere) — rename it via the file PATCH.


        **Required permission:** `company.file:update`
      operationId: updateCompanyFilePlacement
      parameters:
        - $ref: '#/components/parameters/companyId'
        - $ref: '#/components/parameters/fileId'
        - $ref: '#/components/parameters/placementId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                folderId:
                  type: string
                  format: uuid
                  nullable: true
                  description: >-
                    New folder id (must belong to the placement's owner), or
                    null for the owner's top level
                category:
                  type: string
                  nullable: true
                  maxLength: 255
                  description: >-
                    Free-text category label (max 255 characters), or null to
                    clear it
            examples:
              moveToFolder:
                summary: Move this placement into one of its owner's folders
                value:
                  folderId: 550e8400-e29b-41d4-a716-446655440001
              moveToTopLevel:
                summary: Move this placement to its owner's top level
                value:
                  folderId: null
              categorize:
                summary: Set this placement's category
                value:
                  category: Loss Runs
              clearCategory:
                summary: Clear this placement's category
                value:
                  category: null
      responses:
        '200':
          description: Placement updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  placementId:
                    type: string
                    format: uuid
                    description: Id of the updated placement
                  fileId:
                    type: string
                    format: uuid
                    description: The file the placement belongs to
                  entityType:
                    type: string
                    description: The placement owner's entity type
                  entityId:
                    type: string
                    format: uuid
                    nullable: true
                    description: >-
                      The placement owner's entity id (null for the company
                      level)
                  folderId:
                    type: string
                    format: uuid
                    nullable: true
                    description: The folder the placement now sits in
                  category:
                    type: string
                    nullable: true
                    description: The placement's category after the update
              examples:
                success:
                  summary: Placement moved and categorized
                  value:
                    placementId: 550e8400-e29b-41d4-a716-446655440032
                    fileId: 550e8400-e29b-41d4-a716-446655440020
                    entityType: submission
                    entityId: 550e8400-e29b-41d4-a716-446655440011
                    folderId: 550e8400-e29b-41d4-a716-446655440001
                    category: Loss Runs
        '400':
          description: Bad Request — Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                nothingToUpdate:
                  summary: No updatable field provided
                  value:
                    error:
                      code: BadRequest
                      message: 'Nothing to update: provide folderId and/or category'
                wrongOwnerFolder:
                  summary: Target folder belongs to a different owner
                  value:
                    error:
                      code: BadRequest
                      message: Folder does not belong to the file owner
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Placement not found (or not a placement of this file)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                notFound:
                  summary: Placement does not exist
                  value:
                    error:
                      code: NotFound
                      message: >-
                        File placement not found:
                        550e8400-e29b-41d4-a716-446655440032
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Company identifier
    fileId:
      name: fileId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: File identifier
    placementId:
      name: placementId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Placement identifier
  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
  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.
  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.

````