> ## Documentation Index > Fetch the complete documentation index at: https://docs.credibledata.com/llms.txt > Use this file to discover all available pages before exploring further. # List environment packages > Retrieves a list of all Malloy packages within the specified environment. Each package contains models, notebooks, databases, and other resources. This endpoint is useful for discovering available packages and their basic metadata. ## OpenAPI ````yaml /dataplane-public-api-doc.yaml get /environments/{environmentName}/packages openapi: 3.1.0 info: title: Malloy Publisher - Semantic Model Serving API description: > The Malloy Publisher - Semantic Model Serving API provides comprehensive access to Malloy packages and their associated resources. A Malloy package is a directory containing Malloy models (.malloy files), Malloy notebooks (.malloynb files), and embedded databases (.parquet files) with a malloy-publisher.json manifest at the package's root directory. ## Key Features - **Environment Management**: Create and manage environments with their associated packages and connections - **Package Lifecycle**: Full CRUD operations for Malloy packages and their versions - **Model & Notebook Access**: Retrieve and execute Malloy models and notebooks - **Connection Management**: Secure database connection configuration and testing - **Query Execution**: Execute queries against models and retrieve results - **Watch Mode**: Real-time file watching for development workflows ## Resource Hierarchy The API follows a hierarchical resource structure: ``` Environments ├── Connections └── Packages ├── Models ├── Notebooks └── Databases ``` For examples, see the Malloy samples packages (https://github.com/malloydata/malloy-samples) repository. version: v0 servers: - url: https://{organization}.data.credibledata.com/api/v0/ description: Production API server variables: organization: default: demo description: Your organization subdomain security: - bearerAuth: [] tags: - name: publisher description: Publisher status and health check operations - name: environments description: >- Environment lifecycle management including creation, configuration, and deletion of data modeling environments - name: connections description: >- Database connection management for secure data source configuration and access - name: packages description: >- Package management for Malloy data models, including versioning and distribution - name: models description: Malloy model access and compilation operations - name: notebooks description: Malloy notebook access and execution operations - name: pages description: Static HTML pages (in-package data apps) - name: databases 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 paths: /environments/{environmentName}/packages: get: tags: - packages summary: List environment packages description: > Retrieves a list of all Malloy packages within the specified environment. Each package contains models, notebooks, databases, and other resources. This endpoint is useful for discovering available packages and their basic metadata. operationId: list-packages parameters: - name: environmentName in: path description: Name of the environment required: true schema: $ref: '#/components/schemas/IdentifierPattern' responses: '200': description: A list of all packages in the environment content: application/json: schema: type: array items: $ref: '#/components/schemas/Package' '401': $ref: '#/components/responses/Unauthorized' '500': $ref: '#/components/responses/InternalServerError' '501': $ref: '#/components/responses/NotImplemented' '503': $ref: '#/components/responses/ServiceUnavailable' components: schemas: IdentifierPattern: type: string pattern: ^[a-zA-Z0-9_-]+$ description: Standard identifier pattern for resource names Package: type: object description: >- Represents a Malloy package containing models, notebooks, and embedded databases properties: resource: type: string description: Resource path to the package name: type: string description: Package name description: type: string description: Package description location: type: string description: >- Package location, can be an absolute path or URI (e.g. github, s3, gcs, etc.) explores: type: array items: type: string description: >- 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. exploresWarnings: type: array readOnly: true items: type: string description: >- Actionable messages for declared explores that do not resolve to a real model in this package (e.g. a misspelled path, or a notebook listed as an explore). Server-computed and read-only: it is ignored on create/update requests and only ever returned in responses. Present only when there are such problems. Loading is fail-safe — the unresolved entry simply lists nothing rather than exposing everything — so this is the signal that a package is misconfigured; publishing such a package is rejected. warnings: type: array readOnly: true description: >- Non-fatal render-tag findings collected when the package loaded: a render annotation (e.g. `# big_value` or `# currency`) misconfigured for the field it sits on, so it renders as "[object Object]" or an inline error at query time but does not stop the model compiling or the package loading. Server-computed and read-only: ignored on create/update requests and only returned in responses. Present only when there are such findings. items: type: object properties: model: type: string description: Package-relative path of the model the finding is on. target: type: string description: >- The query or view the finding sits on, e.g. `by_carrier` or `flights -> by_carrier`. message: type: string description: The render validator's description of the problem. severity: type: string enum: - error - warn description: >- Finding severity. Currently only `error`-severity render findings are surfaced here; lower-severity findings remain on the query-time `renderLogs` surface. queryableSources: type: string enum: - declared - all description: >- 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)`. manifestLocation: type: - string - 'null' description: > 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: type: string enum: - version - package description: >- 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 platform default (`package`) and never as a scope change. See docs/persistence.md §3.1. materialization: oneOf: - $ref: '#/components/schemas/PackageMaterializationConfig' - type: 'null' description: | 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. manifestBindingStatus: type: string readOnly: true enum: - unbound - bound - live_fallback description: >- Server-computed, read-only: whether the configured build manifest is currently bound to this package's served models. `unbound` = no manifest configured, so the package serves live. `bound` = a manifest was fetched and applied, so persist sources route to their materialized physical tables. `live_fallback` = a `manifestLocation` is configured but the fetch/bind failed or timed out, so the package is serving live despite intending to be materialized-routed. Lets the caller confirm the publisher actually bound the configured manifest rather than inferring it from logs. manifestEntryCount: type: integer readOnly: true description: >- Server-computed, read-only: number of sourceEntityId -> physical-table entries currently bound (0 when unbound or on live fallback). boundManifestUri: type: - string - 'null' readOnly: true description: >- Server-computed, read-only: the manifest URI actually bound to the served models. Usually equals `manifestLocation`, but can differ after an in-memory auto-load following a materialization build (no URI), in which case it is null. Null whenever the package is unbound. buildPlan: oneOf: - $ref: '#/components/schemas/BuildPlan' - type: 'null' readOnly: true description: >- Server-computed, read-only: the persist build plan for this package version (per-source sourceEntityId, output columns, build SQL, dependency graphs), exposed as a deterministic property of the compiled package. A caller reads it directly off the load/get-package response, assigns physical names/identity per source, and issues a single build call (see `CreateMaterializationRequest.buildInstructions`) — no separate plan round-trip. The plan is a pure function of the compiled model + connection config (no warehouse access), so it is stable for a given (package version, connection config). Returned by default whenever the package is compiled; null only when the package declares no persist source. PackageMaterializationConfig: type: object description: >- Package-level Malloy Persistence policy from malloy-publisher.json's `materialization` block. Surfaced verbatim so the control plane can drive scheduled version-level re-materialization without re-reading the package files. properties: schedule: type: - string - 'null' description: >- 5-field UNIX cron controlling how often the control plane re-materializes this package's published versions. Null/absent = no scheduled re-materialization (publish / on-demand only). A cron is valid only in `scope: version` mode and is mutually exclusive with any freshness declaration in the package (package/model-file/source/ index). A cron on a `scope: package` package, or alongside any freshness, is rejected at publish (declare `materialization.freshness.window` instead). See docs/persistence.md §9.4. freshness: oneOf: - $ref: '#/components/schemas/Freshness' - type: 'null' description: >- The manifest's `materialization.freshness` block, verbatim. Null = no freshness policy declared. `window` is the control plane's refresh objective for the package's materialized sources; `fallback` is the declared query-time behavior when the objective is missed. The publisher only surfaces the values — the control plane owns the scheduling and gating logic. BuildPlan: type: object description: > The package's persist build plan. Mirrors Malloy's native build plan plus the minimal per-source detail a caller needs to assign identity/naming/realization. Lineage, policy, and connection capability are intentionally omitted until they carry real data. required: - graphs - sources properties: graphs: type: array description: Dependency-ordered build graphs, one per connection. items: $ref: '#/components/schemas/BuildGraph' sources: type: object description: Map of sourceID ("sourceName@modelURL") to per-source plan. additionalProperties: $ref: '#/components/schemas/PersistSourcePlan' Error: type: object description: Standard error response format properties: message: type: string description: Human-readable error message describing what went wrong details: type: string description: Additional error details or context required: - message Freshness: type: object description: >- Freshness policy declared in malloy-publisher.json's `materialization.freshness` block. Fields are surfaced verbatim; invalid values are dropped (reported as absent), never defaulted. properties: window: type: string description: >- Maximum acceptable staleness of the package's materialized sources, as a duration string (e.g. "24h"). The control plane schedules refreshes to meet it. fallback: type: string enum: - live - stale_ok - fail description: >- Declared query-time behavior when the freshness window is missed: serve live, serve the stale table, or fail the query. BuildGraph: type: object required: - connectionName - nodes properties: connectionName: type: string nodes: type: array description: >- Leveled build nodes; each inner array is one parallelizable level, levels run in order. items: type: array items: $ref: '#/components/schemas/BuildNode' PersistSourcePlan: type: object required: - name - sourceID - connectionName - sourceEntityId - sql - columns properties: name: type: string sourceID: type: string connectionName: type: string dialect: type: string sourceEntityId: type: string description: >- Stable, content-addressed identity of this persisted source. Today a deterministic SHA-256 hex digest (`mkBuildID`) over the source's connection `fingerprint` and its canonical compiled SQL — deliberately independent of package version, so it changes only when the source's data identity changes. (Folding source scope into the address and moving to a UUID5 form is planned but not yet shipped.) Consumers treat it as an opaque token and use the supplied value verbatim. sql: type: string description: >- The source's build SQL (with the build manifest applied for upstream rewrites). refresh: type: - string - 'null' description: >- The source's declared `#@ persist ... refresh=...` value ("full" | "incremental"), reported verbatim; null = unset. Metadata pass-through — inert to the publisher today. freshness: oneOf: - $ref: '#/components/schemas/Freshness' - type: 'null' description: >- The source's EFFECTIVE freshness objective after most-specific-wins resolution (source > model-file > package). Null = unset at every level; the control plane applies the platform default. Reported verbatim (invalid fields dropped, never defaulted). columns: type: array description: Output schema of the source. items: $ref: '#/components/schemas/Column' annotationFields: type: object additionalProperties: type: string description: >- All key=value fields of the source's `#@ persist` annotation (e.g. `name`, `realization`). The control plane uses `name` as the materialized table name — it may carry a dialect container path (`dataset.table` / `project.dataset.table`) — falling back to the Malloy source name when absent. modelPath: type: string description: >- Package-relative path of the `.malloy` model that declares this source (e.g. `order_rollup.malloy`). The source's sourceID embeds an absolute `file://` modelURL with no package boundary, so this is the only place the relative path is exposed; the control plane uses it to let the build-plan DAG deep-link a source back to its model. BuildNode: type: object required: - sourceID properties: sourceID: type: string description: sourceName@modelURL dependsOn: type: array description: Upstream sourceIDs in this graph. items: type: string Column: type: object description: Database column definition properties: name: type: string description: Name of the column type: type: string description: Data type of the column responses: Unauthorized: description: Unauthorized - authentication required content: application/json: schema: $ref: '#/components/schemas/Error' InternalServerError: description: The server encountered an internal error content: application/json: schema: $ref: '#/components/schemas/Error' NotImplemented: description: The requested operation is not implemented content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: > The service is temporarily unable to accept the request. Possible causes: * Initialization or draining state (rolling updates, graceful shutdown). * Memory back-pressure — the publisher's RSS crossed the high-water mark derived from PUBLISHER_MAX_MEMORY_BYTES and PUBLISHER_MEMORY_HIGH_WATER_FRACTION, so new queries are rejected until RSS drops below the low-water mark (PUBLISHER_MEMORY_LOW_WATER_FRACTION). * Per-pod query concurrency cap reached — PUBLISHER_MAX_CONCURRENT_QUERIES in-flight queries are already running on this pod. Clients should retry with backoff; under sustained pressure, scale out, raise PUBLISHER_MAX_MEMORY_BYTES / PUBLISHER_MAX_CONCURRENT_QUERIES, or refine the offending queries. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````