Skip to main content
API docs by Redocly

Lightdash API (0.600.0)

Lightdash Support: support@lightdash.com URL: https://docs.lightdash.com/help-and-contact/contact/contact_info/ License: MIT

Open API documentation for all public Lightdash API endpoints

My Account

These routes allow users to manage their own user account.

CreateEmailOneTimePasscode

Create a new one-time passcode for the current user's primary email. The user will receive an email with the passcode.

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

GetEmailVerificationStatus

Get the verification status for the current user's primary email

query Parameters
passcode
string

the one-time passcode sent to the user's primary email

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

ListMyAvailableOrganizations

List the organizations that the current user can join. This is based on the user's primary email domain and the organization's allowed email domains.

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

JoinOrganization

Add the current user to an organization that accepts users with a verified email domain. This will fail if the organization email domain does not match the user's primary email domain.

path Parameters
organizationUuid
required
string

the uuid of the organization to join

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

DeleteMe

Delete user

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

Organizations

Each user is a member of a single organization. These routes allow users to manage their organization. Most actions are only available to admin users.

GetMyOrganization

Get the current user's organization

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

CreateOrganization

Creates a new organization, the current user becomes the Admin of the new organization. This is only available to users that are not already in an organization.

Request Body schema: application/json

the new organization settings

name
required
string

The name of the organization

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

UpdateMyOrganization

Update the current user's organization

Request Body schema: application/json

the new organization settings

name
string

The name of the organization

chartColors
Array of strings

The default color palette for all projects in the organization

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "chartColors": [
    ]
}

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

DeleteMyOrganization

Deletes an organization and all users inside that organization

path Parameters
organizationUuid
required
string

the uuid of the organization to delete

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

ListOrganizationMembers

Gets all the members of the current user's organization

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

UpdateOrganizationMember

Updates the membership profile for a user in the current user's organization

path Parameters
userUuid
required
string

the uuid of the user to update

Request Body schema: application/json

the new membership profile

role
string (OrganizationMemberRole)
Enum: "member" "viewer" "interactive_viewer" "editor" "developer" "admin"

Responses

Request samples

Content type
application/json
{
  • "role": "member"
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

DeleteOrganizationMember

Deletes a user from the current user's organization

path Parameters
userUuid
required
string

the uuid of the user to delete

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

ListOrganizationEmailDomains

Gets the allowed email domains for the current user's organization

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

UpdateOrganizationEmailDomains

Gets the allowed email domains for the current user's organization

Request Body schema: application/json
role
required
string (OrganizationMemberRole)
Enum: "member" "viewer" "interactive_viewer" "editor" "developer" "admin"
emailDomains
required
Array of strings
projectUuids
required
Array of strings

Responses

Request samples

Content type
application/json
{
  • "role": "member",
  • "emailDomains": [
    ],
  • "projectUuids": [
    ]
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

CreateGroupInOrganization

Creates a new group in the current user's organization

Request Body schema: application/json
name
required
string

A friendly name for the group

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

ListGroupsInOrganization

Gets all the groups in the current user's organization

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

Projects

Projects belong to a single organization. These routes allow users to manage their projects, browse content, and execute queries. Users inside an organization might have access to a project from an organization-level role or they might be granted access to a project directly.

ListChartsInProject

List all charts in a project

path Parameters
projectUuid
required
string

The uuid of the project to get charts for

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

ListSpacesInProject

List all spaces in a project

path Parameters
projectUuid
required
string

The uuid of the project to get spaces for

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

GetProjectAccessList

Get access list for a project. This is a list of users that have been explictly granted access to the project. There may be other users that have access to the project via their organization membership.

path Parameters
projectUuid
required
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

GrantProjectAccessToUser

Grant a user access to a project

path Parameters
projectUuid
required
string
Request Body schema: application/json
sendEmail
required
boolean
role
required
string (ProjectMemberRole)
Enum: "viewer" "interactive_viewer" "editor" "developer" "admin"
email
required
string

Responses

Request samples

Content type
application/json
{
  • "sendEmail": true,
  • "role": "viewer",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

UpdateProjectAccessForUser

Update a user's access to a project

path Parameters
projectUuid
required
string
userUuid
required
string
Request Body schema: application/json
role
required
string (ProjectMemberRole)
Enum: "viewer" "interactive_viewer" "editor" "developer" "admin"

Responses

Request samples

Content type
application/json
{
  • "role": "viewer"
}

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

RevokeProjectAccessForUser

Remove a user's access to a project

path Parameters
projectUuid
required
string
userUuid
required
string

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

ValidateProject

Validate content inside a project. This will start a validation job and return the job id.

Validation jobs scan all charts and dashboards inside a project to find any broken references to metrics or dimensions that aren't available. Results are available after the job is completed.

path Parameters
projectUuid
required
string

the projectId for the validation

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

GetLatestValidationResults

Get validation results for a project. This will return the results of the latest validation job.

path Parameters
projectUuid
required
string

the projectId for the validation

query Parameters
fromSettings
boolean

boolean to know if this request is made from the settings page, for analytics

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

DeleteValidationDismiss

Deletes a single validation error.

path Parameters
validationId
required
number <double>

the projectId for the validation

Responses

Response samples

Content type
application/json
{
  • "status": "ok"
}

Spaces

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.

CreateSpaceInProject

Create a new space inside a project

path Parameters
projectUuid
required
string

The uuid of the space's parent project

Request Body schema: application/json
name
required
string
isPrivate
boolean
Array of objects (SpaceShare)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "isPrivate": true,
  • "access": [
    ]
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

GetSpace

Get details for a space in a project

path Parameters
projectUuid
required
string

The uuid of the space's parent project

spaceUuid
required
string

The uuid of the space to get

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

DeleteSpace

Delete a space from a project

path Parameters
projectUuid
required
string

The uuid of the space's parent project

spaceUuid
required
string

The uuid of the space to delete

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

UpdateSpace

Update a space in a project

path Parameters
projectUuid
required
string

The uuid of the space's parent project

spaceUuid
required
string

The uuid of the space to update

Request Body schema: application/json
name
required
string
isPrivate
required
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "isPrivate": true
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

Roles & Permissions

These routes allow users to manage roles and permissions for their organization.

https://docs.lightdash.com/references/roles

UpdateOrganizationMember

Updates the membership profile for a user in the current user's organization

path Parameters
userUuid
required
string

the uuid of the user to update

Request Body schema: application/json

the new membership profile

role
string (OrganizationMemberRole)
Enum: "member" "viewer" "interactive_viewer" "editor" "developer" "admin"

Responses

Request samples

Content type
application/json
{
  • "role": "member"
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

CreateSpaceInProject

Create a new space inside a project

path Parameters
projectUuid
required
string

The uuid of the space's parent project

Request Body schema: application/json
name
required
string
isPrivate
boolean
Array of objects (SpaceShare)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "isPrivate": true,
  • "access": [
    ]
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

GetProjectAccessList

Get access list for a project. This is a list of users that have been explictly granted access to the project. There may be other users that have access to the project via their organization membership.

path Parameters
projectUuid
required
string

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

GrantProjectAccessToUser

Grant a user access to a project

path Parameters
projectUuid
required
string
Request Body schema: application/json
sendEmail
required
boolean
role
required
string (ProjectMemberRole)
Enum: "viewer" "interactive_viewer" "editor" "developer" "admin"
email
required
string

Responses

Request samples

Content type
application/json
{
  • "sendEmail": true,
  • "role": "viewer",
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

UpdateProjectAccessForUser

Update a user's access to a project

path Parameters
projectUuid
required
string
userUuid
required
string
Request Body schema: application/json
role
required
string (ProjectMemberRole)
Enum: "viewer" "interactive_viewer" "editor" "developer" "admin"

Responses

Request samples

Content type
application/json
{
  • "role": "viewer"
}

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

RevokeProjectAccessForUser

Remove a user's access to a project

path Parameters
projectUuid
required
string
userUuid
required
string

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

UpdateSpace

Update a space in a project

path Parameters
projectUuid
required
string

The uuid of the space's parent project

spaceUuid
required
string

The uuid of the space to update

Request Body schema: application/json
name
required
string
isPrivate
required
boolean

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "isPrivate": true
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

Exports

getCsvUrl

Get a Csv

path Parameters
jobId
required
string

the jobId for the CSV

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

Integrations

getDbtCloudIntegrationSettings

Get the current dbt Cloud integration settings for a project

path Parameters
projectUuid
required
string

the uuid of the project

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

updateDbtCloudIntegrationSettings

Update the dbt Cloud integration settings for a project

path Parameters
projectUuid
required
string

the uuid of the project

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

deleteDbtCloudIntegrationSettings

Remove the dbt Cloud integration settings for a project

path Parameters
projectUuid
required
string

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

getDbtCloudMetrics

Get a list of dbt metric definitions from the dbt Cloud metadata api. The metrics are taken from the metadata from a single dbt Cloud job configured with the dbt Cloud integration settings for the project.

path Parameters
projectUuid
required
string

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

getSlackChannels

Get slack channels

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

User Groups

getGroup

Get group details

path Parameters
groupUuid
required
string

unique id of the group

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

deleteGroup

Delete a group

path Parameters
groupUuid
required
string

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

updateGroup

Update a group

path Parameters
groupUuid
required
string
Request Body schema: application/json
name
required
string

A friendly name for the group

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

addUserToGroup

Add a Lightdash user to a group

path Parameters
groupUuid
required
string

the UUID for the group to add the user to

userUuid
required
string

the UUID for the user to add to the group

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

removeUserFromGroup

Remove a user from a group

path Parameters
groupUuid
required
string

the UUID for the group to remove the user from

userUuid
required
string

the UUID for the user to remove from the group

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

getGroupMembers

View members of a group

path Parameters
groupUuid
required
string

the UUID for the group to view the members of

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

Content

getPinnedItems

Get pinned items

path Parameters
projectUuid
required
string

project uuid

pinnedListUuid
required
string

the list uuid for the pinned items

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

updatePinnedItemsOrder

Update pinned items order

path Parameters
projectUuid
required
string

project uuid

pinnedListUuid
required
string

the list uuid for the pinned items

Request Body schema: application/json

the new order of the pinned items

Array
required
object (Pick_ResourceViewItem-at-data.uuid-or-pinnedListOrder_)

From T, pick a set of properties whose keys are in the union K

type
required
string (ResourceViewItemType)
Enum: "chart" "dashboard" "space"

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

Exploring

postRunUnderlyingDataQuery

Run a query for underlying data results

path Parameters
projectUuid
required
string

The uuid of the project

exploreId
required
string

table name

Request Body schema: application/json

metricQuery for the chart to run

csvLimit
number <double>
Array of objects (AdditionalMetric)
required
Array of objects (TableCalculation)
limit
required
number <double>
required
Array of objects (SortField)
required
object
metrics
required
Array of strings (FieldId)
dimensions
required
Array of strings (FieldId)

Responses

Request samples

Content type
application/json
{
  • "csvLimit": 0,
  • "additionalMetrics": [
    ],
  • "tableCalculations": [
    ],
  • "limit": 0,
  • "sorts": [
    ],
  • "filters": {
    },
  • "metrics": [
    ],
  • "dimensions": [
    ]
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

postRunQuery

Run a query for explore

path Parameters
projectUuid
required
string

The uuid of the project

exploreId
required
string

table name

Request Body schema: application/json

metricQuery for the chart to run

csvLimit
number <double>
Array of objects (AdditionalMetric)
required
Array of objects (TableCalculation)
limit
required
number <double>
required
Array of objects (SortField)
required
object
metrics
required
Array of strings (FieldId)
dimensions
required
Array of strings (FieldId)

Responses

Request samples

Content type
application/json
{
  • "csvLimit": 0,
  • "additionalMetrics": [
    ],
  • "tableCalculations": [
    ],
  • "limit": 0,
  • "sorts": [
    ],
  • "filters": {
    },
  • "metrics": [
    ],
  • "dimensions": [
    ]
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

Charts

postChartResults

Run a query for a chart

path Parameters
chartUuid
required
string

chartUuid for the chart to run

Request Body schema: application/json
object (Filters)
object or object (FilterGroupResponse)
object or object (FilterGroupResponse)

Responses

Request samples

Content type
application/json
{
  • "filters": {
    }
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

Schedulers

getSchedulerLogs

Get scheduled logs

path Parameters
projectUuid
required
string

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

getScheduler

Get a scheduler

path Parameters
schedulerUuid
required
string

The uuid of the scheduler to update

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

updateScheduler

Update a scheduler

path Parameters
schedulerUuid
required
string

The uuid of the scheduler to update

Request Body schema: application/json

the new scheduler data

any

the new scheduler data

Responses

Request samples

Content type
application/json
null

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

deleteScheduler

Delete a scheduler

path Parameters
schedulerUuid
required
string

The uuid of the scheduler to delete

Responses

Response samples

Content type
application/json
{
  • "results": null,
  • "status": "ok"
}

getScheduledJobs

Get scheduled jobs

path Parameters
schedulerUuid
required
string

The uuid of the scheduler to update

Responses

Response samples

Content type
application/json
{
  • "results": [
    ],
  • "status": "ok"
}

getSchedulerJobStatus

Get a generic job status This method can be used when polling from the frontend

path Parameters
jobId
required
string

the jobId for the status to check

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

getShareUrl

Get a share url from a short url id

path Parameters
nanoId
required
string

the short id for the share url

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

CreateShareUrl

Given a full URL generates a short url id that can be used for sharing

Request Body schema: application/json

a full URL used to generate a short url id

path
required
string

The URL path of the full URL

params
required
string

Responses

Request samples

Content type
application/json
{
  • "path": "string",
  • "params": "string"
}

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}

SSH Keypairs

createSshKeyPair

Responses

Response samples

Content type
application/json
{
  • "results": {
    },
  • "status": "ok"
}