Create a new package

Creates a new Malloy package within the specified environment. A package serves as a container for models, notebooks, embedded databases, and other resources. The package will be initialized with the provided metadata and can immediately accept content.

POST/environments/{environmentName}/packages

Authorization

bearerAuth

AuthorizationBearer <token>

In: header

Path Parameters

environmentName*string

Name of the environment

Match^[a-zA-Z0-9_-]+$

Request Body

application/json

Represents a Malloy package containing models, notebooks, and embedded databases

resource?string

Resource path to the package

name?string

Package name

description?string

Package description

location?string

Package location, can be an absolute path or URI (e.g. github, s3, gcs, etc.)

explores?array<string>

Optional opt-in for curated discovery. When present, only these model file paths (relative to the package root) are listed via listModels(), and within-file discovery is filtered to each model's export {} closure. When absent or empty, every model is listed with its full source set (backward-compatible). Every other .malloy file still compiles for import/join resolution but is hidden from listings once explores is declared. Notebooks are always listed regardless of this field.

queryableSources?string

Controls whether the discovery surface is also a query boundary. "declared" (the default) makes queryable == discoverable: when explores is declared, only explores model files — and within them only the export {} closure — are valid top-level query targets; every other source still compiles, imports, joins, and extends but is not directly queryable (denied with 404). "all" decouples them: explores/export {} gate discovery only and every compiled source stays directly queryable. When explores is absent there is no curated surface, so both modes are equivalent (everything queryable). Invalid values fall back to "declared". Identity-based access is a separate concern — see #(authorize).

Value in

"declared"
"all"

manifestLocation?|

URI (gs:// or s3://) of the externally-computed manifest for this package. On (re)load the publisher reads it and binds persist references (sourceEntityId -> physicalTableName). Null = serve live.

scope?string

Package-level materialization scope mode, declared at the malloy-publisher.json manifest root. Governs the lifetime/ownership of every persisted source and dimension index in the package, and replaces the removed per-source/per-dimension sharing annotation:

version: materializations are owned by (scoped to) the package version; no cross-version reuse. Cadence is a single package-level materialization.schedule OR freshness (never both).
package: materializations may be reused across the package's own versions when fresh; cadence is freshness only (no schedule allowed). Null/absent = unknown this request; the control plane treats it as the system default (package) and never as a scope change. See docs/persistence.md §3.1.

Value in

"version"
"package"

materialization?|

Package-level Malloy Persistence policy declared in malloy-publisher.json. The control plane reads it to drive scheduled re-materialization. The object is present whenever the package is loaded (with schedule: null when none is declared), so its presence is the authoritative manifest policy; null/absent means only that metadata was unavailable this request, which the control plane treats as "unknown" (never a schedule removal). A published version's schedule is persisted write-once and thereafter only verified, so it cannot self-wipe on a later build.

Response Body

`application/json`

curl --request POST \  --url 'https://example.com/environments/string/packages' \  --header 'Authorization: Bearer <token>' \  --header 'Content-Type: application/json' \  --data '{}'

{  "resource": "string",  "name": "string",  "description": "string",  "location": "string",  "explores": [    "string"  ],  "exploresWarnings": [    "string"  ],  "warnings": [    {      "model": "string",      "target": "string",      "message": "string",      "severity": "error"    }  ],  "queryableSources": "declared",  "manifestLocation": "string",  "scope": "version",  "materialization": {    "schedule": "string",    "freshness": {      "window": "string",      "fallback": "live"    }  },  "manifestBindingStatus": "unbound",  "manifestEntryCount": 0,  "boundManifestUri": "string",  "buildPlan": {    "graphs": [      {        "connectionName": "string",        "nodes": [          [            {              "sourceID": "string",              "dependsOn": [                "string"              ]            }          ]        ]      }    ],    "sources": {      "property1": {        "name": "string",        "sourceID": "string",        "connectionName": "string",        "dialect": "string",        "sourceEntityId": "string",        "sql": "string",        "refresh": "string",        "freshness": {          "window": "string",          "fallback": "live"        },        "columns": [          {            "name": "string",            "type": "string"          }        ],        "annotationFields": {          "property1": "string",          "property2": "string"        },        "modelPath": "string"      },      "property2": {        "name": "string",        "sourceID": "string",        "connectionName": "string",        "dialect": "string",        "sourceEntityId": "string",        "sql": "string",        "refresh": "string",        "freshness": {          "window": "string",          "fallback": "live"        },        "columns": [          {            "name": "string",            "type": "string"          }        ],        "annotationFields": {          "property1": "string",          "property2": "string"        },        "modelPath": "string"      }    }  }}

Create a new package

Authorization

Path Parameters

Request Body

Response Body

200application/json

400application/json

401application/json

500application/json

501application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`