> ## 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 indexes for a version > Lists the per-dimension search indexes bound to a package version, most recent first. Each index is the version's serving anchor for one indexed (`#(index)`-tagged) dimension. The underlying built index is content-addressed and package-scoped (shared across versions that define the same dimension), so it is not exposed here; this returns only the version's bindings. **Authorization**: Requires read access to the package. ## OpenAPI ````yaml /controlplane-public-api-doc.yaml get /organizations/{organizationName}/environments/{environmentName}/packages/{packageName}/versions/{versionId}/indexes 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}/indexes: get: tags: - indexes summary: List indexes for a version description: | Lists the per-dimension search indexes bound to a package version, most recent first. Each index is the version's serving anchor for one indexed (`#(index)`-tagged) dimension. The underlying built index is content-addressed and package-scoped (shared across versions that define the same dimension), so it is not exposed here; this returns only the version's bindings. **Authorization**: Requires read access to the package. operationId: listIndexes 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' - name: limit in: query required: false description: >- Maximum number of items to return. Use -1 or omit to return all results. Valid values: -1 (all results) or 1–500. schema: type: integer minimum: -1 maximum: 500 default: -1 - name: offset in: query required: false description: Number of items to skip before starting to return results schema: type: integer minimum: 0 default: 0 responses: '200': description: List of indexes retrieved successfully headers: Total-Count: description: Total number of indexes available schema: type: integer required: true Link: description: RFC 8288 pagination links (first, prev, next, last) schema: type: string content: application/json: schema: type: array items: $ref: '#/components/schemas/Index' '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 Index: type: object description: > A version's serving anchor for one indexed (`#(index)`-tagged) dimension. It binds the version to the content-addressed, package-scoped built index (shared across versions, and — when the source is materialized — derived from the materialized table). That underlying artifact and its content address are internal and never exposed here. properties: id: type: string sourceName: type: string description: >- Fully-qualified source name within the package that owns the dimension. dimension: type: string description: The indexed dimension path (e.g. "country" or "people.name"). modelFilePath: type: string description: > The model file that declares this (source, dimension). Two files in one package version can declare the same source + dimension name with different definitions (each its own index), so this disambiguates otherwise-identical entries. Empty for legacy/unknown. status: type: string enum: - PENDING - READY - FAILED error: type: string description: > When `status` is FAILED, the reason the most recent build for this dimension failed — a read-time projection of the failing built index's error, surfaced inline so the cause is visible without drilling into individual runs. Null while PENDING/READY. stale: type: boolean readOnly: true description: > True when this index is serving non-current data for any reason (docs/persistence.md §9.7). Unifies the reused-over-failed-source case (`SOURCE_BUILD_FAILED`) with age-based staleness against a declared index `freshness.window` (`FRESHNESS_WINDOW_EXCEEDED`, §9.5). The machine-readable cause(s) are in `staleReasons`. Display-only: the index still serves its prior values. False/absent otherwise. staleSince: type: string format: date-time nullable: true readOnly: true description: | The fresh→stale crossover instant — the age-based component (`lastIndexedAt + effective freshness.window`). Null when the staleness is only failure-derived, or when the index is fresh. staleReasons: type: array readOnly: true items: $ref: '#/components/schemas/StalenessReason' description: | The machine-readable staleness cause(s) (§9.7). Empty when fresh. rowCount: type: integer format: int64 description: >- Number of indexed values currently serving for this dimension (null until first READY build). lastIndexedAt: type: string format: date-time description: >- When the currently serving index generation was built (null until the first READY build). scope: type: string enum: - version - package description: > The scope mode this index was built under (replaces the removed per-dimension `sharing`): `version` = version-owned; `package` = reusable across the package's own versions when fresh. Null = unknown. The dimension-grain analog of `Materialization.scope`, and — like it — a per-anchor **convenience mirror** of the canonical `Version.scope` (declared once at the package-manifest root, uniform across the version), not an independent per-dimension knob. NOTE (current phase): unlike `Materialization.scope`, this value is display metadata only — it does NOT isolate the index artifact. Index artifacts remain content-addressed by `index_entity_id` and are reused across versions regardless of `scope` (identical definition + data identity ⇒ identical index, so reuse is result-correct). A `version`-scoped index therefore records its owning version but may still share one physical artifact with another version that binds the same address; per-version artifact isolation lands with the index-cadence scheduler (persistence.md §9.5). refresh: type: string description: | The dimension's declared `#(index ... refresh=...)` value ("full" | "incremental"), reported verbatim. Null = unset. Policy metadata for display (inert to the build today). freshnessWindowSeconds: type: integer format: int64 description: > The dimension's declared `#(index ... freshness.window=...)` refresh objective, in seconds (parsed from the "24h"/"7d" surface form). Null = unset — index freshness is opt-in per dimension (§9.5), so a bare `#(index)` reports nothing and no proactive cadence applies. freshnessFallback: type: string enum: - live - stale_ok - fail description: > The dimension's declared `#(index ... freshness.fallback=...)` — query-time behavior intent when the window is missed (indexes have no gate today; metadata). Null = unset. 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 ````