> ## 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. # Create document > Creates a new document within the workspace (the `{workspaceName}` in the path is the destination), such as a workbook or dashboard. **Authorization**: Requires workspace manager or editor permissions. **Parameters**: Use `overwrite` to replace existing documents with the same path. **Content**: Supports Malloy code, configuration, and other document types. **Relocating an existing document**: Set `moveFrom` to the `credible://` URI of a document in another workspace to atomically relocate it into this workspace instead of creating from the request body. The source document is deleted, its content/metadata are transplanted under the same path here, and chat/report bookmarks are re-pointed. The request body is ignored in this mode. The destination workspace must be a shared (Group) workspace and must already have every package the source document references — the endpoint deliberately does NOT silently attach packages (that would be a backdoor for granting package read access). Returns 400 if a required package is missing; attach it via the package-permission endpoints first and retry. ## OpenAPI ````yaml /controlplane-public-api-doc.yaml post /organizations/{organizationName}/workspaces/{workspaceName}/documents 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}/workspaces/{workspaceName}/documents: post: tags: - documents summary: Create document description: > Creates a new document within the workspace (the `{workspaceName}` in the path is the destination), such as a workbook or dashboard. **Authorization**: Requires workspace manager or editor permissions. **Parameters**: Use `overwrite` to replace existing documents with the same path. **Content**: Supports Malloy code, configuration, and other document types. **Relocating an existing document**: Set `moveFrom` to the `credible://` URI of a document in another workspace to atomically relocate it into this workspace instead of creating from the request body. The source document is deleted, its content/metadata are transplanted under the same path here, and chat/report bookmarks are re-pointed. The request body is ignored in this mode. The destination workspace must be a shared (Group) workspace and must already have every package the source document references — the endpoint deliberately does NOT silently attach packages (that would be a backdoor for granting package read access). Returns 400 if a required package is missing; attach it via the package-permission endpoints first and retry. operationId: createDocument parameters: - name: organizationName in: path required: true description: The unique identifier of the organization schema: $ref: '#/components/schemas/IdentifierPattern' - name: workspaceName in: path required: true description: The unique identifier of the destination workspace schema: $ref: '#/components/schemas/WorkspaceNamePattern' - name: overwrite description: If true, the document will be overwritten if it already exists in: query required: false schema: type: boolean - name: moveFrom description: >- Optional `credible://` URI of a source document to relocate into this workspace (e.g. `credible://workspaces/{sourceWorkspace}/documents/{sourcePath}`). When set, the source document is moved here under the same path and the request body is ignored. Only data chats and reports may be moved. Not constrained by ResourceIdentifierPattern: the embedded workspace name and document path allow spaces and punctuation (see WorkspaceNamePattern / DocumentPathPattern). The URI is structurally validated by the server (parsed into workspace + document path) and the move is authorized against the resolved source document. in: query required: false schema: type: string maxLength: 512 requestBody: content: application/json: schema: $ref: '#/components/schemas/Document' responses: '200': description: Document created (or relocated) successfully content: application/json: schema: $ref: '#/components/schemas/Document' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': description: >- A document already exists at the destination path (relocate without overwrite) content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: IdentifierPattern: type: string pattern: ^[a-zA-Z0-9_ -]+$ description: Standard identifier pattern for resource names WorkspaceNamePattern: type: string pattern: ^(?!.*\*)(?!.*[/]).{1,63}$ description: >- Workspace name pattern. Allows any character except `/` (would split the FGA resource path — see ResourceIdentifier.parseFromFga) and `*` (FGA wildcard). 1-63 chars. Document: type: object description: >- Represents a document within a workspace, such as a workbook or dashboard properties: path: $ref: '#/components/schemas/DocumentPathPattern' type: string description: The file path of the document within the workspace content: type: string description: The content of the document, typically Malloy code or configuration type: type: string description: The type of document, determining its purpose and behavior enum: - workbook - dashboard - modeling_chat - data_chat - agent_report - agent_modeling_file - agent_html_report - draft_agent_html_report - draft_agent_report - draft_package - model_summary createdAt: type: string format: date-time description: ISO 8601 timestamp indicating when the document was created updatedAt: type: string format: date-time description: ISO 8601 timestamp indicating when the document was last modified modifiedBy: type: string nullable: true description: The userId of the user who last modified this document metadata: type: object nullable: true description: >- Optional JSON metadata associated with the document (e.g. title, tags) 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 DocumentPathPattern: type: string maxLength: 255 pattern: ^(?!.*\.\.)[a-zA-Z0-9_/. \-&:,'+?!()$^–—]+$ description: >- Document path. Permits alphanumerics, spaces, ASCII hyphen, Unicode en-dash/em-dash (U+2013/U+2014), and common title punctuation (& : , ' + ? ! ( ) $ ^). Bans path traversal (..). Length capped at 255 to match the underlying varchar(255) storage column. % is deliberately excluded because @InitBinder decodes %2F → / in path variables to fix encoded-slash routing, which would collide with any path that legitimately contained '%2F'. 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 ````