Skip to main content
The create endpoint documented here imports a new project from a file produced by Export. Use it to reconstruct an exported definition as a new project, move a project between tenants, or create a copy for review. This create operation does not update an existing project or automatically apply Git commits to Orion.

​
Who Can Import

A tenant Admin or a Group Admin can use preview and create. Project ownership alone does not grant import permission. Import creates tenant-level Knowledge Base pages and binds existing catalog metrics.

​
What Must Already Exist

Import recreates supported project content, including exported Knowledge Base pages. The following dependencies must already exist:
  • Data sources: Every data source the file names must exist in the tenant with the same name and type. A missing one is an error and nothing is written. Connections and credentials are set up in Data Sources.
  • Groups: Matched by name. An unknown group is skipped with a warning. Access grants are applied only when the request sets include_access=true, so a file alone cannot share a project with a group.
  • Catalog metrics: Matched by ID first, then by name if the ID does not resolve to a non-deleted metric. An unresolved placement is skipped with a warning.
A file exported with run history is accepted, but the history is dropped with a warning. Export without history when the file is meant for import.

​
Preview First

The preview validates the file and reports what a create would do, without writing anything. It also lists the members of each group an access grant would apply to.
The response contains:
  • project_name: the name the new project would get
  • counts: how many items per section would be created
  • access_grants: each group in the file that exists in this tenant, with its members and their roles
  • unresolved_groups: groups in the file that do not exist in this tenant
  • warnings: anything skipped or ignored
An invalid file returns 422 with a detail.errors list. Each error has a code, a path into the document such as metrics[2].sources[0], and a message. Fix the file and preview again.

​
Create

A 201 response reports the new project_id, counts of what was created and skipped per section, and any warnings. Newly created items get fresh IDs; existing data sources, groups, and catalog metrics retain theirs. The importer maps references onto the new IDs. Imported Knowledge Base slugs can receive suffixes to avoid collisions with existing pages.

​
What the Validator Checks

Preview and create share document validation:
  • The document parses as TOML and each section has the required keys
  • Every data source named exists in this tenant, by name and type
  • Declared slug references resolve within the file: Workflow reference maps, notebook metric and Knowledge Base references, and page parents
  • Slugs are unique within each section, and the Knowledge Base tree has no cycles
  • Embedded Workflow TOML parses, and enabled Workflows supply a schedule string
Create performs additional work after validation. It rewrites Workflow references and validates the resulting bodies; a Workflow that fails this validation is skipped with a warning. Scheduling errors can also produce warnings and leave the next run unset. A successful preview is not a guarantee that every item will be created or run successfully. Inspect the create response’s skipped counts and warnings. Create strips Workflow vanity_url claims so the copy does not claim the original public URLs. Enabled schedules are preserved and next runs are computed during import.

​
Testing an Exported Project

Use a separate project to inspect an exported definition and record test results alongside the snapshot review. Changes captured by a scheduled export have already occurred in Orion. Testing or approving this copy does not gate those changes, and merging the PR does not deploy the copy.
1

Take the file from the pull request

Check out the branch under review, or download the changed file from the pull request.
2

Prepare the file and import it under a review name

Before importing, set schedule_enabled = false on exported metrics, notebooks, and Workflows so the review copy does not start scheduled runs. Review Workflow delivery destinations before any manual run. Create with name=<project> (review) and leave include_access off to avoid applying group grants from the file. Inspect import warnings and the new project’s access.
3

Run it

Open the review project in the app and run the changed metric or Workflow. Compare the result to the source system or to the current production project.
4

Record and clean up

Note the result on the pull request, approve or request changes, then delete the review project. Imported Knowledge Base pages are tenant-level records; review and clean up those copies separately if no longer needed.

​
Limits

  • The create endpoint in this guide always creates a new project. This guide does not configure updates to existing projects or Git-triggered reconciliation.
  • Import can create Knowledge Base pages, but does not create data sources, groups, users, or catalog metrics. Review existing dependencies and import warnings; this is not a complete tenant restore.
  • Run history in a file is not imported.

​
Next Steps

Export Orion Snapshots to Git (Beta)

The scheduled export and review procedure this page supports

Export a Project

Download the TOML file that import reads