Lightdash Spaces API

openapi: 3.0.0
info:
  title: Lightdash AiAgents Spaces API
  version: 0.3156.1
  description: 'Open API documentation for all public Lightdash API endpoints. # Authentication Before you get started, you might need to create a Personal Access Token to authenticate via the API. You can create a token by following this guide: https://docs.lightdash.com/references/personal_tokens

    '
  license:
    name: MIT
  contact:
    name: Lightdash Support
    email: support@lightdash.com
    url: https://docs.lightdash.com/help-and-contact/contact/contact_info/
servers:
- url: /
tags:
- name: Spaces
  description: Spaces allow you to organize charts and dashboards within a project. They also allow granular access to content by allowing you to create private spaces, which are only accessible to the creator and admins.
paths:
  /api/v1/projects/{projectUuid}/spaces/{spaceUuid}:
    get:
      operationId: GetSpace
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSpaceResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get details for a space in a project
      summary: Get space
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The uuid of the space to get
        in: path
        name: spaceUuid
        required: true
        schema:
          type: string
    delete:
      operationId: DeleteSpace
      responses:
        '204':
          description: Deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Delete a space from a project
      summary: Delete space
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The uuid of the space to delete
        in: path
        name: spaceUuid
        required: true
        schema:
          type: string
    patch:
      operationId: UpdateSpace
      responses:
        '200':
          description: Updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSpaceResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Update a space in a project
      summary: Update space
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The uuid of the space to update
        in: path
        name: spaceUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSpace'
  /api/v1/projects/{projectUuid}/spaces/{spaceUuid}/delete-impact:
    get:
      operationId: GetSpaceDeleteImpact
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSpaceDeleteImpactResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Get the impact of deleting a space (affected child spaces, charts, dashboards)
      summary: Get delete impact
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The uuid of the space to check
        in: path
        name: spaceUuid
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/spaces:
    post:
      operationId: CreateSpaceInProject
      responses:
        '200':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSpaceResponse'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Create a new space inside a project
      summary: Create space
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSpace'
  /api/v1/projects/{projectUuid}/spaces/{spaceUuid}/share:
    post:
      operationId: AddSpaceUserAccess
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Grant a user access to a space
      summary: Grant user access to space
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - in: path
        name: spaceUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSpaceUserAccess'
  /api/v1/projects/{projectUuid}/spaces/{spaceUuid}/share/{userUuid}:
    delete:
      operationId: RevokeSpaceAccessForUser
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Remove a user's access to a space
      summary: Revoke user access to space
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The uuid of the space to update
        in: path
        name: spaceUuid
        required: true
        schema:
          type: string
      - description: The uuid of the user to revoke access from
        in: path
        name: userUuid
        required: true
        schema:
          type: string
  /api/v1/projects/{projectUuid}/spaces/{spaceUuid}/group/share:
    post:
      operationId: AddSpaceGroupAccess
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Grant a group access to a space
      summary: Grant group access to space
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The uuid of the space to update
        in: path
        name: spaceUuid
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddSpaceGroupAccess'
  /api/v1/projects/{projectUuid}/spaces/{spaceUuid}/group/share/{groupUuid}:
    delete:
      operationId: RevokeGroupSpaceAccess
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiSuccessEmpty'
        default:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiErrorPayload'
      description: Remove a group's access to a space
      summary: Revoke group access to space
      tags:
      - Spaces
      security: []
      parameters:
      - description: The uuid of the space's parent project
        in: path
        name: projectUuid
        required: true
        schema:
          type: string
      - description: The uuid of the space to update
        in: path
        name: spaceUuid
        required: true
        schema:
          type: string
      - description: The uuid of the group to revoke access from
        in: path
        name: groupUuid
        required: true
        schema:
          type: string
components:
  schemas:
    OrganizationMemberRole:
      enum:
      - member
      - viewer
      - interactive_viewer
      - editor
      - developer
      - admin
      type: string
    ApiSpaceDeleteImpactResponse:
      properties:
        results:
          $ref: '#/components/schemas/SpaceDeleteImpact'
        status:
          type: string
          enum:
          - ok
          nullable: false
      required:
      - results
      - status
      type: object
    ChartSummary:
      allOf:
      - $ref: '#/components/schemas/Pick_SavedChart.uuid-or-name-or-description-or-spaceName-or-spaceUuid-or-projectUuid-or-organizationUuid-or-pinnedListUuid-or-dashboardUuid-or-dashboardName-or-slug_'
      - properties:
          source:
            $ref: '#/components/schemas/ChartSourceType'
          chartKind:
            $ref: '#/components/schemas/ChartKind'
          chartType:
            $ref: '#/components/schemas/ChartType'
        type: object
    SpaceGroup:
      properties:
        spaceRole:
          $ref: '#/components/schemas/SpaceMemberRole'
        groupName:
          type: string
        groupUuid:
          type: string
      required:
      - spaceRole
      - groupName
      - groupUuid
      type: object
    AddSpaceUserAccess:
      properties:
        spaceRole:
          $ref: '#/components/schemas/SpaceMemberRole'
        userUuid:
          type: string
      required:
      - spaceRole
      - userUuid
      type: object
    SpaceMemberRole:
      enum:
      - viewer
      - editor
      - admin
      type: string
    AnyType:
      description: 'This AnyType is an alias for any

        The goal is to make it easier to identify any type in the codebase

        without having to eslint-disable all the time

        These are only used on legacy `any` types, don''t use it for new types.

        This is added on a separate file to avoid circular dependencies.'
    Pick_ValidationResponse.error-or-createdAt-or-validationUuid-or-validationId_:
      properties:
        createdAt:
          type: string
          format: date-time
        error:
          type: string
        validationUuid:
          type: string
        validationId:
          type: number
          format: double
          nullable: true
          deprecated: true
      required:
      - createdAt
      - error
      - validationUuid
      - validationId
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    ApiSuccessEmpty:
      properties:
        results: {}
        status:
          type: string
          enum:
          - ok
          nullable: false
      required:
      - status
      type: object
    ApiErrorPayload:
      properties:
        error:
          properties:
            data:
              $ref: '#/components/schemas/AnyType'
              description: Optional data containing details of the error
            message:
              type: string
              description: A friendly message summarising the error
            name:
              type: string
              description: Unique name for the type of error
            statusCode:
              type: number
              format: integer
              description: HTTP status code
          required:
          - name
          - statusCode
          type: object
        status:
          type: string
          enum:
          - error
          nullable: false
      required:
      - error
      - status
      type: object
      description: 'The Error object is returned from the api any time there is an error.

        The message contains'
    ChartSourceType:
      enum:
      - dbt_explore
      - sql
      type: string
    ? Pick_Dashboard.uuid-or-name-or-description-or-updatedAt-or-projectUuid-or-updatedByUser-or-organizationUuid-or-spaceUuid-or-views-or-firstViewedAt-or-pinnedListUuid-or-pinnedListOrder_
    : properties:
        description:
          type: string
        name:
          type: string
        projectUuid:
          type: string
        organizationUuid:
          type: string
        uuid:
          type: string
        pinnedListUuid:
          type: string
          nullable: true
        pinnedListOrder:
          type: number
          format: double
          nullable: true
        updatedAt:
          type: string
          format: date-time
        spaceUuid:
          type: string
        updatedByUser:
          $ref: '#/components/schemas/UpdatedByUser'
        views:
          type: number
          format: double
        firstViewedAt:
          anyOf:
          - type: string
          - type: string
            format: date-time
          nullable: true
      required:
      - name
      - projectUuid
      - organizationUuid
      - uuid
      - pinnedListUuid
      - pinnedListOrder
      - updatedAt
      - spaceUuid
      - views
      - firstViewedAt
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    ValidationSummary:
      $ref: '#/components/schemas/Pick_ValidationResponse.error-or-createdAt-or-validationUuid-or-validationId_'
    DashboardBasicDetails:
      allOf:
      - $ref: '#/components/schemas/Pick_Dashboard.uuid-or-name-or-description-or-updatedAt-or-projectUuid-or-updatedByUser-or-organizationUuid-or-spaceUuid-or-views-or-firstViewedAt-or-pinnedListUuid-or-pinnedListOrder_'
      - properties:
          verification:
            allOf:
            - $ref: '#/components/schemas/ContentVerificationInfo'
            nullable: true
          validationErrors:
            items:
              $ref: '#/components/schemas/ValidationSummary'
            type: array
        required:
        - verification
        type: object
    SpaceDeleteImpact:
      properties:
        appCount:
          type: number
          format: double
        dashboardCount:
          type: number
          format: double
        chartCount:
          type: number
          format: double
        apps:
          items:
            properties:
              spaceUuid:
                type: string
                nullable: true
              uuid:
                type: string
            required:
            - spaceUuid
            - uuid
            type: object
          type: array
        dashboards:
          items:
            properties:
              spaceUuid:
                type: string
              name:
                type: string
              uuid:
                type: string
            required:
            - spaceUuid
            - name
            - uuid
            type: object
          type: array
        charts:
          items:
            properties:
              spaceUuid:
                type: string
              name:
                type: string
              uuid:
                type: string
            required:
            - spaceUuid
            - name
            - uuid
            type: object
          type: array
        spaces:
          items:
            properties:
              appCount:
                type: number
                format: double
              dashboardCount:
                type: number
                format: double
              chartCount:
                type: number
                format: double
              parentSpaceUuid:
                type: string
                nullable: true
              name:
                type: string
              uuid:
                type: string
            required:
            - appCount
            - dashboardCount
            - chartCount
            - parentSpaceUuid
            - name
            - uuid
            type: object
          type: array
      required:
      - appCount
      - dashboardCount
      - chartCount
      - apps
      - dashboards
      - charts
      - spaces
      type: object
    AddSpaceGroupAccess:
      properties:
        spaceRole:
          $ref: '#/components/schemas/SpaceMemberRole'
        groupUuid:
          type: string
      required:
      - spaceRole
      - groupUuid
      type: object
    SpaceQuery:
      allOf:
      - $ref: '#/components/schemas/ChartSummary'
      - $ref: '#/components/schemas/Pick_SavedChart.updatedAt-or-updatedByUser-or-pinnedListOrder_'
      - $ref: '#/components/schemas/ViewStatistics'
      - properties:
          verification:
            allOf:
            - $ref: '#/components/schemas/ContentVerificationInfo'
            nullable: true
          validationErrors:
            items:
              $ref: '#/components/schemas/ValidationSummary'
            type: array
        required:
        - verification
        type: object
    ViewStatistics:
      properties:
        firstViewedAt:
          anyOf:
          - type: string
            format: date-time
          - type: string
          nullable: true
        views:
          type: number
          format: double
      required:
      - firstViewedAt
      - views
      type: object
    Pick_SavedChart.updatedAt-or-updatedByUser-or-pinnedListOrder_:
      properties:
        pinnedListOrder:
          type: number
          format: double
          nullable: true
        updatedAt:
          type: string
          format: date-time
          description: Timestamp when the chart was last updated
        updatedByUser:
          $ref: '#/components/schemas/UpdatedByUser'
      required:
      - pinnedListOrder
      - updatedAt
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    ChartType:
      enum:
      - cartesian
      - table
      - big_number
      - pie
      - funnel
      - treemap
      - gauge
      - custom
      - map
      - sankey
      type: string
    UpdatedByUser:
      properties:
        userUuid:
          type: string
        firstName:
          type: string
        lastName:
          type: string
      required:
      - userUuid
      - firstName
      - lastName
      type: object
      additionalProperties: true
    SpaceShare:
      allOf:
      - $ref: '#/components/schemas/SpaceAccess'
      - $ref: '#/components/schemas/SpaceAccessUserMetadata'
    ProjectMemberRole:
      enum:
      - viewer
      - interactive_viewer
      - editor
      - developer
      - admin
      type: string
    ? Pick_Space.organizationUuid-or-projectUuid-or-uuid-or-name-or-inheritParentPermissions-or-projectMemberAccessRole-or-pinnedListUuid-or-pinnedListOrder-or-slug-or-parentSpaceUuid-or-path_
    : properties:
        name:
          type: string
        projectUuid:
          type: string
        organizationUuid:
          type: string
        uuid:
          type: string
        inheritParentPermissions:
          type: boolean
        projectMemberAccessRole:
          allOf:
          - $ref: '#/components/schemas/SpaceMemberRole'
          nullable: true
        pinnedListUuid:
          type: string
          nullable: true
        pinnedListOrder:
          type: number
          format: double
          nullable: true
        slug:
          type: string
        parentSpaceUuid:
          type: string
          nullable: true
        path:
          type: string
      required:
      - name
      - projectUuid
      - organizationUuid
      - uuid
      - inheritParentPermissions
      - projectMemberAccessRole
      - pinnedListUuid
      - pinnedListOrder
      - slug
      - parentSpaceUuid
      - path
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    CreateSpace:
      properties:
        parentSpaceUuid:
          type: string
        access:
          items:
            $ref: '#/components/schemas/Pick_SpaceShare.userUuid-or-role_'
          type: array
        inheritParentPermissions:
          type: boolean
        name:
          type: string
      required:
      - name
      type: object
    ApiSpaceResponse:
      properties:
        results:
          $ref: '#/components/schemas/Space'
        status:
          type: string
          enum:
          - ok
          nullable: false
      required:
      - results
      - status
      type: object
    Space:
      properties:
        breadcrumbs:
          items:
            properties:
              hasAccess:
                type: boolean
              uuid:
                type: string
              name:
                type: string
            required:
            - hasAccess
            - uuid
            - name
            type: object
          type: array
        path:
          type: string
        colorPaletteUuid:
          type: string
          nullable: true
        projectMemberAccessRole:
          allOf:
          - $ref: '#/components/schemas/SpaceMemberRole'
          nullable: true
        inheritParentPermissions:
          type: boolean
        parentSpaceUuid:
          type: string
          nullable: true
        childSpaces:
          items:
            $ref: '#/components/schemas/SpaceSummaryBase'
          type: array
        slug:
          type: string
        pinnedListOrder:
          type: number
          format: double
          nullable: true
        pinnedListUuid:
          type: string
          nullable: true
        groupsAccess:
          items:
            $ref: '#/components/schemas/SpaceGroup'
          type: array
        access:
          items:
            $ref: '#/components/schemas/SpaceShare'
          type: array
        dashboards:
          items:
            $ref: '#/components/schemas/SpaceDashboard'
          type: array
        projectUuid:
          type: string
        queries:
          items:
            $ref: '#/components/schemas/SpaceQuery'
          type: array
        inheritsFromOrgOrProject:
          type: boolean
        name:
          type: string
        uuid:
          type: string
        organizationUuid:
          type: string
      required:
      - path
      - colorPaletteUuid
      - projectMemberAccessRole
      - inheritParentPermissions
      - parentSpaceUuid
      - childSpaces
      - slug
      - pinnedListOrder
      - pinnedListUuid
      - groupsAccess
      - access
      - dashboards
      - projectUuid
      - queries
      - inheritsFromOrgOrProject
      - name
      - uuid
      - organizationUuid
      type: object
    SpaceDashboard:
      $ref: '#/components/schemas/DashboardBasicDetails'
    ? Pick_SavedChart.uuid-or-name-or-description-or-spaceName-or-spaceUuid-or-projectUuid-or-organizationUuid-or-pinnedListUuid-or-dashboardUuid-or-dashboardName-or-slug_
    : properties:
        description:
          type: string
          description: Optional description of what this chart displays
        name:
          type: string
          description: Display name of the chart
        projectUuid:
          type: string
        organizationUuid:
          type: string
        uuid:
          type: string
        pinnedListUuid:
          type: string
          nullable: true
        slug:
          type: string
          description: Unique identifier slug for this chart
        spaceUuid:
          type: string
        dashboardUuid:
          type: string
          nullable: true
        spaceName:
          type: string
        dashboardName:
          type: string
          nullable: true
      required:
      - name
      - projectUuid
      - organizationUuid
      - uuid
      - pinnedListUuid
      - slug
      - spaceUuid
      - dashboardUuid
      - spaceName
      - dashboardName
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    UpdateSpace:
      properties:
        colorPaletteUuid:
          type: string
          nullable: true
        projectMemberAccessRole:
          allOf:
          - $ref: '#/components/schemas/SpaceMemberRole'
          nullable: true
          description: When set, all project members get this role on the space
        inheritParentPermissions:
          type: boolean
        name:
          type: string
      required:
      - name
      type: object
    SpaceSummaryBase:
      allOf:
      - $ref: '#/components/schemas/Pick_Space.organizationUuid-or-projectUuid-or-uuid-or-name-or-inheritParentPermissions-or-projectMemberAccessRole-or-pinnedListUuid-or-pinnedListOrder-or-slug-or-parentSpaceUuid-or-path_'
      - properties:
          deletedBy:
            properties:
              lastName:
                type: string
              firstName:
                type: string
              userUuid:
                type: string
            required:
            - lastName
            - firstName
            - userUuid
            type: object
          deletedAt:
            type: string
            format: date-time
          appCount:
            type: number
            format: double
          childSpaceCount:
            type: number
            format: double
          dashboardCount:
            type: number
            format: double
          chartCount:
            type: number
            format: double
        required:
        - appCount
        - childSpaceCount
        - dashboardCount
        - chartCount
        type: object
    Pick_SpaceShare.userUuid-or-role_:
      properties:
        userUuid:
          type: string
        role:
          $ref: '#/components/schemas/SpaceMemberRole'
      required:
      - userUuid
      - role
      type: object
      description: From T, pick a set of properties whose keys are in the union K
    SpaceAccess:
      properties:
        inheritedFrom:
          type: string
          enum:
          - organization
          - project
          - group
          - space_group
          - parent_space
        inheritedRole:
          anyOf:
          - $ref: '#/components/schemas/OrganizationMemberRole'
          - $ref: '#/components/schemas/ProjectMemberRole'
        projectRole:
          $ref: '#/components/schemas/ProjectMemberRole'
        hasDirectAccess:
          type: boolean
        role:
          $ref: '#/components/schemas/SpaceMemberRole'
        userUuid:
          type: string
      required:
      - hasDirectAccess
      - role
      - userUuid
      type: object
    ChartKind:
      enum:
      - line
      - horizontal_bar
      - vertical_bar
      - scatter
      - area
      - mixed
      - pie
      - table
      - big_number
      - funnel
      - custom
      - treemap
      - gauge
      - map
      - sankey
      type: string
    ContentVerificationInfo:
      properties:
        verifiedAt:
          type: string
          format: date-time
        verifiedBy:
          properties:
            lastName:
              type: string
            firstName:
              type: string
            userUuid:
              type: string
          required:
          - lastName
          - firstName
          - userUuid
          type: object
      required:
      - verifiedAt
      - verifiedBy
      type: object
    SpaceAccessUserMetadata:
      properties:
        isInternal:
          type: boolean
        email:
          type: string
        lastName:
          type: string
        firstName:
          type: string
      required:
      - isInternal
      - email
      - lastName
      - firstName
      type: object
  securitySchemes:
    session_cookie:
      type: apiKey
      in: cookie
      name: connect.sid
    api_key:
      type: apiKey
      in: header
      name: Authorization
      description: Value should be 'ApiKey <your key>'