Skip to main content
POST
Start a project import
Back to the Project API overview Use this endpoint to start an asynchronous import of project content into an existing project. The server runs the same preview and dependency validation as Studio before it changes anything. Blocking validation errors stop staging and activation. If activation fails partway, the import rolls back. The response returns an operationId and a statusUrl. Poll Get project import status until the import is completed. The request needs the project_io.write scope. Send the content in files, a map of relative archive paths to UTF-8 file contents. By default, the import detects layers from the content, merges matching records, and deletes nothing. Use layers and excludedLayers to choose layers. Use conflictStrategy (replace, skip, or merge) to resolve conflicts. Use deleteUnmatched to remove target content that the import does not contain. Starting an import while another import runs returns 409. Send an Idempotency-Key header so a retry is safe.

Authorizations

x-api-key
string
header
required

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.

Headers

Idempotency-Key
string

Client-generated key used to safely retry operation creation.

Required string length: 1 - 128

Path Parameters

projectId
string
required

Project identifier. The project must belong to the authenticated tenant.

Minimum string length: 1

Body

application/json
files
object
required

Normalized relative archive paths mapped to UTF-8 file contents.

layers
enum<string>[]

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.

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.

Available options:
core,
connections,
prompts,
guardrails,
workflows,
evals,
search,
channels,
vocabulary,
tables
excludedLayers
enum<string>[]

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.

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.

Available options:
core,
connections,
prompts,
guardrails,
workflows,
evals,
search,
channels,
vocabulary,
tables
conflictStrategy
enum<string>
default:merge

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.

Available options:
replace,
skip,
merge
deleteUnmatched
boolean
default:false

Remove target content not represented by the imported content. Review preview deletes carefully.

importMode
enum<string>
default:compatibility

Validation compatibility mode. compatibility preserves behavior for older archives and clients; strict applies the current import validation rules.

Available options:
compatibility,
strict
bindingResolutions
object

Explicit target resolutions for ambiguous imported bindings.

authProfileMapping
object

Map exported auth-profile names to target profile IDs.

portabilityOptions
object

Optional target-environment adaptation settings, such as portable tool-binding repair, evaluation-reference normalization, or post-import validation.

conflictBaseFiles
object

Optional base files used for three-way merge conflict detection.

conflictResolutions
object

User-approved resolutions keyed by normalized archive path.

Response

Import accepted for asynchronous processing.

success
boolean
required

Indicates that the operation request was accepted for processing.

operationId
string
required

Stable identifier for polling this operation.

status
enum<string>
required

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.

Available options:
queued,
validating,
staging,
activating,
packaging,
processing,
completed,
failed,
rolling_back,
reverted
statusUrl
string<uri-reference>
required

Relative URL that can be polled for the operation status.