> ## 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. # Reconcile File Migration Metadata > Last step of a migration document load. After Finalize File Migration (`finalizeCompanyFileMigration`), it attaches the file to its records, recreates its folders, and sets its document categories and display metadata. Read every placement result in the response, because one conflicted attachment does not stop the others. Reconciles display metadata and eligible owner placements after integrity-checked finalization. The revision must still be active, even when several generations share the same version ID. Provision categories idempotently, reusing case-insensitive existing definitions and their spelling, color and order. Recreate folder ancestry by stable source-folder identity scoped to the destination owner. File and placement fields change only while they still equal their last imported value; matching desired values are adopted without another write. Operator edits, deleted targets and remapped associations produce explicit conflicts. Equal source associations for one owner coalesce into one placement; incompatible metadata conflicts. Inspect every placement result: one blocked or conflicted attachment does not prevent unrelated valid attachments from completing. Available only while the destination company is in Sandbox mode. Forms are outside this contract. **Required permission:** `file.upload` Also requires `file.view` and `file.edit` and `file.configure-categories`. ## OpenAPI ````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/files/migrations/reconcile 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/migrations/reconcile: post: tags: - Company Files summary: Reconcile File Migration Metadata description: > Last step of a migration document load. After Finalize File Migration (`finalizeCompanyFileMigration`), it attaches the file to its records, recreates its folders, and sets its document categories and display metadata. Read every placement result in the response, because one conflicted attachment does not stop the others. Reconciles display metadata and eligible owner placements after integrity-checked finalization. The revision must still be active, even when several generations share the same version ID. Provision categories idempotently, reusing case-insensitive existing definitions and their spelling, color and order. Recreate folder ancestry by stable source-folder identity scoped to the destination owner. File and placement fields change only while they still equal their last imported value; matching desired values are adopted without another write. Operator edits, deleted targets and remapped associations produce explicit conflicts. Equal source associations for one owner coalesce into one placement; incompatible metadata conflicts. Inspect every placement result: one blocked or conflicted attachment does not prevent unrelated valid attachments from completing. Available only while the destination company is in Sandbox mode. Forms are outside this contract. **Required permission:** `file.upload` Also requires `file.view` and `file.edit` and `file.configure-categories`. operationId: reconcileCompanyFileMigration parameters: - $ref: '#/components/parameters/companyId' requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - source - revision - versionId - metadata - attachments properties: source: $ref: '#/components/schemas/CompanyFileMigrationSource' revision: $ref: '#/components/schemas/CompanyFileMigrationRevision' versionId: type: string format: uuid metadata: $ref: '#/components/schemas/CompanyFileMigrationMetadata' attachments: type: array maxItems: 100 items: $ref: '#/components/schemas/CompanyFileMigrationAttachment' examples: request: summary: Reconcile File Migration Metadata value: source: environment: https://legacy.example.com companyId: legacy-company-42 fileId: legacy-file-17 revision: bucket: legacy-company-files object: documents/loss-run.pdf generation: '1720000000000000' byteSize: 102400 contentType: application/pdf md5Hash: 1B2M2Y8AsgTpgAmY7PhCfg== versionId: 550e8400-e29b-41d4-a716-446655440021 metadata: displayName: Loss run.pdf displayDate: '2020-01-02T03:04:05.000Z' displayAuthor: Legacy adjuster originalFilename: loss-run.pdf attachments: - sourceAttachmentId: primary:legacy-file-17 entityType: company entityId: null category: Loss Runs sourceFolderId: null folders: [] responses: '200': description: Read-back metadata and a result for every requested attachment headers: Cache-Control: schema: type: string description: Always no-store because state can include upload capabilities. content: application/json: schema: $ref: '#/components/schemas/CompanyFileMigrationReconcileResult' examples: success: summary: Reconcile File Migration Metadata value: fileId: 550e8400-e29b-41d4-a716-446655440020 metadata: displayName: Loss run.pdf displayDate: '2020-01-02T03:04:05.000Z' displayAuthor: Legacy adjuster conflicts: [] placements: - sourceAttachmentId: primary:legacy-file-17 status: imported placementId: 550e8400-e29b-41d4-a716-446655440022 folderId: null category: Loss Runs conflicts: [] '400': description: Invalid migration declaration content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: failure: summary: Invalid migration declaration value: error: code: BadRequest message: Invalid migration declaration '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Source mapping not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: failure: summary: Source mapping not found value: error: code: NotFound message: Migration source was not found '409': description: Migration requires reconciliation content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: failure: summary: Migration requires reconciliation value: error: code: FileMigrationConflict message: destination_version_changed '500': $ref: '#/components/responses/InternalServerError' security: - BearerAuth: [] - ApiKeyAuth: [] components: parameters: companyId: name: companyId in: path required: true schema: type: string format: uuid description: Company identifier schemas: CompanyFileMigrationSource: type: object additionalProperties: false required: - environment - companyId - fileId properties: environment: type: string minLength: 1 maxLength: 512 description: >- Stable legacy environment identity, at most 512 UTF-8 bytes. Keep it unchanged across runs and credential rotations. companyId: type: string minLength: 1 maxLength: 255 description: Stable source identifier, at most 255 UTF-8 bytes. fileId: type: string minLength: 1 maxLength: 255 description: Stable source identifier, at most 255 UTF-8 bytes. CompanyFileMigrationRevision: description: >- Exact source object declaration. At least one base64 checksum from source object metadata is required. Every available common checksum must match destination storage before finalization. allOf: - type: object additionalProperties: false required: - bucket - object - generation - byteSize - contentType properties: bucket: type: string minLength: 1 maxLength: 255 object: type: string minLength: 1 maxLength: 2048 generation: type: string pattern: ^\d+$ maxLength: 40 description: >- Exact GCS source generation; pin every source read to this generation. byteSize: type: integer minimum: 1 maximum: 2147483648 contentType: type: string minLength: 1 maxLength: 255 description: Supported MIME type; normalized to lowercase. md5Hash: type: string pattern: ^[A-Za-z0-9+/]{22}==$ crc32c: type: string pattern: ^[A-Za-z0-9+/]{6}==$ - anyOf: - type: object required: - md5Hash properties: md5Hash: type: string pattern: ^[A-Za-z0-9+/]{22}==$ - type: object required: - crc32c properties: crc32c: type: string pattern: ^[A-Za-z0-9+/]{6}==$ CompanyFileMigrationMetadata: type: object additionalProperties: false required: - displayName - displayDate - displayAuthor - originalFilename properties: displayName: type: string minLength: 1 maxLength: 1024 description: Source display name; independent of the storage upload filename. displayDate: type: string format: date-time nullable: true description: >- Source attribution date. Stored at whole-second precision; null clears it. displayAuthor: type: string minLength: 1 maxLength: 255 nullable: true description: >- Source attribution label, trimmed. Audit actors remain the authenticated importer. originalFilename: type: string minLength: 1 maxLength: 1024 description: >- Validated upload filename for a newly created version. Does not replace the display name. CompanyFileMigrationAttachment: type: object additionalProperties: false required: - sourceAttachmentId - entityType - entityId - category - sourceFolderId - folders properties: sourceAttachmentId: type: string minLength: 1 maxLength: 255 description: Stable source identifier, at most 255 UTF-8 bytes. entityType: type: string enum: - company - event - exposure - quote - policy - submission - person - organization description: Canonical mapped destination owner type. entityId: type: string format: uuid nullable: true description: Live destination owner ID; null for company ownership. category: type: string maxLength: 255 nullable: true sourceFolderId: type: string minLength: 1 maxLength: 255 description: Source containing-folder identity, or null for the owner root. nullable: true folders: type: array maxItems: 256 description: >- Source folder records including every ancestor of sourceFolderId. Identity, not folder name, determines reuse. items: type: object additionalProperties: false required: - sourceFolderId - parentSourceFolderId - name - category properties: sourceFolderId: type: string minLength: 1 maxLength: 255 description: Stable source identifier, at most 255 UTF-8 bytes. parentSourceFolderId: type: string minLength: 1 maxLength: 255 description: Stable source identifier, at most 255 UTF-8 bytes. nullable: true name: type: string minLength: 1 maxLength: 1024 category: type: string maxLength: 255 nullable: true CompanyFileMigrationReconcileResult: type: object additionalProperties: false required: - fileId - metadata - conflicts - placements properties: fileId: type: string format: uuid metadata: $ref: '#/components/schemas/CompanyFileMigrationDisplayMetadata' conflicts: type: array items: type: string description: >- File display fields preserved because they differ from the last imported value. placements: type: array items: type: object additionalProperties: false required: - sourceAttachmentId - status - placementId - folderId - category - conflicts properties: sourceAttachmentId: type: string status: type: string enum: - imported - unchanged - conflict - blocked placementId: type: string format: uuid nullable: true folderId: type: string format: uuid nullable: true category: type: string maxLength: 255 nullable: true conflicts: type: array items: type: string description: >- Stable value-free reason codes or conflicted field names. Inspect each result even when HTTP status is 200. 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 code: type: string description: Stable problem code for this individual validation failure example: BLANK_LIST_ELEMENT reason: type: string description: Stable reason the value violates its canonical contract example: blank-list-element expected: type: string description: The expected canonical value contract example: nonblank trimmed string message: type: string description: Description of the field error example: Required field is missing CompanyFileMigrationDisplayMetadata: type: object additionalProperties: false required: - displayName - displayDate - displayAuthor properties: displayName: type: string minLength: 1 maxLength: 1024 description: Source display name; independent of the storage upload filename. displayDate: type: string format: date-time nullable: true description: >- Source attribution date. Stored at whole-second precision; null clears it. displayAuthor: type: string minLength: 1 maxLength: 255 nullable: true description: >- Source attribution label, trimmed. Audit actors remain the authenticated importer. 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 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. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0 access token (audience = the app API audience) as `Authorization: Bearer `. The request resolves to the user's identity and is authorized by their Role on the `{companyId}` in the path — the same role-based permissions the web app enforces. This is the path the MCP connector uses to act on a user's behalf; endpoints that accept it list both `BearerAuth` and `ApiKeyAuth`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.