Prerequisites
- A project-bound Platform Key. Send it in the
x-api-keyheader. - The
project_io.readscope on the key for export operations and theproject_io.writescope for import operations. A pipeline that promotes changes normally needs both. - The ID of a project that belongs to your tenant.
Workflow and use cases
To move a project between workspaces, export it from the source project and import the content into the target project:- Start an export of the source project. Save the
operationIdfrom the response. - Poll the export status until it is
completed. Download the archive fromdownloadUrlbeforeexpiresAt. - Start an import into the target project with the content in
files. Set the layers and conflict strategy you need. - Poll the import status until it is
completed. Checkwarnings,errors, and theappliedcounts.
List of endpoints
Behavior to know
- The start endpoints return
202with anoperationId, astatus, and astatusUrl. Poll the status endpoint until the operation reaches a final state:completed,failed, orreverted. - A successful status request does not mean the operation succeeded. Check
data.statusanddata.errors. - Warnings are informational and do not block completion. Errors are blocking.
- An import validates dependencies before it changes anything. Blocking validation errors stop staging and activation. If activation fails partway, the import rolls back.
- By default, an import merges matching content and deletes nothing. Use
conflictStrategyanddeleteUnmatchedto change this. - Both operations work on layers:
core,connections,prompts,guardrails,workflows,evals,search,channels,vocabulary, andtables. An export always includescore. An import detects layers from the content unless you setlayersorexcludedLayers. - Starting an import while another import runs returns
409. Send anIdempotency-Keyheader on start requests so a retry is safe. - Exports do not include environment credentials.