> ## 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 materializations for a version > Lists the per-source materializations bound to a package version (Malloy Persistence v0), most recent first. Each materialization is the lineage anchor for one persist source of the version — identified within the version by its (`sourceName`, `modelFilePath`) — and points at the physical table currently serving that source. In v0 materializations are addressed under the version that binds them. Package-level (cross-version) materialization resources will be added once versions can share materialized tables. **Authorization**: Requires read access to the package. ## OpenAPI ````yaml /controlplane-public-api-doc.yaml get /organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations openapi: 3.1.0 info: title: Credible Admin API description: > The Credible Admin API is a comprehensive REST API that empowers organizations to manage their Malloy data modeling ecosystem with enterprise-grade security and governance. This API provides programmatic access to all administrative functions, enabling seamless integration with existing workflows and automation systems. ## Key Features - **Organization Management**: Create and manage organizations with fine-grained access controls - **Environment & Package Lifecycle**: Full CRUD operations for environments, packages, and versions - **Connection Management**: Secure database connection configuration and management - **Permission Management**: Granular role-based access control (RBAC) at organization, environment, package, workspace, and document levels - **Workspace Management**: Collaborative workspaces for data modeling and analysis - **User & Group Management**: Comprehensive user administration with group-based permissions ## Resource Hierarchy The API follows a hierarchical resource structure with fine-grained permission management at each level: ``` Organizations ├── Permissions ├── Environments │ ├── Permissions │ ├── Packages │ │ ├── Permissions │ │ └── Versions │ └── Connections ├── Workspaces │ ├── Permissions │ └── Documents │ └── Permissions └── Groups ├── Permissions └── Members System-Level Resources: ├── Users ├── System Permissions └── Demo Operations ``` ## Authentication & Authorization All API endpoints require proper authentication. The API implements fine-grained authorization using role-based permissions: - **Admin**: Full access to all resources within scope - **Modeler**: Can create and modify data models and packages - **Viewer**: Read-only access to resources - **Manager**: Workspace management capabilities - **Editor**: Document editing permissions ## Rate Limiting & Best Practices - API requests are rate-limited to ensure system stability - Implement proper error handling and retry logic - Cache responses when appropriate to reduce API calls ## Support & Documentation For additional support, examples, and integration guides, visit our developer documentation or contact our support team. version: v0 contact: name: Credible Support email: support@credibledata.com url: https://credibledata.com/support license: name: Proprietary url: https://credibledata.com/license termsOfService: https://credibledata.com/terms servers: - url: https://{organization}.admin.credibledata.com/api/v0/ description: Production API server variables: organization: default: demo description: Your organization subdomain security: - bearerAuth: [] tags: - name: organizations description: >- Organization management operations for creating, updating, and managing organizational entities - name: organizationPermissions description: >- Fine-grained permission management for organizations, including role assignments and access controls - name: environments description: >- Environment lifecycle management including creation, configuration, and deletion of data modeling environments - name: environmentPermissions description: >- Permission management for environments, controlling access to environment resources and capabilities - name: packages description: >- Package management for Malloy data models, including versioning, publishing, and distribution - name: packagePermissions description: >- Access control for packages, managing who can view, modify, or publish package versions - name: versions description: >- Version management for packages, including archiving, status updates, and lifecycle management - name: connections description: >- Database connection management for secure data source configuration and access - name: materializations description: >- Malloy Persistence materializations (per-version serving anchors for persisted sources) - name: indexes description: >- Malloy Persistence dimensional search indexes (per-version serving anchors for indexed dimensions) - name: runs description: >- Malloy Persistence build/refresh runs — one package-level build event carrying typed units (materialized sources + built indexes) - name: workspaces description: >- Collaborative workspace management for team-based data modeling and analysis - name: workspacePermissions description: >- Access control for workspaces, managing who can view, manage, or collaborate in workspaces - name: documents description: >- Document management within workspaces, including workbooks, dashboards, and other content - name: documentPermissions description: >- Access control for documents, managing who can view, edit, or share document content - name: groups description: >- User group management for organizing users and managing group-based permissions - name: users description: >- User account management including creation, updates, and profile management - name: demo description: Demo and self-service operations for quick setup and testing scenarios - name: permissions description: System-level permission management for administrative functions - name: bookmarks description: >- User bookmark management for saving references to workspaces, models, and chats - name: attributes description: Trusted user attributes for fine-grain (row/column-level) access control - name: invites description: >- Organization-creation invite tokens. A super-admin mints tokens one per call (call `POST /invites` repeatedly to populate an outreach campaign); each token can be redeemed once by an authenticated user to create a new organization on the fly. paths: /organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/materializations: get: tags: - materializations summary: List materializations for a version description: | Lists the per-source materializations bound to a package version (Malloy Persistence v0), most recent first. Each materialization is the lineage anchor for one persist source of the version — identified within the version by its (`sourceName`, `modelFilePath`) — and points at the physical table currently serving that source. In v0 materializations are addressed under the version that binds them. Package-level (cross-version) materialization resources will be added once versions can share materialized tables. **Authorization**: Requires read access to the package. operationId: listMaterializations parameters: - name: organizationName in: path required: true description: The unique identifier of the organization schema: $ref: '#/components/schemas/IdentifierPattern' - name: environmentName in: path required: true description: The unique identifier of the environment schema: $ref: '#/components/schemas/IdentifierPattern' - name: packageName in: path required: true description: The unique identifier of the package schema: $ref: '#/components/schemas/IdentifierPattern' - name: versionId in: path required: true description: The unique identifier of the version schema: $ref: '#/components/schemas/VersionIdPattern' responses: '200': description: List of materializations retrieved successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Materialization' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: schemas: IdentifierPattern: type: string pattern: ^[a-zA-Z0-9_ -]+$ description: Standard identifier pattern for resource names VersionIdPattern: type: string pattern: ^[a-zA-Z0-9_.-]+$ description: Version identifier pattern supporting dots and dashes Materialization: type: object description: | A per-source materialization (Malloy Persistence v0). It is the lineage anchor for one persist source of the version — identified within the version by its (`sourceName`, `modelFilePath`) — and points at the physical table currently serving that source. The underlying artifact's content address is internal and never exposed here. properties: id: type: string sourceName: type: string description: Fully-qualified persist source name within the package. modelFilePath: type: string description: > The model file that declares this source. Two files in one version may declare the same `sourceName` as distinct anchors, so a scoped source rerun must pass both `sourceName` and `modelFilePath` to target the right one (mirrors `Index.modelFilePath`). Empty string (never null) for an anchor with no recorded path — the column is `NOT NULL DEFAULT ''`. status: type: string enum: - PENDING - READY - FAILED error: type: string description: > When `status` is FAILED, the reason the most recent build failed — the error of the materialization's latest run (where build failures occur), surfaced here so the cause (e.g. a BigQuery "Permission bigquery.tables.delete denied" warehouse error, or a build that produced no table) is visible inline without drilling into individual runs. A read-time projection of the run's error; null while PENDING/READY. connectionName: type: string description: >- Name of the connection whose warehouse holds the currently serving materialized table (null until first READY build). servingRunId: type: string description: >- Id of the run whose materialized table this version currently serves; the physical table name is exposed directly on this DTO as `materializedTableName` (and per-source on that run's `buildPlan.nodes[].tableName`). Auto-advances to the latest successful run. A materialization always has a serving run once it has a successful build; null only until the first table is built. servingBuildNumber: type: integer description: | The `buildNumber` (the "gNNN" the UI shows) of the run named by `servingRunId`, resolved server-side so the client can render the serving build label without a second, version-scoped run lookup. Under table reuse the serving run can belong to a *prior* version, so a client-side lookup against the current version's runs would miss it; this field is version-agnostic. Null until the first table is built, or for a legacy serving run created before build numbers existed. materializedTableName: type: string description: >- Physical name of the currently serving materialized table (null until the first READY build). servingStartedAt: type: string format: date-time description: >- When the currently serving table was materialized, i.e. began serving (null until the first READY build). scope: type: string enum: - version - package description: > The materialization scope mode this source's table was built under (replaces the removed per-source `sharing`): `version` = version-owned, no cross-version reuse; `package` = reusable across the package's own versions when fresh. Null = unknown (materialized before scope was recorded). This is a per-anchor **convenience mirror** of the canonical `Version.scope`, not an independent per-source knob: scope is declared once at the package-manifest root and is uniform across every source and index of a version, so this always equals the owning version's `scope`. It is surfaced here so a single materialization is self-describing without a second `getVersion`; read `Version.scope` when you want the authoritative version-grain value. refresh: type: string description: | The source's declared `#@ persist ... refresh=...` value ("full" | "incremental"), reported verbatim. Null = unset. Policy metadata for display (inert to the build today). freshnessWindowSeconds: type: integer format: int64 description: > The source's EFFECTIVE freshness window (after most-specific-wins resolution: source > model-file > package), in seconds — the control plane's refresh objective for this source's materialized table. Null = unset at every level (the platform default applies). freshnessFallback: type: string enum: - live - stale_ok - fail description: | The source's EFFECTIVE freshness fallback — the declared query-time behavior when the window is missed. Null = unset. stale: type: boolean readOnly: true description: | True when this source is serving non-current data for any reason (docs/persistence.md §9.7). The unified staleness indicator; the machine-readable cause(s) are in `staleReasons`. False/absent otherwise. staleSince: type: string format: date-time nullable: true readOnly: true description: | The fresh→stale crossover instant — the age-based component (`dataAsOf + freshness.window`). Null when the staleness is only failure-derived (no age crossover), or when the source is fresh. staleReasons: type: array readOnly: true items: $ref: '#/components/schemas/StalenessReason' description: | The machine-readable staleness cause(s) (§9.7). Empty when fresh. createdAt: type: string format: date-time updatedAt: type: string format: date-time StalenessReason: type: string description: | Machine-readable cause for an artifact's staleness (docs/persistence.md §9.7 — one indicator, orthogonal reasons). Split into GATING reasons (their presence sets `stale=true`) and ANNOTATION reasons (they explain why an already-stale artifact keeps aging, never flip it on their own): * `FRESHNESS_WINDOW_EXCEEDED` (gating) — data age passed the declared `freshness.window` (§9.3 tables, §9.5 indexes). * `SOURCE_BUILD_FAILED` (gating) — serving prior values because this version's source materialization FAILED (the reused-over-failed case, generalized; symmetric for a source whose latest rebuild failed while a prior generation still serves). * `REFRESH_IN_PROGRESS` (annotation) — a scheduled refresh has fired but no fresher generation has landed yet (self-heals). * `LAST_REFRESH_FAILED` (annotation) — the refresh stream was disarmed after repeated fires without landing a fresher generation. * `WINDOW_BELOW_BUILD_TIME` (annotation) — the declared freshness window is shorter than the estimated build duration, so the objective is physically unachievable (the rebuild cannot complete inside the window). The window needs widening, or what it covers reducing. enum: - FRESHNESS_WINDOW_EXCEEDED - SOURCE_BUILD_FAILED - REFRESH_IN_PROGRESS - LAST_REFRESH_FAILED - WINDOW_BELOW_BUILD_TIME Error: type: object x-model-name: ModelError description: Standard error response format used across all API endpoints properties: code: type: string description: > Machine-readable error code that identifies the specific error condition. Clients should branch on `code`, not on the human-readable `message` — the message text is informational and may change over time. Generic codes (may appear on any endpoint): - `VALIDATION_ERROR`: Request body or path/query parameter failed validation - `AUTHENTICATION_REQUIRED`: Valid authentication is required - `INSUFFICIENT_PERMISSIONS`: User lacks required permissions - `RESOURCE_NOT_FOUND`: Requested resource does not exist - `CONFLICT`: Generic resource state conflict (used when no more specific code applies) - `RATE_LIMIT_EXCEEDED`: API rate limit exceeded - `INTERNAL_ERROR`: Unexpected server error Endpoint-specific codes used by the signup / invites flow: - `ORGANIZATION_NAME_TAKEN`: 409 on `POST /organizations` — the requested org name (URL slug) is already in use. Retry with a different name. - `ORGANIZATION_NAME_RESERVED`: 409 on `POST /organizations` — the requested org name collides with a platform subdomain (e.g. `signup`, `admin`, `data`, `login`) and cannot be claimed. Retry with a different name. - `INVITE_ALREADY_CONSUMED`: 409 on `POST /organizations` — the supplied invite token has already been redeemed into an existing organization. Retry will not help; the token is dead. - `INVITE_ALREADY_CONSUMED_REVOKE`: 409 on `DELETE /invites/{token}` — consumed invites are preserved for audit and cannot be revoked. - `INVITE_INVALID`: 400 on `POST /organizations` — the supplied invite token is malformed or unknown. - `INVITE_EXPIRED`: 400 on `POST /organizations` — the supplied invite token is past its `expiresAt`. - `INVITE_EMAIL_MISMATCH`: 403 on `POST /organizations` — the invite is bound to a different email address than the caller. message: type: string description: Human-readable error message providing details about what went wrong responses: BadRequest: description: >- The request was malformed or can not be performed given the state of the system. content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- Can not perform the operation due to insufficient permissions or the state of the system. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The specified resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````