@malloydata/db-publisher 0.0.381 → 0.0.382

package/publisher-api-doc.yaml

@@ -38,11 +38,14 @@ tags:
   - name: publisher
     description: Publisher status and health check operations
   - name: projects
-    description: Project lifecycle management including creation, configuration, and deletion of data modeling projects
+    description: Project lifecycle management including creation, configuration, and
+      deletion of data modeling projects
   - name: connections
-    description: Database connection management for secure data source configuration and access
+    description: Database connection management for secure data source configuration
+      and access
   - name: packages
-    description: Package management for Malloy data models, including versioning and distribution
+    description: Package management for Malloy data models, including versioning and
+      distribution
   - name: models
     description: Malloy model access and compilation operations
   - name: notebooks
@@ -51,6 +54,10 @@ tags:
     description: Embedded database management and access
   - name: watch-mode
     description: Real-time file watching for development workflows
+  - name: materializations
+    description: Package-level materializations for persisting Malloy sources
+  - name: manifests
+    description: Build manifest management for tracking materialized source tables
 
 paths:
   /status:
@@ -70,6 +77,8 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ServerStatus"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects:
     get:
@@ -94,6 +103,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
     post:
       tags:
         - projects
@@ -120,6 +131,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}:
     get:
@@ -157,6 +170,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
     patch:
       tags:
         - projects
@@ -190,6 +205,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
     delete:
       tags:
         - projects
@@ -219,6 +236,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/connections:
     get:
@@ -250,6 +269,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/connections/{connectionName}:
     get:
@@ -287,6 +308,164 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+    post:
+      tags:
+        - connections
+      operationId: create-connection
+      summary: Create a new database connection
+      description: |
+        Creates a new database connection in the specified project.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: connectionName
+          in: path
+          description: Name of the connection
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/Connection"
+      responses:
+        "201":
+          description: Connection created successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: Connection already exists
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  error:
+                    type: string
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+    patch:
+      tags:
+        - connections
+      operationId: update-connection
+      summary: Update an existing database connection
+      description: |
+        Updates the configuration of an existing database connection.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: connectionName
+          in: path
+          description: Name of the connection to update
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                postgresConnection:
+                  $ref: "#/components/schemas/PostgresConnection"
+                mysqlConnection:
+                  $ref: "#/components/schemas/MysqlConnection"
+                bigqueryConnection:
+                  $ref: "#/components/schemas/BigqueryConnection"
+                snowflakeConnection:
+                  $ref: "#/components/schemas/SnowflakeConnection"
+                duckdbConnection:
+                  $ref: "#/components/schemas/DuckdbConnection"
+                motherduckConnection:
+                  $ref: "#/components/schemas/MotherDuckConnection"
+                trinoConnection:
+                  $ref: "#/components/schemas/TrinoConnection"
+                ducklakeConnection:
+                  $ref: "#/components/schemas/DucklakeConnection"
+      responses:
+        "200":
+          description: Connection updated successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+    delete:
+      tags:
+        - connections
+      operationId: delete-connection
+      summary: Delete a database connection
+      description: |
+        Permanently deletes a database connection from the project.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: connectionName
+          in: path
+          description: Name of the connection to delete
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+      responses:
+        "200":
+          description: Connection deleted successfully
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  message:
+                    type: string
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/connections/{connectionName}/schemas:
     get:
@@ -326,6 +505,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/connections/{connectionName}/schemas/{schemaName}/tables:
     get:
@@ -356,6 +537,16 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - name: tableNames
+          in: query
+          description: |
+            List of table names to filter results. When provided, only returns metadata
+            for the specified tables. When omitted, returns all tables in the schema.
+          required: false
+          schema:
+            type: array
+            items:
+              type: string
       responses:
         "200":
           description: A list of table names available in the specified schema
@@ -371,6 +562,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/connections/{connectionName}/schemas/{schemaName}/tables/{tablePath}:
     get:
@@ -421,6 +614,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   # TODO: Remove this endpoint.
   /projects/{projectName}/connections/{connectionName}/sqlSource:
@@ -468,6 +663,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
     post:
       tags:
@@ -513,6 +710,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/connections/{connectionName}/sqlQuery:
     post:
@@ -536,12 +735,6 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
-        - name: options
-          in: query
-          description: Options
-          required: false
-          schema:
-            type: string
       requestBody:
         description: SQL statement to execute
         required: true
@@ -552,6 +745,9 @@ paths:
               properties:
                 sqlStatement:
                   type: string
+                options:
+                  type: string
+                  description: Options
       responses:
         "200":
           description: Query execution results
@@ -565,6 +761,9 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
   /projects/{projectName}/connections/{connectionName}/sqlTemporaryTable:
     post:
       tags:
@@ -610,6 +809,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   # TODO: Remove this endpoint.
   /projects/{projectName}/connections/{connectionName}/temporaryTable:
@@ -657,57 +858,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
-
-  # TODO: Remove this endpoint. This is deprecated and replaced by /projects/{projectName}/connections/{connectionName}/table resource.
-  /projects/{projectName}/connections/{connectionName}/tableSource:
-    get:
-      tags:
-        - connections
-      operationId: get-tablesource
-      summary: Get table source information
-      deprecated: true
-      description: |
-        Retrieves information about a specific table or view from the database connection.
-        This includes table schema, column definitions, and metadata. The table can be specified
-        by either tableKey or tablePath parameters, depending on the database type.
-      parameters:
-        - name: projectName
-          in: path
-          description: Name of the project
-          required: true
-          schema:
-            $ref: "#/components/schemas/IdentifierPattern"
-        - name: connectionName
-          in: path
-          description: Name of the connection
-          required: true
-          schema:
-            $ref: "#/components/schemas/IdentifierPattern"
-        - name: tableKey
-          in: query
-          description: Table key
-          required: false
-          schema:
-            type: string
-        - name: tablePath
-          in: query
-          description: Table path
-          required: false
-          schema:
-            type: string
-      responses:
-        "200":
-          description: Table source information
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/TableSource"
-        "401":
-          $ref: "#/components/responses/Unauthorized"
-        "404":
-          $ref: "#/components/responses/NotFound"
-        "500":
-          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   # TODO: Remove this endpoint.
   /projects/{projectName}/connections/{connectionName}/queryData:
@@ -794,6 +946,8 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
     post:
       tags:
         - packages
@@ -810,6 +964,16 @@ paths:
           required: true
           schema:
             $ref: "#/components/schemas/IdentifierPattern"
+        - name: autoLoadManifest
+          in: query
+          description: |
+            When true, automatically loads any existing build manifest
+            for the package so materialized table references resolve immediately.
+            Defaults to false.
+          required: false
+          schema:
+            type: boolean
+            default: false
       requestBody:
         required: true
         content:
@@ -829,6 +993,8 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/packages/{packageName}:
     get:
@@ -881,6 +1047,8 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
     patch:
       tags:
         - packages
@@ -924,6 +1092,8 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
     delete:
       tags:
         - packages
@@ -961,6 +1131,8 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/packages/{packageName}/models:
     get:
@@ -1008,6 +1180,8 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/packages/{packageName}/models/{path}:
     get:
@@ -1115,6 +1289,62 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /projects/{projectName}/packages/{packageName}/models/{path}/compile:
+    post:
+      tags:
+        - models
+      operationId: compile-model-source
+      summary: Compile Malloy source code
+      description: |
+        Compiles Malloy source code in the context of a specific model file.
+        The submitted source is appended to the full model content, giving it
+        access to all sources, imports, and queries defined in the model.
+        Relative imports resolve correctly against sibling model files.
+        Returns compilation status and any problems (errors or warnings) found.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            type: string
+        - name: path
+          in: path
+          description: Path to the model within the package (used to resolve relative
+            imports)
+          required: true
+          schema:
+            $ref: "#/components/schemas/PathPattern"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CompileRequest"
+      responses:
+        "200":
+          description: Compilation result with status and any problems
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CompileResult"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /projects/{projectName}/packages/{packageName}/notebooks:
     get:
@@ -1162,19 +1392,18 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
-  # TODO: Notebooks should return the notebook file content, not the compiled notebook.  The front end shoould
-  # run the individual notebook cells against the backend.
   /projects/{projectName}/packages/{packageName}/notebooks/{path}:
     get:
       tags:
         - notebooks
       operationId: get-notebook
-      summary: Get compiled Malloy notebook
+      summary: Get Malloy notebook cells
       description: |
-        Retrieves a compiled Malloy notebook with its cells, results, and metadata. The notebook
-        is compiled using the specified version of the Malloy compiler. This endpoint provides
-        access to the notebook's structure, cells, and execution results for use in applications.
+        Retrieves a Malloy notebook with its raw cell contents (markdown and code).
+        Cell execution should be done separately via the execute-notebook-cell endpoint.
       parameters:
         - name: projectName
           in: path
@@ -1202,11 +1431,11 @@ paths:
             $ref: "#/components/schemas/VersionIdPattern"
       responses:
         "200":
-          description: A Malloy notebook.
+          description: A Malloy notebook with raw cell contents.
           content:
             "application/json":
               schema:
-                $ref: "#/components/schemas/CompiledNotebook"
+                $ref: "#/components/schemas/RawNotebook"
         "401":
           $ref: "#/components/responses/Unauthorized"
         "404":
@@ -1216,6 +1445,82 @@ paths:
         "501":
           $ref: "#/components/responses/NotImplemented"
 
+  /projects/{projectName}/packages/{packageName}/notebooks/{path}/cells/{cellIndex}:
+    get:
+      tags:
+        - notebooks
+      operationId: execute-notebook-cell
+      summary: Execute a specific notebook cell
+      description: |
+        Executes a specific cell in a Malloy notebook by index. For code cells, this compiles
+        and runs the Malloy code, returning query results and any new sources defined.
+        For markdown cells, this simply returns the cell content.
+      parameters:
+        - name: projectName
+          in: path
+          description: Name of the project
+          required: true
+          schema:
+            $ref: "#/components/schemas/IdentifierPattern"
+        - name: packageName
+          in: path
+          description: Name of the package
+          required: true
+          schema:
+            type: string
+        - name: path
+          in: path
+          description: Path to notebook within the package
+          required: true
+          schema:
+            type: string
+        - name: cellIndex
+          in: path
+          description: Index of the cell to execute (0-based)
+          required: true
+          schema:
+            type: integer
+        - name: versionId
+          in: query
+          description: Version identifier for the package
+          required: false
+          schema:
+            $ref: "#/components/schemas/VersionIdPattern"
+        - name: filter_params
+          in: query
+          description: JSON-encoded filter parameter values keyed by filter name
+          required: false
+          schema:
+            type: string
+        - name: bypass_filters
+          in: query
+          description: When true, skip filter injection entirely
+          required: false
+          schema:
+            type: string
+            enum:
+              - "true"
+              - "false"
+      responses:
+        "200":
+          description: Cell execution result
+          content:
+            "application/json":
+              schema:
+                $ref: "#/components/schemas/NotebookCellResult"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+        "501":
+          $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
   /projects/{projectName}/packages/{packageName}/databases:
     get:
       tags:
@@ -1262,6 +1567,8 @@ paths:
           $ref: "#/components/responses/InternalServerError"
         "501":
           $ref: "#/components/responses/NotImplemented"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /connections/test:
     post:
@@ -1295,6 +1602,8 @@ paths:
           $ref: "#/components/responses/NotFound"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /watch-mode/status:
     get:
@@ -1317,6 +1626,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /watch-mode/start:
     post:
@@ -1341,6 +1652,8 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
 
   /watch-mode/stop:
     post:
@@ -1359,11 +1672,228 @@ paths:
           $ref: "#/components/responses/Unauthorized"
         "500":
           $ref: "#/components/responses/InternalServerError"
+        "503":
+          $ref: "#/components/responses/ServiceUnavailable"
+
+  /projects/{projectName}/packages/{packageName}/materializations:
+    post:
+      tags:
+        - materializations
+      operationId: create-materialization
+      summary: Create a materialization
+      description: |
+        Creates a new materialization in PENDING state for all persist sources across all
+        models in the package. Use POST .../materializations/{materializationId}?action=start to begin execution.
+      parameters:
+        - $ref: "#/components/parameters/projectName"
+        - $ref: "#/components/parameters/packageName"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CreateMaterializationRequest"
+      responses:
+        "201":
+          description: Materialization created
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Materialization"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: Package already has an active materialization
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    get:
+      tags:
+        - materializations
+      operationId: list-materializations
+      summary: List materializations for a package
+      description: Returns the materialization history for the package, ordered by
+        most recent first.
+      parameters:
+        - $ref: "#/components/parameters/projectName"
+        - $ref: "#/components/parameters/packageName"
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+          description: Maximum number of materializations to return
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+          description: Number of materializations to skip
+      responses:
+        "200":
+          description: List of materializations
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: "#/components/schemas/Materialization"
+        "404":
+          $ref: "#/components/responses/NotFound"
+
+  /projects/{projectName}/packages/{packageName}/materializations/{materializationId}:
+    get:
+      tags:
+        - materializations
+      operationId: get-materialization
+      summary: Get a specific materialization
+      parameters:
+        - $ref: "#/components/parameters/projectName"
+        - $ref: "#/components/parameters/packageName"
+        - $ref: "#/components/parameters/materializationId"
+      responses:
+        "200":
+          description: Materialization details
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Materialization"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    post:
+      tags:
+        - materializations
+      operationId: materialization-action
+      summary: Perform an action on a materialization
+      description: |
+        Performs an action on a materialization. The action is specified via
+        the `action` query parameter:
+          * `start` - Transitions a PENDING materialization to RUNNING and begins execution in the background. Returns 202.
+          * `stop` - Cancels a PENDING or RUNNING materialization. Returns 200.
+      parameters:
+        - $ref: "#/components/parameters/projectName"
+        - $ref: "#/components/parameters/packageName"
+        - $ref: "#/components/parameters/materializationId"
+        - name: action
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - start
+              - stop
+          description: Action to perform on the materialization
+      responses:
+        "200":
+          description: Materialization cancelled (action=stop)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Materialization"
+        "202":
+          description: Materialization started (action=start)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Materialization"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: Materialization cannot transition to the requested state
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+    delete:
+      tags:
+        - materializations
+      operationId: delete-materialization
+      summary: Delete a materialization
+      description: Deletes a terminal (SUCCESS, FAILED, or CANCELLED) materialization
+        record.
+      parameters:
+        - $ref: "#/components/parameters/projectName"
+        - $ref: "#/components/parameters/packageName"
+        - $ref: "#/components/parameters/materializationId"
+      responses:
+        "204":
+          description: Materialization deleted
+        "404":
+          $ref: "#/components/responses/NotFound"
+        "409":
+          description: Materialization cannot be deleted (PENDING or RUNNING)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+
+  /projects/{projectName}/packages/{packageName}/manifest:
+    get:
+      tags:
+        - manifests
+      operationId: get-manifest
+      summary: Get the build manifest for a package
+      description: |
+        Returns the current build manifest containing buildId-to-tableName mappings
+        for all materialized sources in the package.
+      parameters:
+        - $ref: "#/components/parameters/projectName"
+        - $ref: "#/components/parameters/packageName"
+      responses:
+        "200":
+          description: Build manifest
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BuildManifest"
+        "404":
+          $ref: "#/components/responses/NotFound"
+    post:
+      tags:
+        - manifests
+      operationId: manifest-action
+      summary: Perform an action on the package manifest
+      description: |
+        Performs an action on the package manifest. The action is specified via
+        the `action` query parameter:
+          * `reload` - Reads the build manifest from the shared store (DuckLake
+            in orchestrated mode, local DuckDB in standalone mode) and recompiles
+            every model in the package so subsequent queries resolve persisted
+            sources to their materialized tables. Intended for orchestrated
+            workers that did not themselves run the build; the endpoint does
+            not write anything *into* storage.
+      parameters:
+        - $ref: "#/components/parameters/projectName"
+        - $ref: "#/components/parameters/packageName"
+        - name: action
+          in: query
+          required: true
+          schema:
+            type: string
+            enum:
+              - reload
+          description: Action to perform on the manifest
+      responses:
+        "200":
+          description: Manifest loaded
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/BuildManifest"
+        "400":
+          $ref: "#/components/responses/BadRequest"
+        "404":
+          $ref: "#/components/responses/NotFound"
 
 components:
   responses:
     BadRequest:
-      description: The request was malformed or cannot be performed given the current state of the system
+      description: The request was malformed or cannot be performed given the current
+        state of the system
       content:
         application/json:
           schema:
@@ -1404,6 +1934,13 @@ components:
         application/json:
           schema:
             $ref: "#/components/schemas/Error"
+    ServiceUnavailable:
+      description: The service is temporarily unavailable, typically due to
+        initialization, or draining state (Rolling updates, etc.)
+      content:
+        application/json:
+          schema:
+            $ref: "#/components/schemas/Error"
 
   schemas:
     IdentifierPattern:
@@ -1436,10 +1973,22 @@ components:
         initialized:
           type: boolean
           description: Whether the server is fully initialized and ready to serve requests
+        operationalState:
+          type: string
+          enum: [ "initializing", "serving", "draining" ]
+          description: Status of the server; initializing when the server is loading
+            projects, packages and connections, serving when the server is
+            initialized and ready to serve requests, and draining when the
+            server is going to shut down
+        frozenConfig:
+          type: boolean
+          description: Whether the server configuration is frozen (read-only mode). When
+            true, all mutation operations are disabled.
 
     Project:
       type: object
-      description: Represents a Malloy project containing packages, connections, and other resources
+      description: Represents a Malloy project containing packages, connections, and
+        other resources
       properties:
         resource:
           type: string
@@ -1452,7 +2001,8 @@ components:
           description: Project README content
         location:
           type: string
-          description: Project location, can be an absolute path or URI (e.g. github, s3, gcs, etc.)
+          description: Project location, can be an absolute path or URI (e.g. github, s3,
+            gcs, etc.)
         connections:
           type: array
           description: List of database connections configured for this project
@@ -1463,10 +2013,24 @@ components:
           description: List of Malloy packages in this project
           items:
             $ref: "#/components/schemas/Package"
+        materializationStorage:
+          type: object
+          nullable: true
+          description: Optional DuckLake-backed storage for materialization manifests
+            (orchestrated mode). When set, manifests are stored in a shared
+            DuckLake catalog instead of the local DuckDB database.
+          properties:
+            catalogUrl:
+              type: string
+              description: PostgreSQL connection URL for the DuckLake catalog metadata store
+            dataPath:
+              type: string
+              description: Cloud storage path (s3:// or gs://) for DuckLake data files
 
     Package:
       type: object
-      description: Represents a Malloy package containing models, notebooks, and embedded databases
+      description: Represents a Malloy package containing models, notebooks, and
+        embedded databases
       properties:
         resource:
           type: string
@@ -1479,7 +2043,8 @@ components:
           description: Package description
         location:
           type: string
-          description: Package location, can be an absolute path or URI (e.g. github, s3, gcs, etc.)
+          description: Package location, can be an absolute path or URI (e.g. github, s3,
+            gcs, etc.)
 
     Model:
       type: object
@@ -1515,9 +2080,9 @@ components:
           type: string
           description: Error message if the notebook failed to compile or load
 
-    CompiledNotebook:
+    RawNotebook:
       type: object
-      description: Compiled Malloy notebook with cells, results, and execution data
+      description: Raw Malloy notebook with unexecuted cell contents
       properties:
         resource:
           type: string
@@ -1533,9 +2098,19 @@ components:
           description: Version of the Malloy compiler used to generate the notebook data
         notebookCells:
           type: array
-          description: Array of notebook cells containing code, markdown, and execution results
+          description: Array of notebook cells containing raw markdown and code content
           items:
             $ref: "#/components/schemas/NotebookCell"
+        annotations:
+          type: array
+          description: Array of file-level (##) annotations attached to the notebook
+          items:
+            type: string
+        sources:
+          type: array
+          description: Sources defined in the notebook's model
+          items:
+            $ref: "#/components/schemas/Source"
 
     CompiledModel:
       type: object
@@ -1558,7 +2133,8 @@ components:
           description: JSON string containing model metadata and structure information
         sourceInfos:
           type: array
-          description: Array of JSON strings containing source information for each data source
+          description: Array of JSON strings containing source information for each data
+            source
           items:
             type: string
         queries:
@@ -1566,6 +2142,11 @@ components:
           description: Array of named queries defined in the model
           items:
             $ref: "#/components/schemas/Query"
+        sources:
+          type: array
+          description: Sources defined in this model
+          items:
+            $ref: "#/components/schemas/Source"
 
     View:
       type: object
@@ -1596,22 +2177,99 @@ components:
           items:
             type: string
 
+    Filter:
+      type: object
+      description: A filter declared via #(filter) annotation on a Malloy source
+      properties:
+        name:
+          type: string
+          description: Display name of the filter
+        dimension:
+          type: string
+          description: Dimension this filter targets
+        type:
+          type: string
+          description: Comparator type
+          enum:
+            - equal
+            - in
+            - like
+            - greater_than
+            - less_than
+        implicit:
+          type: boolean
+          description: Whether this filter is hidden from users
+        required:
+          type: boolean
+          description: Whether a value must be provided
+        dimensionType:
+          type: string
+          description: Malloy data type of the dimension (e.g. string, number, boolean,
+            date, timestamp)
+
+    Source:
+      type: object
+      description: A Malloy source defined in a model
+      properties:
+        name:
+          type: string
+          description: Name of the source
+        annotations:
+          type: array
+          description: Annotations attached to the source
+          items:
+            type: string
+        views:
+          type: array
+          description: Views defined in this source
+          items:
+            $ref: "#/components/schemas/View"
+        filters:
+          type: array
+          description: Filters declared on this source via #(filter) annotations
+          items:
+            $ref: "#/components/schemas/Filter"
+
     QueryRequest:
       type: object
       description: Request body for executing a Malloy query
       properties:
         query:
           type: string
-          description: Query string to execute on the model. If the query parameter is set, the queryName parameter must be empty.
+          description: Query string to execute on the model. If the query parameter is
+            set, the queryName parameter must be empty.
         sourceName:
           type: string
-          description: Name of the source in the model to use for queryName, search, and topValue requests.
+          description: Name of the source in the model to use for queryName, search, and
+            topValue requests.
         queryName:
           type: string
-          description: Name of a query to execute on a source in the model. Requires the sourceName parameter is set. If the queryName parameter is set, the query parameter must be empty.
+          description: Name of a query to execute on a source in the model. Requires the
+            sourceName parameter is set. If the queryName parameter is set, the
+            query parameter must be empty.
+        compactJson:
+          type: boolean
+          default: false
+          description: "If true, returns a simple JSON array of row objects in the form
+            {\"columnName\": value}. If false (default), returns the full Malloy
+            result with type metadata for rendering."
         versionId:
           type: string
           description: Version ID
+        filterParams:
+          type: object
+          description: Filter parameter values keyed by filter name. Used with sources
+            that declare #(filter) annotations.
+          additionalProperties:
+            oneOf:
+              - type: string
+              - type: array
+                items:
+                  type: string
+        bypassFilters:
+          type: boolean
+          default: false
+          description: When true, skip server-side #(filter) injection entirely.
 
     NotebookCell:
       type: object
@@ -1619,7 +2277,29 @@ components:
       properties:
         type:
           type: string
-          enum: ["markdown", "code"]
+          enum: [ "markdown", "code" ]
+          description: Type of notebook cell
+        text:
+          type: string
+          description: Text contents of the notebook cell (either markdown or Malloy code)
+        newSources:
+          type: array
+          description: Array of JSON strings containing SourceInfo objects made available
+            in this cell
+          items:
+            type: string
+        queryInfo:
+          type: string
+          description: JSON string containing QueryInfo object for the query in this cell
+            (if the cell contains a query)
+
+    NotebookCellResult:
+      type: object
+      description: Result of executing a notebook cell
+      properties:
+        type:
+          type: string
+          enum: [ "markdown", "code" ]
           description: Type of notebook cell
         text:
           type: string
@@ -1629,7 +2309,8 @@ components:
           description: JSON string containing the execution result for this cell
         newSources:
           type: array
-          description: Array of JSON strings containing SourceInfo objects made available in this cell
+          description: Array of JSON strings containing SourceInfo objects made available
+            in this cell
           items:
             type: string
 
@@ -1639,10 +2320,50 @@ components:
       properties:
         result:
           type: string
-          description: JSON string containing the query results, metadata, and execution information
+          description: JSON string containing the query results, metadata, and execution
+            information
         resource:
           type: string
           description: Resource path to the query result
+        renderLogs:
+          type: array
+          description: Render tag validation messages (errors, warnings) detected during
+            query preparation
+          items:
+            $ref: "#/components/schemas/LogMessage"
+
+    LogMessage:
+      type: object
+      description: A log message from render tag validation
+      properties:
+        url:
+          type: string
+          description: URL of the source file related to this message
+        range:
+          type: object
+          description: Source location range for this message
+          properties:
+            start:
+              type: object
+              properties:
+                line:
+                  type: integer
+                character:
+                  type: integer
+            end:
+              type: object
+              properties:
+                line:
+                  type: integer
+                character:
+                  type: integer
+        severity:
+          type: string
+          description: Severity level of the log message
+          enum: [ "debug", "info", "warn", "error" ]
+        message:
+          type: string
+          description: Human-readable log message
 
     Database:
       type: object
@@ -1659,7 +2380,7 @@ components:
         type:
           type: string
           description: Type of embedded database
-          enum: ["embedded", "materialized"]
+          enum: [ "embedded", "materialized" ]
 
     Schema:
       description: A schema name in a Connection.
@@ -1692,7 +2413,16 @@ components:
           type: string
           description: Type of database connection
           enum:
-            [postgres, bigquery, snowflake, trino, mysql, duckdb, motherduck]
+            [
+              postgres,
+              bigquery,
+              snowflake,
+              trino,
+              mysql,
+              duckdb,
+              motherduck,
+              ducklake,
+            ]
         attributes:
           $ref: "#/components/schemas/ConnectionAttributes"
         postgresConnection:
@@ -1709,6 +2439,8 @@ components:
           $ref: "#/components/schemas/DuckdbConnection"
         motherduckConnection:
           $ref: "#/components/schemas/MotherDuckConnection"
+        ducklakeConnection:
+          $ref: "#/components/schemas/DucklakeConnection"
 
     ConnectionAttributes:
       type: object
@@ -1748,7 +2480,8 @@ components:
           description: PostgreSQL password for authentication
         connectionString:
           type: string
-          description: Complete PostgreSQL connection string (alternative to individual parameters)
+          description: Complete PostgreSQL connection string (alternative to individual
+            parameters)
 
     MysqlConnection:
       type: object
@@ -1770,6 +2503,116 @@ components:
           type: string
           description: MySQL password for authentication
 
+    GCSConnection:
+      type: object
+      description: Google Cloud Storage connection configuration for DuckDB
+      properties:
+        keyId:
+          type: string
+          description: GCS HMAC access key ID
+        secret:
+          type: string
+          description: GCS HMAC secret key
+      required:
+        - keyId
+        - secret
+
+    S3Connection:
+      type: object
+      description: AWS S3 connection configuration for DuckDB
+      properties:
+        accessKeyId:
+          type: string
+          description: AWS access key ID
+        secretAccessKey:
+          type: string
+          description: AWS secret access key
+        region:
+          type: string
+          description: AWS region (e.g., us-east-1)
+          default: us-east-1
+        endpoint:
+          type: string
+          description: Custom S3-compatible endpoint URL (optional, for MinIO, etc.)
+        sessionToken:
+          type: string
+          description: AWS session token for temporary credentials (optional)
+      required:
+        - accessKeyId
+        - secretAccessKey
+
+    AzureConnection:
+      type: object
+      description: >
+        Azure Data Lake Storage (ADLS Gen2) / Blob Storage connection
+        configuration Supports https://, http://, abfss://, and az:// URL
+        schemes.
+      properties:
+        authType:
+          type: string
+          enum: [ service_principal, sas_token ]
+          description: Authentication method for Azure Storage
+        sasUrl:
+          type: string
+          description: >
+            Full SAS URL including token; required for sas_token auth. Supports
+            single file, directory glob (*.ext), or recursive (**) patterns.
+            Example:
+            https://account.blob.core.windows.net/container/path/*.parquet?sp=rl&st=...
+        tenantId:
+          type: string
+          description: Azure AD tenant ID (required for service_principal)
+        clientId:
+          type: string
+          description: Azure AD application (client) ID (required for service_principal)
+        clientSecret:
+          type: string
+          description: Azure AD client secret (required for service_principal)
+        accountName:
+          type: string
+          description: Azure Storage account name (required for service_principal)
+        fileUrl:
+          type: string
+          description: >
+            Azure file URL to query; required for service_principal auth.
+            Supports single file, directory glob (*.ext), or recursive (**)
+            patterns. Example:
+            https://account.blob.core.windows.net/container/path/**
+      required:
+        - authType
+
+    DucklakeConnection:
+      type: object
+      description: DuckLake lakehouse connection configuration
+      properties:
+        storage:
+          type: object
+          description: Data storage connection configuration (S3 or GCS)
+          properties:
+            bucketUrl:
+              type: string
+              description: URL of the storage bucket (e.g. s3://my-bucket/path or
+                gs://my-bucket/path)
+            s3Connection:
+              $ref: "#/components/schemas/S3Connection"
+              description: AWS S3 connection configuration for data storage
+            gcsConnection:
+              $ref: "#/components/schemas/GCSConnection"
+              description: Google Cloud Storage connection configuration for data storage
+          required:
+            - bucketUrl
+        catalog:
+          type: object
+          description: Catalog metadata connection configuration
+          properties:
+            postgresConnection:
+              $ref: "#/components/schemas/PostgresConnection"
+              description: PostgreSQL connection for DuckLake metadata catalog
+          required:
+            - postgresConnection
+      required:
+        - storage
+        - catalog
     BigqueryConnection:
       type: object
       description: Google BigQuery database connection configuration
@@ -1885,7 +2728,7 @@ components:
         type:
           type: string
           description: Type of database connection
-          enum: [bigquery, snowflake, postgres]
+          enum: [ bigquery, snowflake, postgres, gcs, s3, azure ]
         attributes:
           $ref: "#/components/schemas/ConnectionAttributes"
         bigqueryConnection:
@@ -1894,7 +2737,12 @@ components:
           $ref: "#/components/schemas/SnowflakeConnection"
         postgresConnection:
           $ref: "#/components/schemas/PostgresConnection"
-
+        gcsConnection:
+          $ref: "#/components/schemas/GCSConnection"
+        s3Connection:
+          $ref: "#/components/schemas/S3Connection"
+        azureConnection:
+          $ref: "#/components/schemas/AzureConnection"
     # TODO: What is this?  Can we remove it?
     SqlSource:
       type: object
@@ -2011,8 +2859,12 @@ components:
           description: Name of the project being watched for file changes
         watchingPath:
           type: string
-          nullable: true
-          description: The file system path being monitored for changes, null if not watching
+          description: The file system path being monitored for changes, null if not
+            watching
+      required:
+        - enabled
+        - projectName
+        - watchingPath
 
     StartWatchRequest:
       type: object
@@ -2031,7 +2883,159 @@ components:
         status:
           type: string
           description: Connection test result status
-          enum: ["ok", "failed"]
+          enum: [ "ok", "failed" ]
         errorMessage:
           type: string
           description: Error message if the connection test failed, null if successful
+
+    CompileRequest:
+      type: object
+      description: Request body for compiling Malloy source code
+      properties:
+        source:
+          type: string
+          description: Malloy source code to compile
+        includeSql:
+          type: boolean
+          default: false
+          description: If true, returns the generated SQL alongside compilation results
+            (only available when compilation succeeds and the source contains a
+            runnable query).
+      required:
+        - source
+
+    CompileResult:
+      type: object
+      description: Result of a Malloy source compilation check
+      properties:
+        status:
+          type: string
+          description: Overall compilation status — "error" if any problems have error
+            severity
+          enum: [ "success", "error" ]
+        problems:
+          type: array
+          description: List of compilation problems (errors and warnings)
+          items:
+            $ref: "#/components/schemas/CompileProblem"
+        sql:
+          type: string
+          description: Generated SQL for the compiled query. Only present when includeSql
+            is true and compilation succeeds with a runnable query.
+
+    CompileProblem:
+      type: object
+      description: A compilation problem reported by the Malloy compiler
+      properties:
+        message:
+          type: string
+          description: Human-readable problem description
+        severity:
+          type: string
+          description: Severity level of the problem
+          enum: [ "error", "warn", "debug" ]
+        code:
+          type: string
+          description: Machine-readable error code
+        at:
+          type: object
+          description: Source location of the problem
+          properties:
+            url:
+              type: string
+              description: URL of the source file
+            range:
+              type: object
+              description: Character range within the source file
+
+    CreateMaterializationRequest:
+      type: object
+      description: Options for creating a materialization
+      properties:
+        forceRefresh:
+          type: boolean
+          default: false
+          description: If true, forces rebuild of all sources even if their BuildID is
+            unchanged
+        autoLoadManifest:
+          type: boolean
+          default: false
+          description: If true, automatically reloads the manifest into the Malloy Runtime
+            after a successful materialization
+
+    Materialization:
+      type: object
+      description: A record of a package materialization
+      properties:
+        id:
+          type: string
+        projectId:
+          type: string
+        packageName:
+          type: string
+        status:
+          type: string
+          enum: [ "PENDING", "RUNNING", "SUCCESS", "FAILED", "CANCELLED" ]
+        startedAt:
+          type: [ "string", "null" ]
+          format: date-time
+        completedAt:
+          type: [ "string", "null" ]
+          format: date-time
+        error:
+          type: [ "string", "null" ]
+          description: Error message if the materialization failed
+        metadata:
+          type: [ "object", "null" ]
+          description: Materialization metadata including build options, source counts,
+            and durations
+        createdAt:
+          type: string
+          format: date-time
+        updatedAt:
+          type: string
+          format: date-time
+
+    BuildManifest:
+      type: object
+      description: Manifest mapping BuildIDs to materialized table names
+      properties:
+        entries:
+          type: object
+          additionalProperties:
+            $ref: "#/components/schemas/ManifestEntry"
+          description: Map of BuildID to manifest entry
+        strict:
+          type: boolean
+          description: Whether the manifest is in strict mode
+
+    ManifestEntry:
+      type: object
+      description: A single entry in the build manifest
+      properties:
+        tableName:
+          type: string
+          description: Name of the materialized table
+
+  parameters:
+    projectName:
+      name: projectName
+      in: path
+      required: true
+      description: Name of the project
+      schema:
+        type: string
+    packageName:
+      name: packageName
+      in: path
+      required: true
+      description: Name of the package
+      schema:
+        type: string
+    materializationId:
+      name: materializationId
+      in: path
+      required: true
+      description: ID of the materialization
+      schema:
+        type: string