The Lucid Data API enables external applications to create, read, update, and delete structured data linked to Lucid documents. 50 operations across data sets, data set grants and properties, data sources (including a CSV adapter), collections, field-definition schemas, and data items addressed by id or by key. Authenticate via OAuth 2.0 with the data-service.admin scope.
openapi: 3.0.3
info:
title: Lucid Data API
version: '1.0'
description: The Lucid Data API enables external applications to create, read, update, and delete structured
data linked to Lucid documents. Use it to sync data sets, collections, and schemas between your data
sources and Lucid diagrams. Authenticate via OAuth 2.0.
contact:
name: Lucid Developer Platform
url: https://developer.lucid.co/
x-documentation: https://developer.lucid.co/reference/data-api
x-harvest:
harvested: '2026-08-01'
method: searched
source: https://lucid-developer-docs.readme.io/mcp
note: 'Assembled operation-by-operation from Lucid''s own documentation MCP server (tools list-endpoints
+ get-endpoint), which returns verbatim OpenAPI 3.0.3 fragments out of the spec Lucid uploaded to
its ReadMe hub (/branches/1.4/apis/lucid-data-api.json). Paths, operations, parameters, request bodies,
responses, components and securitySchemes are provider content, unmodified. Only the info block is
ours: ReadMe''s per-endpoint fragments omit info, so title/description are copied verbatim from the
provider''s own list-specs description for this spec.'
servers:
- url: https://data.lucid.app
tags:
- name: Rate Limits
description: Retrieve current rate limit thresholds and quotas for the authenticated user.
- name: Data Set
description: Create, retrieve, update, and delete data sets. A data set is a top-level container that
groups related data sources and their collections.
- name: Data Set Grant
description: Manage access grants on data sets to control which users or applications can read or write
data.
- name: Data Set Properties
description: Read and update metadata properties on a data set, such as display name and configuration.
- name: Data Source
description: Create, retrieve, update, and delete data sources within a data set. A data source represents
an external system whose data is synced into Lucid.
- name: Collection
description: Create, retrieve, update, and delete collections within a data source. A collection is
a named group of data items that share a common schema (similar to a database table).
- name: Collection Properties
description: Read and update metadata properties on a collection, such as display name and configuration.
- name: Schema
description: Define and retrieve the schema for a collection, specifying the fields, types, and constraints
for its data items.
- name: Data Item
description: Create, retrieve, update, and delete individual data items within a collection. A data
item is a single record conforming to the collection's schema.
paths:
/rateLimits:
get:
summary: Get Rate Limits
description: 'See what your current rate limits are.
'
operationId: getRateLimits
tags:
- Rate Limits
security:
- OAuth2:
- data-service.admin
responses:
'200':
description: OK with current limits for requesting user.
content:
application/json:
schema:
type: object
properties:
userHardRefreshInterval:
type: integer
description: Minimum number of seconds that must elapse before a hard (full) data
refresh can be triggered again.
example: 30
userSoftRefreshInterval:
type: integer
description: Minimum number of seconds that must elapse before a soft (incremental)
data refresh can be triggered again.
example: 30
userApiCallRate:
type: integer
description: Maximum number of API requests the user can make per minute.
example: 750
fileSizeLimit:
type: integer
description: Maximum file upload size in megabytes.
example: 3
required:
- userHardRefreshInterval
- userSoftRefreshInterval
- userApiCallRate
- fileSizeLimit
example:
userHardRefreshInterval: 30
userSoftRefreshInterval: 30
userApiCallRate: 750
fileSizeLimit: 3
/dataSets:
head:
summary: Get Total Data Sets Count
description: 'This endpoint returns the number of data sets a user has access to. The return value
is in the response headers as `Lucid-DataSets-Total`
'
operationId: getDataSetCount
tags:
- Data Set
security:
- OAuth2:
- data-service.admin
responses:
'200':
description: OK with lucid-datasets-total header in response
headers:
lucid-datasets-total:
description: Total number of data sets
schema:
type: integer
example: 123
get:
summary: Get All Data Sets
description: 'This endpoint returns all data sets that the user has access to. The results will
be paginated. If the number of data sets exceeds the pagination limit, links will be provided
to get the next set of results or the previous set of results (if applicable). The range of returned
values can be determined by optional start and end parameters. If the difference between the end
and start values is greater than the pagination limit, the endpoint returns data sets in the range
from start to start + pagination limit. Items in the response are determined based on their creation
order.
'
operationId: getAllDataSets
tags:
- Data Set
security:
- OAuth2:
- data-service.admin
parameters:
- name: start
in: query
description: Starting 1-based index of data sets to retreive. Defaults to 1.
required: false
schema:
type: integer
- name: end
in: query
description: Ending index of data sets to retreive. Defaults to 100.
required: false
schema:
type: integer
responses:
'200':
description: OK with paginated list of Data Set objects
content:
application/json:
schema:
type: object
properties:
dataSets:
type: array
items:
type: object
properties:
uri:
type: string
description: URI of the data set
example: https://data.lucid.app/dataSets/2168
name:
type: string
description: Name of the data set
example: Data Set Name
properties:
type: string
description: Link to get properties of the data set
example: https://data.lucid.app/dataSets/2168/properties
created:
type: string
description: Date the data set was created
example: '2021-01-01T00:00:00Z'
modified:
type: string
description: Date the data set was last modified
example: '2021-01-01T00:00:00Z'
creatorId:
type: integer
description: ID of the user who created the data set
example: 123456
dataSetGrants:
type: string
description: Link to get grants for the data set
example: https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
dataSources:
type: string
description: Link to get data sources for the data set
example: https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
required:
- uri
- name
- properties
- created
- modified
- creatorId
- dataSetGrants
- dataSources
example:
uri: https://data.lucid.app/dataSets/2168
name: Data Set Name
properties: https://data.lucid.app/dataSets/2168/properties
created: '2021-01-01'
modified: '2021-01-01T00:00:00Z'
creatorId: 123456
dataSetGrants: https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
dataSources: https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
total:
type: integer
description: Total number of data sets
example: 125
prev:
type: string
description: Link to get the previous set of data sets
example: https://data.lucid.app/dataSets?start=80&end=90
next:
type: string
description: Link to get the next set of data sets
example: https://data.lucid.app/dataSets?start=100&end=110
post:
summary: Create Data Set
description: 'Creates a new data set and a corresponding new data set grant for the user. Note that
a data set cannot be created with data sources already inside it, so data sources must be added
to a data set through either the Create Data Source endpoint or the Update Data Source endpoint.
'
operationId: createDataSet
tags:
- Data Set
security:
- OAuth2:
- data-service.admin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name to give the new data set
example: Data Set Name
properties:
type: object
additionalProperties:
type: string
description: Used to create the data set properties for the new data set.
example: null
required:
- name
example:
name: Data Set Name
properties:
Color: green
AuthoredBy: Lucidchart
responses:
'200':
description: OK with Data Set
content:
application/json:
schema:
type: object
properties:
uri:
type: string
description: URI of the data set
example: https://data.lucid.app/dataSets/2168
name:
type: string
description: Name of the data set
example: Data Set Name
properties:
type: string
description: Link to get properties of the data set
example: https://data.lucid.app/dataSets/2168/properties
created:
type: string
description: Date the data set was created
example: '2021-01-01T00:00:00Z'
modified:
type: string
description: Date the data set was last modified
example: '2021-01-01T00:00:00Z'
creatorId:
type: integer
description: ID of the user who created the data set
example: 123456
dataSetGrants:
type: string
description: Link to get grants for the data set
example: https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
dataSources:
type: string
description: Link to get data sources for the data set
example: https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
required:
- uri
- name
- properties
- created
- modified
- creatorId
- dataSetGrants
- dataSources
example:
uri: https://data.lucid.app/dataSets/2168
name: Data Set Name
properties: https://data.lucid.app/dataSets/2168/properties
created: '2021-01-01'
modified: '2021-01-01T00:00:00Z'
creatorId: 123456
dataSetGrants: https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
dataSources: https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
/dataSets/{dataSetId}:
get:
summary: Get Data Set
description: 'Gets a specific existing data set from Lucid.
'
operationId: getDataSet
tags:
- Data Set
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSetId
in: path
description: ID of data set to return
required: true
schema:
type: integer
responses:
'200':
description: OK with Data Set object
content:
application/json:
schema:
type: object
properties:
uri:
type: string
description: URI of the data set
example: https://data.lucid.app/dataSets/2168
name:
type: string
description: Name of the data set
example: Data Set Name
properties:
type: string
description: Link to get properties of the data set
example: https://data.lucid.app/dataSets/2168/properties
created:
type: string
description: Date the data set was created
example: '2021-01-01T00:00:00Z'
modified:
type: string
description: Date the data set was last modified
example: '2021-01-01T00:00:00Z'
creatorId:
type: integer
description: ID of the user who created the data set
example: 123456
dataSetGrants:
type: string
description: Link to get grants for the data set
example: https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
dataSources:
type: string
description: Link to get data sources for the data set
example: https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
required:
- uri
- name
- properties
- created
- modified
- creatorId
- dataSetGrants
- dataSources
example:
uri: https://data.lucid.app/dataSets/2168
name: Data Set Name
properties: https://data.lucid.app/dataSets/2168/properties
created: '2021-01-01T00:00:00Z'
modified: '2021-01-01T00:00:00Z'
creatorId: 123456
dataSetGrants: https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
dataSources: https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
patch:
summary: Update Data Set Name
description: 'This endpoint takes the payload specified below and updates the data set name. Updates
will only occur if the user has access to the data set. Note that the other fields in a dataset
cannot be updated through this endpoint.
'
operationId: updateDataSetName
tags:
- Data Set
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSetId
in: path
description: ID of data set to update
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
description: Name to give the existing data set
example: New Data Set Name
required:
- name
example:
name: New Data Set Name
responses:
'200':
description: OK with Data Set
content:
application/json:
schema:
type: object
properties:
uri:
type: string
description: URI of the data set
example: https://data.lucid.app/dataSets/2168
name:
type: string
description: Name of the data set
example: Data Set Name
properties:
type: string
description: Link to get properties of the data set
example: https://data.lucid.app/dataSets/2168/properties
created:
type: string
description: Date the data set was created
example: '2021-01-01T00:00:00Z'
modified:
type: string
description: Date the data set was last modified
example: '2021-01-01T00:00:00Z'
creatorId:
type: integer
description: ID of the user who created the data set
example: 123456
dataSetGrants:
type: string
description: Link to get grants for the data set
example: https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
dataSources:
type: string
description: Link to get data sources for the data set
example: https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
required:
- uri
- name
- properties
- created
- modified
- creatorId
- dataSetGrants
- dataSources
example:
uri: https://data.lucid.app/dataSets/2168
name: Data Set Name
properties: https://data.lucid.app/dataSets/2168/properties
created: '2021-01-01'
modified: '2021-01-01T00:00:00Z'
creatorId: 123456
dataSetGrants: https://data.lucid.app/dataSetGrants?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
dataSources: https://data.lucid.app/dataSources?dataSet=https%3A%2F%2Fdata.lucid.app%2FdataSets%2F2168
delete:
summary: Delete Data Set
description: 'This removes the specified data set and its associated properties. Once deleted, none
of the information can be recovered. The data sources in the set will be removed from the data
set but otherwise they will not be deleted or altered.
'
operationId: deleteDataSet
tags:
- Data Set
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSetId
in: path
description: ID of data set to delete
required: true
schema:
type: integer
responses:
'200':
description: OK
/dataSetGrants/{dataSetId}:
get:
summary: Get Data Set Grant
description: 'Gets the requested data set grant if the access tokens are valid and the user has
access to the data set. Note that the id in the URI is the number at the end of the data set grant''s
uri, not the identifier field of the object.
'
operationId: getDataSetGrant
tags:
- Data Set Grant
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSetId
in: path
description: ID of data set to return grant for
required: true
schema:
type: integer
responses:
'200':
description: OK with Data Set Grant
content:
application/json:
schema:
type: object
properties:
uri:
type: string
description: URI of the data set grant
example: https://data.lucid.app/dataSetGrants/435
dataSet:
type: string
description: Link to get the data set for the grant
example: https://data.lucid.app/dataSets/8
permissionType:
type: string
description: Type of permission granted
example: account
identifier:
type: string
description: The document id, account id, or user id matching the permission type
example: '1234'
role:
type: string
description: 'Available types are: ''edit'' and ''view'''
example: edit
required:
- uri
- dataSet
- permissionType
- identifier
- role
example:
uri: https://data.lucid.app/dataSetGrants/435
dataSet: https://data.lucid.app/dataSets/8
permissionType: account
identifier: '1234'
role: edit
delete:
summary: Delete Data Set Grant
description: 'Removes the specified data set grant ONLY if it''s not the last data set grant. There
must always be at least one data set grant for a given data set, therefore the last data set grant
cannot be deleted. A response message is returned with the result of the deletion. Note that the
id in the URI is the number at the end of the data set grant''s URI, not the identifier field
of the Data Set Grant.
'
operationId: deleteDataSetGrant
tags:
- Data Set Grant
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSetId
in: path
description: ID of data set grant to delete
required: true
schema:
type: integer
responses:
'200':
description: OK
/dataSetGrants:
get:
summary: Get All Data Set Grants
description: 'Finds and returns all data set grants for the queried data set if the user has access
to the data set.
'
operationId: getAllDataSetGrants
tags:
- Data Set Grant
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSet
in: query
description: Data set to get grants for
required: true
schema:
type: string
responses:
'200':
description: OK with array of Data Set Grant
content:
application/json:
schema:
type: array
items:
type: object
properties:
uri:
type: string
description: URI of the data set grant
example: https://data.lucid.app/dataSetGrants/435
dataSet:
type: string
description: Link to get the data set for the grant
example: https://data.lucid.app/dataSets/8
permissionType:
type: string
description: Type of permission granted
example: account
identifier:
type: string
description: The document id, account id, or user id matching the permission type
example: '1234'
role:
type: string
description: 'Available types are: ''edit'' and ''view'''
example: edit
required:
- uri
- dataSet
- permissionType
- identifier
- role
example:
uri: https://data.lucid.app/dataSetGrants/435
dataSet: https://data.lucid.app/dataSets/8
permissionType: account
identifier: '1234'
role: edit
post:
summary: Create Data Set Grant
description: 'Creates a new data set grant for the specified data set. The requesting user must
have access to the data set in order for it to succeed.
'
operationId: createDataSetGrant
tags:
- Data Set Grant
security:
- OAuth2:
- data-service.admin
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
dataSet:
type: string
description: Link to the data set to grant access to
example: https://data.lucid.app/dataSets/8
permissionType:
type: string
description: Type of permission to grant
example: account
identifier:
type: string
description: The document id, account id, or user id matching the permission type
example: '1234'
role:
type: string
description: 'Available types are: ''edit'' and ''view'''
example: edit
required:
- dataSet
- permissionType
- identifier
- role
example:
dataSet: https://data.lucid.app/dataSets/8
permissionType: account
identifier: '1234'
role: edit
responses:
'200':
description: OK with Data Set Grant
content:
application/json:
schema:
type: object
properties:
uri:
type: string
description: URI of the data set grant
example: https://data.lucid.app/dataSetGrants/435
dataSet:
type: string
description: Link to get the data set for the grant
example: https://data.lucid.app/dataSets/8
permissionType:
type: string
description: Type of permission granted
example: account
identifier:
type: string
description: The document id, account id, or user id matching the permission type
example: '1234'
role:
type: string
description: 'Available types are: ''edit'' and ''view'''
example: edit
required:
- uri
- dataSet
- permissionType
- identifier
- role
example:
uri: https://data.lucid.app/dataSetGrants/435
dataSet: https://data.lucid.app/dataSets/8
permissionType: account
identifier: '1234'
role: edit
/dataSets/{dataSetId}/properties:
get:
summary: Get Data Set Properties
description: 'Gets all properties for the specified data set if the user has access to the data
set.
'
operationId: getDataSetProperties
tags:
- Data Set Properties
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSetId
in: path
description: ID of data set to return properties for
required: true
schema:
type: integer
responses:
'200':
description: OK with Data Set Properties
content:
application/json:
schema:
type: object
additionalProperties:
type: string
example:
backgroundColor: blue
font: Times New Roman
patch:
summary: Update Data Set Properties
description: 'Allows a user to update the properties on a data set. This endpoint uses the supplied
values to either update existing properties or add new properties.
'
operationId: updateDataSetProperties
tags:
- Data Set Properties
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSetId
in: path
description: ID of data set to update properties for
required: true
schema:
type: integer
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties:
type: string
example:
backgroundColor: blue
font: Times New Roman
responses:
'200':
description: OK with affected Data Set Properties
content:
application/json:
schema:
type: object
additionalProperties:
type: string
example:
backgroundColor: blue
font: Times New Roman
delete:
summary: Delete Data Set Properties
description: 'Removes only the properties provided in the query parameter. The deleted properties
cannot be undone. The deletion will only occur if the user has access to the data set.
'
operationId: deleteDataSetProperties
tags:
- Data Set Properties
security:
- OAuth2:
- data-service.admin
parameters:
- name: dataSetId
in: path
description: ID of data set to delete properties for
required: true
schema:
type: integer
- name: properties
in: query
description: List of properties to remove from specified data set
required: false
schema:
type: array
items:
type: string
responses:
'200':
description: OK
/dataSources:
head:
summary: Get Total Data Sources Count
description: 'This endpoint returns the number of data sources a user has access to. The return
value is in the response headers as `Lucid-DataSources-Total`
'
operationId: getDataSourceCount
tags:
# --- truncated at 32 KB (155 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lucid/refs/heads/main/openapi/lucid-data-api-openapi.yml