curl --request POST \
--url https://{host}/v1/projects/{projectId}/import \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"files": {},
"layers": [],
"excludedLayers": [],
"conflictStrategy": "merge",
"deleteUnmatched": false,
"importMode": "compatibility",
"bindingResolutions": {},
"authProfileMapping": {},
"portabilityOptions": {},
"conflictBaseFiles": {},
"conflictResolutions": {}
}
'{
"success": true,
"operationId": "imp_01JIMPORT123",
"status": "queued",
"statusUrl": "/v1/projects/proj_123/import/imp_01JIMPORT123"
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}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.
curl --request POST \
--url https://{host}/v1/projects/{projectId}/import \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"files": {},
"layers": [],
"excludedLayers": [],
"conflictStrategy": "merge",
"deleteUnmatched": false,
"importMode": "compatibility",
"bindingResolutions": {},
"authProfileMapping": {},
"portabilityOptions": {},
"conflictBaseFiles": {},
"conflictResolutions": {}
}
'{
"success": true,
"operationId": "imp_01JIMPORT123",
"status": "queued",
"statusUrl": "/v1/projects/proj_123/import/imp_01JIMPORT123"
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}{
"success": false,
"error": {
"code": "<string>",
"message": "<string>",
"stage": "<string>",
"layer": "core",
"path": "<string>",
"line": 2,
"details": {}
}
}Authorizations
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
Client-generated key used to safely retry operation creation.
1 - 128Path Parameters
Project identifier. The project must belong to the authenticated tenant.
1Body
Normalized relative archive paths mapped to UTF-8 file contents.
Show child attributes
Show child attributes
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.
core, connections, prompts, guardrails, workflows, evals, search, channels, vocabulary, tables 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.
core, connections, prompts, guardrails, workflows, evals, search, channels, vocabulary, tables 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.
replace, skip, merge Remove target content not represented by the imported content. Review preview deletes carefully.
Validation compatibility mode. compatibility preserves behavior for older archives and clients; strict applies the current import validation rules.
compatibility, strict Explicit target resolutions for ambiguous imported bindings.
Show child attributes
Show child attributes
Map exported auth-profile names to target profile IDs.
Show child attributes
Show child attributes
Optional target-environment adaptation settings, such as portable tool-binding repair, evaluation-reference normalization, or post-import validation.
Optional base files used for three-way merge conflict detection.
Show child attributes
Show child attributes
User-approved resolutions keyed by normalized archive path.
Show child attributes
Show child attributes
Response
Import accepted for asynchronous processing.
Indicates that the operation request was accepted for processing.
Stable identifier for polling this operation.
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.
queued, validating, staging, activating, packaging, processing, completed, failed, rolling_back, reverted Relative URL that can be polled for the operation status.
Was this page helpful?