Multidoc - Xano Documentation

What is a Multidoc?

A multidoc is a single XanoScript document that captures one branch of a workspace — every table, API, function, task, agent, and other construct — separated by --- (triple-dash) delimiters. Think of it as a snapshot of a workspace branch in one file: like a database dump, but for your backend logic and schema. You don’t hand-author a multidoc — Xano generates it — but it’s the format you or your AI agents work with for version control, backups, and migrating or cloning a workspace. The CLI and Metadata API read and write it:

xano workspace pull downloads the workspace as a multidoc and splits it into individual .xs files on your filesystem.
xano workspace push reassembles your local .xs files into a multidoc and sends it to Xano.
The Metadata API exposes GET and POST endpoints at /workspace/{workspace_id}/multidoc for the same purpose — this is what the CLI calls under the hood.

This page is the complete reference for that format — written so an agent (or a human) working through the CLI or Metadata API knows exactly what a multidoc contains and how it’s applied, without needing any other context.

A multidoc captures a single branch. Pulling exports the live branch by default — pass a branch to target another. There is no “all branches” export, so back up each branch separately. By default a multidoc is published definitions only: table records, environment variables, and draft (unpublished) function versions are excluded unless you opt in (see Optional inclusions).

Structure

A multidoc is a sequence of XanoScript definitions separated by ---. Each section between separators is a standalone definition — a table, function, API endpoint, etc. — exactly as it would appear in its own .xs file. Here’s a minimal multidoc with three definitions:

A minimal multidoc (three definitions)

workspace "Loan Origination App" {
  preferences = {
    track_performance: true
    sql_columns      : true
  }
}
---
table loan_application {
  schema {
    int id
    int user_id {
      table = "user"
    }
    decimal amount
    text purpose
    enum status?=pending {
      values = ["pending", "approved", "rejected"]
    }
    timestamp created_at?=now
  }
}
---
query apply verb=POST {
  api_group = "Loan"
  auth = "user"

  input {
    decimal amount
    text purpose
  }

  stack {
    db.add loan_application {
      data = {
        user_id: $auth.id
        amount : $input.amount
        purpose: $input.purpose
        status : "pending"
      }
    } as $application
  }

  response = $application
}

The example above is trimmed for clarity. Below is a real, complete multidoc — the entire Loan Origination App workspace (3 tables, 2 API groups, and the full auth + loan flow) exported with xano workspace pull. You can load a multidoc like this into Xano in a few ways:

Create a new workspace from it (dashboard) — on the Workspaces page, open the ⋮ menu and choose Create Workspace (Multi-Doc), then paste the multidoc (or click Upload File) and click Create.
Apply it to an existing workspace (CLI) — assemble your .xs files and run xano workspace push.
Apply it to an existing workspace (Metadata API) — send the multidoc to POST /workspace/{id}/multidoc.

Full example: the Loan Origination App workspace as a single multidoc

Loan Origination App full workspace multidoc

workspace "Loan Origination App" {
  acceptance = {ai_terms: true}
  preferences = {
    internal_docs    : false
    track_performance: true
    sql_names        : false
    sql_columns      : true
  }
}
---
table user {
  auth = true

  schema {
    int id
    timestamp created_at?=now {
      visibility = "private"
    }
  
    text name filters=trim
    email? email filters=trim|lower
    password? password filters=min:8|minAlpha:1|minDigit:1
    enum role?=user {
      values = ["user", "admin"]
    }
  }

  index = [
    {type: "primary", field: [{name: "id"}]}
    {type: "btree", field: [{name: "created_at", op: "desc"}]}
    {type: "btree|unique", field: [{name: "email", op: "asc"}]}
    {type: "btree", field: [{name: "role"}]}
  ]

  guid = "0zDkg0JfwQkH9_AyPMmrsUAEqbg"
}
---
table loan {
  auth = false

  schema {
    int id
  
    // The application that originated this loan
    int application_id {
      table = "loan_application"
    }
  
    // The borrower
    int user_id {
      table = "user"
    }
  
    // The initial loan amount
    decimal amount
  
    // The current remaining balance
    decimal balance
  
    // The current status of the loan
    enum status?=active {
      values = ["active", "paid", "defaulted"]
    }
  
    timestamp created_at?=now
  }

  index = [
    {type: "primary", field: [{name: "id"}]}
    {type: "btree", field: [{name: "application_id"}]}
    {type: "btree", field: [{name: "user_id"}]}
    {type: "btree", field: [{name: "status"}]}
  ]

  guid = "GyMZM1p6PK7AmCHI-5T3QGnf160"
}
---
table loan_application {
  auth = false

  schema {
    int id
  
    // The user applying for the loan
    int user_id {
      table = "user"
    }
  
    // The requested loan amount
    decimal amount
  
    // The purpose of the loan
    text purpose
  
    // The current status of the application
    enum status?=pending {
      values = ["pending", "approved", "rejected"]
    }
  
    timestamp created_at?=now
  }

  index = [
    {type: "primary", field: [{name: "id"}]}
    {type: "btree", field: [{name: "user_id"}]}
    {type: "btree", field: [{name: "status"}]}
  ]

  guid = "g647JzT3IKgiZw8rJhrnL9d7Ajs"
}
---
api_group Authentication {
  canonical = "mIJgjWIF"
  guid = "cXyl6kSWyzgsUTihX5vdBLS1TH8"
}
---
// APIs for loan application and management
api_group Loan {
  canonical = "loan-origination"
  guid = "Tvz9LM_yM8Vlpisy3AOfKC7to4M"
}
---
// Update application status (Admin only)
// Approve or reject a loan application (Admin only)
query "admin/application/{application_id}" verb=PATCH {
  api_group = "Loan"
  auth = "user"

  input {
    int application_id {
      table = "loan_application"
    }
  
    enum status {
      values = ["approved", "rejected"]
    }
  }

  stack {
    // 1. Get current user profile to check role
    db.get user {
      field_name = "id"
      field_value = $auth.id
    } as $user
  
    // 2. Verify admin role
    precondition ($user.role == "admin") {
      error_type = "accessdenied"
      error = "Admin privileges required"
    }
  
    // 3. Get the application
    db.get loan_application {
      field_name = "id"
      field_value = $input.application_id
    } as $application
  
    precondition ($application != null) {
      error_type = "notfound"
      error = "Application not found"
    }
  
    precondition ($application.status == "pending") {
      error = "Application has already been processed"
    }
  
    // 4. Update status and create loan in a transaction
    db.transaction {
      stack {
        // Update application status
        db.edit loan_application {
          field_name = "id"
          field_value = $input.application_id
          data = {status: $input.status}
        } as $updated_application
      
        // If approved, create the loan
        conditional {
          if ($input.status == "approved") {
            db.add loan {
              data = {
                application_id: $application.id
                user_id       : $application.user_id
                amount        : $application.amount
                balance       : $application.amount
                status        : "active"
              }
            } as $new_loan
          }
        }
      }
    }
  }

  response = {
    message       : "Application "|concat:$input.status
    application_id: $input.application_id
  }

  guid = "DdHvEGUKVQfwC-h9tPiggfMZGVE"
}
---
// List all applications (Admin only)
// List all loan applications (Admin only)
query "admin/applications" verb=GET {
  api_group = "Loan"
  auth = "user"

  input {
    int page?=1
    int per_page?=20
    enum status? {
      values = ["pending", "approved", "rejected"]
    }
  }

  stack {
    // 1. Get current user profile to check role
    db.get user {
      field_name = "id"
      field_value = $auth.id
    } as $user
  
    // 2. Verify admin role
    precondition ($user.role == "admin") {
      error_type = "accessdenied"
      error = "Admin privileges required"
    }
  
    // 3. Query all applications
    db.query loan_application {
      where = $db.loan_application.status ==? $input.status
      sort = {created_at: "desc"}
      return = {
        type  : "list"
        paging: {page: $input.page, per_page: $input.per_page}
      }
    } as $applications
  }

  response = $applications
  guid = "zfkPgd8FET1-te_Q8itQsSzAuIY"
}
---
// Create a new loan application
// Submit a new loan application
query apply verb=POST {
  api_group = "Loan"
  auth = "user"

  input {
    // The requested loan amount
    decimal amount
  
    // The purpose of the loan
    text purpose
  }

  stack {
    // Add the application to the database
    db.add loan_application {
      data = {
        user_id: $auth.id
        amount : $input.amount
        purpose: $input.purpose
        status : "pending"
      }
    } as $application
  }

  response = $application
  guid = "_IbZxk9A1rnaI0adELHOto3l8N0"
}
---
// Login and retrieve an authentication token
query "auth/login" verb=POST {
  api_group = "Authentication"

  input {
    email email? filters=trim|lower
    text password?
  }

  stack {
    db.get user {
      field_name = "email"
      field_value = $input.email
      output = ["id", "created_at", "name", "email", "password"]
    } as $user
  
    precondition ($user != null) {
      error_type = "accessdenied"
      error = "Invalid Credentials."
    }
  
    security.check_password {
      text_password = $input.password
      hash_password = $user.password
    } as $pass_result
  
    precondition ($pass_result) {
      error_type = "accessdenied"
      error = "Invalid Credentials."
    }
  
    security.create_auth_token {
      table = "user"
      extras = {}
      expiration = 86400
      id = $user.id
    } as $authToken
  }

  response = {authToken: $authToken}
  guid = "wiLiUSYLcPkhUCY1xDYlEpKGDIE"
}
---
// Get the user record belonging to the authentication token
query "auth/me" verb=GET {
  api_group = "Authentication"
  auth = "user"

  input {
  }

  stack {
    db.get user {
      field_name = "id"
      field_value = $auth.id
      output = ["id", "created_at", "name", "email"]
    } as $user
  }

  response = $user
  guid = "Q7UKZk3KmMLn7R903IPVWaYc2BI"
}
---
// Signup and retrieve an authentication token
query "auth/signup" verb=POST {
  api_group = "Authentication"

  input {
    text name?
    email email? filters=trim|lower
    text password?
  }

  stack {
    db.get user {
      field_name = "email"
      field_value = $input.email
    } as $user
  
    precondition ($user == null) {
      error_type = "accessdenied"
      error = "This account is already in use."
    }
  
    db.add user {
      enforce_hidden_fields = false
      data = {
        created_at: "now"
        name      : $input.name
        email     : $input.email
        password  : $input.password
      }
    } as $user
  
    security.create_auth_token {
      table = "user"
      extras = {}
      expiration = 86400
      id = $user.id
    } as $authToken
  }

  response = {authToken: $authToken}
  guid = "5_4yZbXcseUitQREfwiFIhv6bcA"
}
---
// List applications for the authenticated user
// List all applications for the current user
query my_applications verb=GET {
  api_group = "Loan"
  auth = "user"

  input {
    int page?=1
    int per_page?=20
  }

  stack {
    // Query the loan_application table for the current user
    db.query loan_application {
      where = $db.loan_application.user_id == $auth.id
      sort = {created_at: "desc"}
      return = {
        type  : "list"
        paging: {page: $input.page, per_page: $input.per_page}
      }
    } as $applications
  }

  response = $applications
  guid = "Rw6xcu6c0nh7iVglzD0l4e-crEo"
}
---
// List active loans for the authenticated user
// List all active loans for the current user
query my_loans verb=GET {
  api_group = "Loan"
  auth = "user"

  input {
    int page?=1
    int per_page?=20
  }

  stack {
    // Query the loan table for the current user
    db.query loan {
      where = $db.loan.user_id == $auth.id
      sort = {created_at: "desc"}
      return = {
        type  : "list"
        paging: {page: $input.page, per_page: $input.per_page}
      }
    } as $loans
  }

  response = $loans
  guid = "Tfrfukm3jbEJkE_9AeHlsMI5UzE"
}

Key rules

Each definition is separated by exactly --- on its own line
Every .xs file contributes one definition to the multidoc
Definitions can appear in any order, though the CLI sorts them alphabetically by file path when assembling a push
The CLI’s default push is partial — only changed definitions are sent. Use --sync for a full push of every definition, and --sync --delete to also remove remote objects that are no longer present locally
Each definition must be a valid, standalone XanoScript primitive

What’s Included

A multidoc can contain every type of XanoScript construct in your workspace. Here’s the full list:

Construct	Keyword	Description
Workspace Settings	`workspace`	Environment variables, preferences, and configuration
Branch Config	`branch`	Branch color, description, middleware, history retention
Database Tables	`table`	Schema definitions with fields, indexes, and views
API Groups	`api_group`	API group settings (canonical URL, swagger, tags)
API Endpoints	`query`	HTTP endpoints with inputs, logic stacks, and responses
Custom Functions	`function`	Reusable logic blocks
Background Tasks	`task`	Scheduled and cron jobs
Triggers	`table_trigger`, `realtime_trigger`, `workspace_trigger`, `agent_trigger`, `mcp_server_trigger`	Event-driven handlers
Middleware	`middleware`	Request/response interceptors
Addons	`addon`	Reusable subqueries for fetching related data
AI Agents	`agent`	AI agent configuration
AI Tools	`tool`	Tools for agents and MCP servers
MCP Servers	`mcp_server`	MCP server definitions
Tests	`test` (embedded)	Unit tests, defined inline within their parent construct

Optional inclusions

A few additional data types can be included via flags:

Data	CLI Flag	API Parameter	Description
Environment variables	`--env`	`env=true`	Custom `$env.*` values defined in workspace settings
Table records	`--records`	`records=true`	Actual data rows stored in each table
Draft function versions	`--draft` (pull only)	`include_draft=true`	Unpublished draft versions of functions

These are excluded by default since they contain runtime data rather than workspace definitions.

How the CLI Uses Multidoc

The CLI is the primary interface for working with multidoc. Understanding how it transforms between multidoc and individual files helps when troubleshooting push/pull issues.

Pull: Multidoc to files

When you run xano workspace pull, the CLI:

Calls GET /workspace/{workspace_id}/multidoc on the Metadata API
Receives a single multidoc response
Splits it on --- boundaries
Writes each definition to its own .xs file, organized by type into the directory structure

Push: Files to multidoc

When you run xano workspace push, the CLI:

Recursively collects all .xs files from the target directory
Sorts them alphabetically by file path
Joins them with --- separators into a single multidoc
Sends it to POST /workspace/{workspace_id}/multidoc with content type text/x-xanoscript

The order of definitions within the multidoc doesn’t matter to Xano — the server resolves dependencies regardless of order. The CLI sorts alphabetically for consistency and readable diffs.

Importing and overwrite behavior

Multidocs are how you (or an agent) back up, restore, clone, and migrate a workspace — so it matters where you send one and what it overwrites:

Import as a new workspace (dashboard) — on the Workspaces page, the ⋮ menu → Create Workspace (Multi-Doc) builds a brand-new workspace from the multidoc. Nothing is overwritten — the safest path for restoring a backup elsewhere, cloning, or migrating between instances.
Push into an existing workspace — Xano matches each definition to existing objects by its guid: matches are updated in place (overwritten) and new definitions are created. Objects already in the workspace but absent from the multidoc are left untouched — unless you use --sync --delete (delete=true), which removes them so the workspace matches the multidoc exactly. That delete is destructive.
Records are only written with --records/records=true. By default rows are added on top of existing data (which can duplicate); add --truncate/truncate=true to empty each table first so the import replaces it.
Pushes run inside a database transaction by default (transaction=true), so a failed import rolls back instead of leaving the workspace half-applied.

Goal	How
Restore or clone to a fresh workspace	Dashboard → Create Workspace (Multi-Doc)
Update an existing workspace, keep anything not in the doc	`xano workspace push` (default partial)
Make a workspace exactly match the multidoc	`xano workspace push --sync --delete`
Replace table data too	add `--records --truncate`

Every definition carries a guid (visible in the example above). That GUID is how Xano decides whether a push updates an existing object or creates a new one — which is why importing the same multidoc twice updates in place instead of duplicating. Identity lives inside each document — there is no external mapping file, and the object’s file path is irrelevant to matching. Push the same definitions from a different folder layout and they still bind to the same objects.

Metadata API Endpoints

The Metadata API provides direct access to the multidoc format for programmatic workflows, CI/CD pipelines, or custom tooling.

Retrieve a multidoc

GET /workspace/{workspace_id}/multidoc

Parameter	Type	In	Required	Default	Description
`workspace_id`	integer	path	Yes	—	Workspace ID
`branch`	string	query	No	Live branch	Branch to retrieve
`env`	boolean	query	No	`false`	Include environment variables
`records`	boolean	query	No	`false`	Include table records
`include_draft`	boolean	query	No	`false`	Include draft (unpublished) versions of functions

Response: The selected branch as a text/x-xanoscript multidoc.

Push a multidoc

POST /workspace/{workspace_id}/multidoc

Parameter	Type	In	Required	Default	Description
`workspace_id`	integer	path	Yes	—	Workspace ID
`branch`	string	query	No	Live branch	Branch to push to
`partial`	boolean	query	No	`false`	Apply only the supplied definitions instead of a full replace (the CLI’s default push mode)
`delete`	boolean	query	No	`false`	Remove remote objects not present in the multidoc (full sync)
`env`	boolean	query	No	`false`	Include environment variables
`records`	boolean	query	No	`false`	Include table records
`truncate`	boolean	query	No	`false`	Truncate tables before importing records
`as_draft`	boolean	query	No	`false`	Import functions as draft versions instead of publishing
`transaction`	boolean	query	No	`true`	Wrap the import in a database transaction
`force`	boolean	query	No	`false`	Skip server-side safety checks (for CI/CD)

Request body: Content type text/x-xanoscript — the full multidoc as a string.

To preview a push without applying it, send the same request to POST /workspace/{workspace_id}/multidoc/dry-run. This is what backs the CLI’s --dry-run flag.

Both endpoints require authentication via a Bearer token with appropriate workspace permissions. The same format powers several adjacent operations:

Endpoint	Purpose
`GET` / `POST /sandbox/multidoc`	Export / import the sandbox tenant
`POST /workspace/{workspace_id}/release/multidoc`	Create a release from a multidoc
`GET /workspace/{workspace_id}/release/{release_id}/multidoc`	Export an existing release as a multidoc
`GET /workspace/{workspace_id}/tenant/{tenant_name}/multidoc`	Export a specific tenant’s workspace

When you’ll work with multidoc

Whether you’re an AI agent operating through the CLI/Metadata API or a human reviewing a diff, multidoc is the format under the hood:

Version control — A pulled workspace is a tree of .xs files (one definition each) that reassemble into a multidoc on push, so changes diff and review like any other code.
Backup & restore — Export a branch to a multidoc, then re-import it as a new workspace or push it back to restore. See Importing and overwrite behavior.
Migration & cloning — Move a workspace between branches or instances by exporting one multidoc and importing it elsewhere.
CI/CD pipelines — Automated deployments send and receive multidoc payloads directly against the Metadata API.
Debugging push failures — Knowing the CLI assembles your .xs files into one multidoc helps you isolate which definition broke a push.
Custom tooling — If you’re building tools that interact with Xano programmatically, the multidoc endpoints are the transport layer for reading and writing workspace definitions.

​What is a Multidoc?

​Structure

​Key rules

​What’s Included

​Optional inclusions

​How the CLI Uses Multidoc

​Pull: Multidoc to files

​Push: Files to multidoc

​Importing and overwrite behavior

​Metadata API Endpoints

​Retrieve a multidoc

​Push a multidoc

​Related multidoc endpoints

​When you’ll work with multidoc

What is a Multidoc?

Structure

Key rules

What’s Included

Optional inclusions

How the CLI Uses Multidoc

Pull: Multidoc to files

Push: Files to multidoc

Importing and overwrite behavior

Metadata API Endpoints

Retrieve a multidoc

Push a multidoc

Related multidoc endpoints

When you’ll work with multidoc