> ## 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 package versions > Retrieves all versions of a specific package, including version identifiers, creation timestamps, and archive status information. **Authorization**: Requires read access to the package. **Response**: Returns array of version objects ordered by creation date. ## OpenAPI ````yaml /controlplane-public-api-doc.yaml get /organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions 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: get: tags: - versions summary: List package versions description: > Retrieves all versions of a specific package, including version identifiers, creation timestamps, and archive status information. **Authorization**: Requires read access to the package. **Response**: Returns array of version objects ordered by creation date. operationId: listVersions 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' responses: '200': description: List of versions retrieved successfully content: application/json: schema: type: array items: $ref: '#/components/schemas/Version' '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 Version: type: object description: >- Represents a specific version of a package with metadata and lifecycle information properties: id: $ref: '#/components/schemas/SemanticVersionPattern' type: string description: >- The unique version identifier, typically following semantic versioning (e.g., 1.2.3) createdAt: type: string format: date-time description: ISO 8601 timestamp indicating when this version was created updatedAt: type: string format: date-time description: ISO 8601 timestamp indicating when this version was last modified archiveStatus: type: string description: Current status of the package version, controlling its availability enum: - archive - unarchive - error_state stale: type: boolean readOnly: true description: > True when this version serves at least one stale artifact — a materialized source or index that is serving non-current data for any reason (docs/persistence.md §9.7). Display-only roll-up (the OR of its artifacts' `stale`); the version still serves prior values. False/absent otherwise. staleSince: type: string format: date-time nullable: true readOnly: true description: > The earliest fresh→stale crossover instant across the version's stale artifacts (§9.7 roll-up). Null when no artifact carries an age-based crossover (or the version is fresh). staleReasons: type: array readOnly: true items: $ref: '#/components/schemas/StalenessReason' description: > The union of the version's artifacts' staleness cause(s) (§9.7). Empty when fresh. promoteWhenReady: type: boolean readOnly: true description: > Whether this version is armed for auto-promote: the version-lifecycle reconciler promotes it to the package's `latestVersion` once it is ready (fully indexed and settled into a servable resting state — materialized, or no persist sources / DuckDB serving live) and has never been latest. Read-only state set by the system at publish when the package's `autoPromote` policy is enabled (at most one version per package is armed at a time); cleared once the intent resolves (after promotion, or on terminal materialization failure). promotedAt: type: string format: date-time nullable: true readOnly: true description: > When this version most recently became the package's latest. Null if it has never been promoted. Used as the auto-promote "never been latest" rollback guard. demotedAt: type: string format: date-time nullable: true readOnly: true description: > When this version most recently stopped being the package's latest. Null while it is the current latest or has never been latest. Auto-archive's ttl is measured from this timestamp. metadata: $ref: '#/components/schemas/VersionIndexingMetadata' nullable: true indexingProgress: $ref: '#/components/schemas/VersionIndexingProgress' buildStatus: type: string readOnly: true description: > Single aggregate build status for this version, rolling up its materialization and indexing into one lifecycle so tables and indexes present as one family: - `FAILED` if either side failed. - else `BUILDING` while either side is still working (materializing, or indexing not yet settled). - else `UNSUPPORTED` when the version declares persist sources whose dialect cannot be materialized in v0 (DuckDB) — nothing is built and those sources serve live — and indexing has settled. - else `READY` once both sides have reached a servable resting state. Derived read-only projection. enum: - BUILDING - READY - FAILED - UNSUPPORTED scope: type: string nullable: true readOnly: true description: | The version's materialization scope mode, ingested from the package manifest root (`Package.scope`) at materialize time: - `version`: this version owns its materialized source tables — they are not reused across versions. (Dimension indexes are the exception: they remain content-addressed and may still be shared across versions regardless of scope until per-version index isolation lands with the index-cadence scheduler — see the note on `Index.scope`.) A package-level `materializationSchedule` is legal only in this mode. - `package`: materialized source tables may be reused across the package's own versions when fresh; cadence is freshness only (no schedule). Null when unknown (older versions materialized before scope was recorded); the control plane treats null as the default (`package`). enum: - version - package materializationSchedule: type: string nullable: true readOnly: true description: > The version's re-materialization cadence — the 5-field UNIX cron from the package manifest's `materialization.schedule` (e.g. `0 6 * * *`), ingested at materialize time. Null when the package declares no schedule (the version materializes only on publish or on-demand rebuild). nextScheduledAt: type: string format: date-time nullable: true readOnly: true description: | When the scheduler will next re-materialize this version on its `materializationSchedule`. Null when the version has no schedule. lastRefreshedAt: type: string format: date-time nullable: true readOnly: true description: > When a scheduled (SCHEDULER-trigger) re-materialization of this version last fired. Null when the version has no schedule or has not yet fired. materializationFreshnessWindowSeconds: type: integer format: int64 nullable: true readOnly: true description: > The package-level freshness window declared in the package manifest's `materialization.freshness.window`, parsed to seconds and ingested write-once at materialize time. This is the refresh objective / staleness bound that individual sources and indexes inherit as the package default under most-specific-wins resolution. Null when the package declares no freshness window. Mutually exclusive with `materializationSchedule`: a version configures a schedule OR a freshness window, never both. materializationFreshnessFallback: type: string nullable: true readOnly: true description: > The package-level freshness fallback (`materialization.freshness.fallback`) — the query-time behavior when the window is missed ("live" | "stale_ok" | "fail"), reported verbatim from the manifest. Null when unset or no freshness is declared. buildPlan: $ref: '#/components/schemas/BuildPlanGraph' nullable: true description: > The persist build plan's dependency graph (DAG) for this version — the persist sources and their dependsOn edges. Read from the publisher's deterministic build plan. Populated only on the single-version GET (getVersion); null on list responses and when the version declares no persist source or no healthy worker can serve the plan. SemanticVersionPattern: type: string pattern: >- ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ description: >- SemVer 2.0 version identifier. Required core MAJOR.MINOR.PATCH plus optional pre-release suffix (e.g. `-rc1`, `-alpha.2`) and optional build metadata (e.g. `+20231120.deadbeef`). Previously enforced strict MAJOR.MINOR.PATCH only, which would have started 400-ing legitimate pre-release versions (e.g. videoamp's -rc1/-rc2 RC builds) once hibernate-validator started firing. 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 VersionIndexingMetadata: type: object description: Metadata from indexing failures, attached to a package version properties: displayErrorMessage: type: string description: User-friendly error message explaining why indexing failed rawErrorMessage: type: string description: Detailed error message VersionIndexingProgress: type: object nullable: true description: > Aggregate package-indexing (source-extraction) progress for a package version, polled from the entity-indexing service while the version is being indexed. Populated on the single-version read while indexing is in progress (indexStatus = indexing); null once indexed/failed or when progress is unavailable. Mirrors ConnectionIndexingProgress. Per-dimension index progress is surfaced separately via the index-run / dimensional-index APIs, not here. properties: packageProgress: $ref: '#/components/schemas/PackageIndexingProgress' BuildPlanGraph: type: object description: > The persist build plan's dependency graph (DAG) for a version: persist sources as nodes and their dependsOn relationships as edges. A deterministic property of the compiled package version, so identical across that version's runs. properties: nodes: type: array items: $ref: '#/components/schemas/BuildPlanNode' edges: type: array items: $ref: '#/components/schemas/BuildPlanEdge' 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 PackageIndexingProgress: type: object description: Package-indexing pipeline progress (sources). properties: sourcesTotal: type: integer sourcesProcessing: type: integer sourcesCompleted: type: integer sourcesFailed: type: integer entitiesFound: type: integer nullable: true description: >- Sum of compiled entities indexed over completed sources (null if no counts recorded yet). BuildPlanNode: type: object description: One persist source in the build plan. properties: sourceId: type: string description: Stable source identifier (the publisher's sourceID). name: type: string description: The persist source's name. connectionName: type: string description: The connection the source materializes into. modelPath: type: string description: >- Package-relative path of the `.malloy` model that declares this source (e.g. `order_rollup.malloy`), for deep-linking the source back to its model. Null when the serving worker's build plan predates this field. BuildPlanEdge: type: object description: A dependency edge — "from" must be built before "to". properties: from: type: string description: Upstream source id (a dependency). to: type: string description: Downstream source id that depends on "from". 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 ````