> ## Documentation Index > Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Project import API > Starts an asynchronous import. The server runs the Builder-equivalent preview and dependency validation before applying any mutation. Blocking validation errors prevent staging and activation. ## OpenAPI ````yaml agent-platform/api-specs/project-import-export.yaml post /v1/projects/{projectId}/import openapi: 3.1.0 info: title: Project Import / Export API version: 1.0.0 summary: >- Project-scoped APIs for importing and exporting platform project configuration. description: | Starts asynchronous project import and export operations and exposes their status. The operations use the same dependency discovery, validation, staging, activation, and rollback flow as the Studio Builder experience. Warnings are informational and do not block completion. Errors are blocking, are preserved on the operation, and must be propagated to the caller. servers: - url: https://{host} description: Replace with your base URL of the platform. security: - apiKey: [] tags: - name: Project Import description: Import project configuration into an existing project. - name: Project Export description: Export project configuration as a portable archive. paths: /v1/projects/{projectId}/import: post: tags: - Project Import summary: Start a project import description: | Starts an asynchronous import. The server runs the Builder-equivalent preview and dependency validation before applying any mutation. Blocking validation errors prevent staging and activation. operationId: createProjectImport parameters: - $ref: '#/components/parameters/ProjectId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImportRequest' responses: '202': description: Import accepted for asynchronous processing. content: application/json: schema: $ref: '#/components/schemas/OperationAcceptedResponse' example: success: true operationId: imp_01JIMPORT123 status: queued statusUrl: /v1/projects/proj_123/import/imp_01JIMPORT123 '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: Idempotency conflict or another import is already running. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '413': $ref: '#/components/responses/PayloadTooLarge' components: parameters: ProjectId: name: projectId in: path required: true description: Project identifier. The project must belong to the authenticated tenant. schema: type: string minLength: 1 IdempotencyKey: name: Idempotency-Key in: header required: false description: Client-generated key used to safely retry operation creation. schema: type: string minLength: 1 maxLength: 128 schemas: ImportRequest: type: object required: - files additionalProperties: false properties: files: type: object description: Normalized relative archive paths mapped to UTF-8 file contents. minProperties: 1 additionalProperties: type: string layers: type: array description: >- Optional allowlist of project layers to import. If omitted, layers are detected from the bundle. Values are core, connections, prompts, guardrails, workflows, evals, search, channels, vocabulary, or tables. Required dependencies must also be present or the import fails validation. uniqueItems: true items: $ref: '#/components/schemas/LayerName' excludedLayers: type: array description: >- Optional list of detected layers to skip. Values are core, connections, prompts, guardrails, workflows, evals, search, channels, vocabulary, or tables. Excluding a referenced dependency can produce a blocking import error. uniqueItems: true items: $ref: '#/components/schemas/LayerName' conflictStrategy: type: string description: >- Conflict behavior for records that already exist in the target project. replace overwrites matching content, skip preserves the target record, and merge upserts or merges matching content. enum: - replace - skip - merge default: merge deleteUnmatched: type: boolean default: false description: >- Remove target content not represented by the imported content. Review preview deletes carefully. importMode: type: string description: >- Validation compatibility mode. compatibility preserves behavior for older archives and clients; strict applies the current import validation rules. enum: - compatibility - strict default: compatibility bindingResolutions: type: object description: Explicit target resolutions for ambiguous imported bindings. additionalProperties: type: object additionalProperties: true authProfileMapping: type: object description: Map exported auth-profile names to target profile IDs. additionalProperties: type: string portabilityOptions: type: object description: >- Optional target-environment adaptation settings, such as portable tool-binding repair, evaluation-reference normalization, or post-import validation. additionalProperties: true conflictBaseFiles: type: object description: Optional base files used for three-way merge conflict detection. additionalProperties: type: string conflictResolutions: type: object description: User-approved resolutions keyed by normalized archive path. additionalProperties: type: string OperationAcceptedResponse: type: object required: - success - operationId - status - statusUrl properties: success: type: boolean const: true description: Indicates that the operation request was accepted for processing. operationId: type: string description: Stable identifier for polling this operation. status: $ref: '#/components/schemas/OperationStatus' statusUrl: type: string format: uri-reference description: Relative URL that can be polled for the operation status. ErrorResponse: type: object required: - success - error properties: success: type: boolean const: false error: $ref: '#/components/schemas/Diagnostic' LayerName: type: string description: >- Project configuration layer. core=agents/tools/core metadata; connections=connectors; prompts=prompt bundles; guardrails=guardrail policies; workflows=workflows; evals=evaluation data; search=SearchAI configuration; channels=channel definitions; vocabulary=domain vocabulary; tables=Agent Tables definitions. enum: - core - connections - prompts - guardrails - workflows - evals - search - channels - vocabulary - tables OperationStatus: type: string description: >- Current asynchronous operation state. queued=accepted and waiting; validating=checking input and dependencies; staging=writing staged records; activating=making staged records active; packaging=assembling the export artifact; processing=worker is executing the operation; completed=finished successfully; failed=finished with an error; rolling_back=import is undoing partial activation; reverted=import completed with changes reverted. enum: - queued - validating - staging - activating - packaging - processing - completed - failed - rolling_back - reverted Diagnostic: type: object required: - code - message properties: code: type: string description: Stable machine-readable diagnostic code. message: type: string description: Human-readable explanation of the diagnostic. stage: type: string description: >- Processing stage that produced the diagnostic, such as request, validation, staging, activation, or packaging. layer: $ref: '#/components/schemas/LayerName' path: type: string description: Archive file path associated with the diagnostic, when available. line: type: integer minimum: 1 description: >- One-based source line associated with a syntax diagnostic, when available. details: type: object description: >- Additional structured diagnostic context. Contents depend on the diagnostic code. additionalProperties: true responses: BadRequest: description: Invalid request, archive, layer selection, or operation parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: Authentication required or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: Authenticated principal lacks the required project scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: >- Project or operation was not found in the authenticated tenant/project scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' PayloadTooLarge: description: Request exceeds the public import payload or file limits. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: | Project-bound Platform Key supplied in the x-api-key header. The key must include the operation's required scope: project_io.read for export operations or project_io.write for import operations. A pipeline that promotes changes normally requires both scopes. ````