openapi: 3.0.3
info:
title: Lucid REST API
version: '1.0'
description: The Lucid REST API provides programmatic access to manage documents, users, folders, sharing,
licensing, and audit logs across the Lucid Suite (Lucidchart, Lucidspark, and Lucidscale). Authenticate
via OAuth 2.0 or API key.
contact:
name: Lucid Developer Platform
url: https://developer.lucid.co/
x-documentation: https://developer.lucid.co/reference/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-rest-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://api.lucid.co
tags:
- name: OAuth 2.0 Tokens
description: Create, refresh, introspect, and revoke OAuth 2.0 access tokens used to authenticate API
requests on behalf of a user.
- name: Accounts
description: Retrieve information about the authenticated Lucid account.
- name: Document Access
description: Create, import, copy, retrieve, update, search, export, and trash documents across the
Lucid Suite, and access their contents.
- name: Legal Holds
description: Create and manage legal holds on a Lucid account. Legal holds prevent documents from being
permanently deleted for users placed on hold.
- name: Documents Collaboration
description: Manage user and team collaborator access on individual documents, including granting, updating,
and revoking collaboration roles.
- name: Folders Collaboration
description: Manage user, group, and team collaborator access on folders, including granting, updating,
and revoking collaboration roles.
- name: Document Embedding
description: Generate session tokens and render the embedded viewer iframe used to display Lucid documents
in external applications.
- name: Folders
description: Create, retrieve, update, search, trash, and restore folders. Includes listing folder contents
and root folder navigation.
- name: Documents Sharing
description: Create, retrieve, update, and delete share links for documents to control external access.
- name: Folders Sharing
description: Create, retrieve, update, and delete share links for folders to control external access.
- name: Transfer Content
description: Transfer ownership of a user's documents, folders, custom shape libraries, and Lucidscale
objects to another user within the same account.
- name: Users
description: Retrieve, create, and search for users within the authenticated account. Includes user
profile access.
- name: Unfurling
description: Retrieve metadata for Lucid document links to power rich previews, and serve direct iframe
embeds for Lucid documents in external applications.
- name: Embedding Utils
description: Create, retrieve, delete, and change the version of embed instances on a document.
- name: Document Picker
description: Generate tokens and render an embedded document picker that lets users select Lucid documents
from within your application.
- name: Audit Logs
description: Retrieve audit log events that record user and admin activity across the Lucid account.
- name: Teams
description: Create, retrieve, update, archive, and restore teams. Manage team membership by adding
and removing users.
- name: Cloud
description: Manage cloud infrastructure credentials, data sources, and architecture diagrams for AWS,
Azure, and Google Cloud.
- name: Repositories
description: Create and manage shared document repositories. Control repository membership by adding
and removing users and groups.
- name: Document Comments
description: Retrieve comment threads on a document, list comments within a thread, and post new comments
to an existing thread.
- name: Subscriptions
description: List and retrieve product subscriptions on the account.
- name: Licenses
description: View and manage product licenses assigned to users within a subscription.
paths:
/v1/oauth2/token:
post:
summary: Create or Refresh Access Token
operationId: createOrRefreshAccessToken
tags:
- OAuth 2.0 Tokens
security:
- OAuth2: []
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- type: object
required:
- code
- client_id
- client_secret
- grant_type
- redirect_uri
properties:
code:
type: string
description: The authorization code.
client_id:
type: string
description: The client ID.
client_secret:
type: string
description: The client secret.
grant_type:
type: string
description: Value is always "authorization_code".
redirect_uri:
type: string
description: The redirect URI used to get the authorization code.
- type: object
required:
- refresh_token
- client_id
- client_secret
- grant_type
properties:
refresh_token:
type: string
description: The current refresh token.
client_id:
type: string
description: The client ID.
client_secret:
type: string
description: The client secret.
grant_type:
type: string
description: Value is always "refresh_token".
responses:
'200':
description: OK application/json with the access token and refresh token (if the offline_access
scope was included for creating access token).
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth2Token'
'401':
description: Unauthorized if the client credentials are invalid.
/v1/oauth2/token/introspect:
post:
summary: Introspect Access Token
operationId: introspectAccessToken
tags:
- OAuth 2.0 Tokens
security:
- OAuth2: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- client_id
- client_secret
- token
properties:
client_id:
type: string
description: The client ID.
client_secret:
type: string
description: The client secret.
token:
type: string
description: The token to inspect.
responses:
'200':
description: OK with information about the token, as specified in OAuth2 Introspect Token
content:
application/json:
schema:
$ref: '#/components/schemas/OAuth2IntrospectToken'
'401':
description: Unauthorized if the client credentials are invalid.
/v1/oauth2/token/revoke:
post:
summary: Revoke Access Token
description: Regardless of which token is revoked, all tokens from that authorization grant will
become invalid.
operationId: revokeAccessToken
tags:
- OAuth 2.0 Tokens
security:
- OAuth2: []
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- client_id
- client_secret
- token
properties:
client_id:
type: string
description: The client ID.
client_secret:
type: string
description: The client secret.
token:
type: string
description: The token to revoke.
responses:
'200':
description: OK if the client credentials are valid.
'401':
description: Unauthorized if the client credentials are invalid.
/v1/accounts/me:
get:
summary: Get Account Information
description: Retrieves basic information about the authenticated account.
operationId: getAccountInformation
tags:
- Accounts
security:
- ApiKey:
- AccountReadonly
- OAuth2:
- account.info
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/AccountInformationResource'
'403':
description: Forbidden
/v1/accounts/me/classifications:
get:
summary: Get Classifications
description: Returns the paginated list of classifications configured for the authenticated account.
Deleted classifications are excluded from results.
operationId: getClassifications
tags:
- Accounts
security:
- ApiKey:
- AccountReadonly
- OAuth2:
- account.info
responses:
'200':
description: OK. Returns a list of classifications for the account.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Classification'
'403':
description: Forbidden. Token does not have the required scope.
/v1/accounts/me/documents/search:
post:
summary: Search Account Documents
description: Returns a list of all documents belonging to the requesting user's account, sorted
by created date. This API is exclusive to Enterprise Shield accounts. The endpoint supports pagination
and has a per-account rate limit of 300 requests per 5 seconds.
operationId: SearchAccountDocuments
tags:
- Document Access
security:
- ApiKey:
- DocumentAdmin
- OAuth2:
- lucidchart.document.content:admin.readonly
- lucidspark.document.content:admin.readonly
- lucidscale.document.content:admin.readonly
parameters:
- $ref: '#/components/parameters/RequestAs-AccountDocuments'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
userIds:
type: array
items:
type: number
description: 'When provided, limit the search to documents that at least one specified
user can access.
If no list is provided, search across the entire account.
'
ownedByUsers:
type: boolean
description: When true, search results will only include documents owned by users specified
by userIds. Ignored if no userIds are provided.
documentIds:
type: array
items:
type: string
format: uuid
description: List of documentIds to filter by.
classificationIds:
type: array
items:
type: string
format: uuid
description: List of classificationIds to filter by.
statusIds:
type: array
items:
type: number
description: List of statusIds to filter by.
createdStartTime:
type: string
format: date-time
description: Start of range to filter documents by created time.
createdEndTime:
type: string
format: date-time
description: End of range to filter documents by created time.
lastModifiedStartTime:
type: string
format: date-time
description: Start of range to filter documents by last modified time.
lastModifiedEndTime:
type: string
format: date-time
description: End of range to filter documents by last modified time.
product:
type: array
items:
$ref: '#/components/schemas/Product'
description: Array of Lucid Suite products to filter by. Default value assumes all valid
products for the given scopes.
default:
- lucidchart
- lucidscale
- lucidspark
keywords:
type: string
description: Keyword(s) to search against document content and titles. When provided,
results will be sorted by relevance to keyword search. Use quotes to search for exact
phrases (e.g. "Project X")
documentLocation:
type: string
enum:
- team folders
- users
- deleted
- repositories
description: Specify to search for documents in team folders, owned by users, deleted,
or contained within repositories
externalAccess:
type: string
enum:
- any
- external-collaborators
- external-links
description: Specify to search for documents with either “any” type of external access,
“external-collaborators”, or "external-links"
responses:
'200':
description: With paginated list of Account Documents
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/AccountDocument'
'400':
description: Bad Request if incorrect format
'403':
description: Forbidden if "product" query parameter is used and the token’s scopes do not contain
the matching readonly scope for each product, or account does not have access to the API
'429':
description: Too Many Requests if account makes more than 300 requests in 5 seconds
/v1/accounts/me/legalHolds:
post:
summary: Create Legal Hold
description: Creates a new legal hold on an Enterprise Shield account with specified parameters
including title, description, keywords, and start/end times.
operationId: createLegalHold
tags:
- Legal Holds
security:
- ApiKey:
- LegalHoldEdit
- OAuth2:
- account.legalhold
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
Title:
type: string
description: Title that should be given to the newly created legal hold. Max length
of title is 80 characters.
StartTime:
type: string
format: date-time
description: Time that the legal hold should start. Must not be in the past.
EndTime:
type: string
format: date-time
description: Time that the legal hold should end. End time must be greater than or equal
to 24 hours after the start time.
Description:
type: string
description: Description that should be given to the newly created legal hold. Max length
of description is 256 characters.
Keywords:
type: string
description: 'Keyword(s) to search against document content and titles. Note: When provided,
only relevant results will be added to the legal hold. Empty strings will be treated
the same as when no keywords are provided. Max length of keywords is 400 characters.'
required:
- Title
- StartTime
- EndTime
responses:
'201':
description: With the newly created legal hold.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHold'
'400':
description: Incorrect format or invalid parameters.
'403':
description: Account does not have permission to access the API.
get:
summary: Get Legal Holds
description: Retrieves all legal holds configured for the authenticated account. The results are
paginated.
operationId: getLegalHolds
tags:
- Legal Holds
security:
- ApiKey:
- LegalHoldReadonly
- OAuth2:
- account.legalhold
- account.legalhold:readonly
responses:
'200':
description: With paginated list of legal holds.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/LegalHold'
'403':
description: Account does not have permission to access the API.
/v1/accounts/me/legalHolds/{legalHoldId}/users/add:
post:
summary: Add Legal Hold Users
description: Adds users to a specified legal hold. This action can only be performed for legal holds
that have not yet started.
operationId: addLegalHoldUsers
tags:
- Legal Holds
security:
- ApiKey:
- LegalHoldEdit
- OAuth2:
- account.legalhold
- account.legalhold.users
parameters:
- $ref: '#/components/parameters/LegalHoldIdPath'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
Users:
type: array
items:
type: number
description: List of user ids for users to be put on the specified legal hold. Users
must belong to the admin’s account. Max number of users per request is 200.
required:
- Users
responses:
'204':
description: Users were correctly added to the legal hold.
'400':
description: Incorrect format or invalid parameters.
'403':
description: Account does not have permission to access the API.
'404':
description: The specified legal hold id was not found.
/v1/accounts/me/legalHolds/{legalHoldId}/users/remove:
post:
summary: Remove Legal Hold Users
description: Removes users from a specified legal hold. This action can only be performed for legal
holds that have not yet started.
operationId: removeLegalHoldUsers
tags:
- Legal Holds
security:
- ApiKey:
- LegalHoldEdit
- OAuth2:
- account.legalhold
- account.legalhold.users
parameters:
- $ref: '#/components/parameters/LegalHoldIdPath'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
Users:
type: array
items:
type: number
description: List of user ids for users to be removed from the specified legal hold.
Users must belong to the admin’s account. Max number of users per request is 200.
required:
- Users
responses:
'204':
description: Users were correctly removed from the legal hold.
'400':
description: Incorrect format or invalid parameters.
'403':
description: Account does not have permission to access the API.
'404':
description: The specified legal hold id was not found.
/v1/accounts/me/legalHolds/{legalHoldId}:
patch:
summary: Edit Legal Hold
description: Modifies an existing legal hold, allowing changes to the title, description, and end
time. If the legal hold has not yet started, the start time and keywords can also be updated.
operationId: editLegalHold
tags:
- Legal Holds
security:
- ApiKey:
- LegalHoldEdit
- OAuth2:
- account.legalhold
parameters:
- $ref: '#/components/parameters/LegalHoldIdPath'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
Title:
type: string
description: The new title for the legal hold (the existing one will be replaced). Max
length of title is 80 characters.
StartTime:
type: string
format: date-time
description: The new time that the legal hold will begin. Must be at least 24 hours
before the end time and cannot be in the past. Cannot be changed if the legal hold
has already started.
EndTime:
type: string
format: date-time
description: The new time that the legal hold will end and documents on the legal hold
will be released. Must be at least 24 hours after the start time and cannot be in
the past.
Description:
type: string
description: The new description for the legal hold (the existing one will be replaced).
Max length of description is 256 characters.
Keywords:
type: string
description: The new keywords for the legal hold (any existing ones will be replaced).
Max length of keywords is 400 characters. Cannot be changed if the legal hold has
already started.
responses:
'200':
description: With the legal hold that was successfully modified.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHold'
'400':
description: Incorrect format or invalid parameters.
'403':
description: Account does not have permission to access the API.
'404':
description: The specified legal hold id was not found.
/v1/accounts/me/legalHolds/{legalHoldId}/release:
post:
summary: Release Legal Hold
description: Releases a legal hold specified by the legalHoldId. Once released, it may take up to
24 hours for the documents to be fully removed from the legal hold restriction.
operationId: releaseLegalHold
tags:
- Legal Holds
security:
- ApiKey:
- LegalHoldEdit
- OAuth2:
- account.legalhold
parameters:
- $ref: '#/components/parameters/LegalHoldIdPath'
responses:
'200':
description: With the legal hold that was released.
content:
application/json:
schema:
$ref: '#/components/schemas/LegalHold'
'403':
description: Account does not have permission to access the API.
'404':
description: The specified legal hold id was not found.
/v1/accounts/me/legalHolds/{legalHoldId}/users:
get:
summary: Get Legal Hold Users
description: Retrieves a paginated list of all users associated with a specified legal hold.
operationId: getLegalHoldUsers
tags:
- Legal Holds
security:
- ApiKey:
- LegalHoldReadonly
- OAuth2:
- account.legalhold
- account.legalhold:readonly
- account.legalhold.users
- account.legalhold.users:readonly
parameters:
- $ref: '#/components/parameters/LegalHoldIdPath'
responses:
'200':
description: With paginated list of Users.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'403':
description: Account does not have permission to access the API.
'404':
description: The specified legal hold id was not found.
/v1/accounts/me/legalHoldDocuments/{legalHoldId}:
get:
summary: Get Legal Hold Documents
description: Retrieves a paginated list of all documents associated with a specified legal hold.
Documents may continue to appear for up to 24 hours after users are removed from the legal hold,
as the system processes the release asynchronously.
operationId: getLegalHoldDocuments
tags:
- Legal Holds
security:
- ApiKey:
- LegalHoldReadonly
- OAuth2:
- account.legalhold
- account.legalhold:readonly
parameters:
- $ref: '#/components/parameters/LegalHoldIdPath'
responses:
'200':
description: With paginated list of Documents.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Document'
'403':
description: Account does not have permission to access the API.
'404':
description: The specified legal hold id was not found.
/v1/documents/{id}/shares/users/{userId}:
get:
summary: Get Document User Collaborator
description: Retrieves information about a specific user's collaboration access level for a given
document, including the sharing permissions and role that the user has been granted.
operationId: getDocumentUserCollaborators
tags:
- Documents Collaboration
security:
- ApiKey:
- DocumentReadonly
- OAuth2:
- lucidchart.document.content.share.collaborator:readonly
- lucidchart.document.app.picker.share.collaborator:readonly
- lucidchart.document.app.folder
- lucidscale.document.content.share.collaborator:readonly
- lucidscale.document.app.picker.share.collaborator:readonly
- lucidscale.document.app.folder
- lucidspark.document.content.share.collaborator:readonly
- lucidspark.document.app.picker.share.collaborator:readonly
- lucidspark.document.app.folder
parameters:
- in: path
name: id
required: true
description: ID of the document.
schema:
type: string
format: uuid
example: 110808fd-4553-4316-bccf-4f25ff59a532
- in: path
name: userId
required: true
description: ID of the user to retrieve collaborator settings for.
schema:
type: number
responses:
'200':
description: OK with a Document User Collaborator Resource containing information about the
user's collaboration settings.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentUserCollaborator'
'403':
description: Forbidden if the app making the request does not have permission to the document,
or if the document has been deleted, or does not exist.
'404':
description: Not Found when a user with the specified ID can not be found or does not have collaborator
access to the document.
put:
summary: Create/Update Document User Collaborator
description: Updates the collaborator role for a user on a document. If the user did not previously
have access to the document, they will be granted access and a new collaborator record will be
created.
operationId: putDocumentUserCollaborators
tags:
- Documents Collaboration
security:
- ApiKey:
- DocumentEdit
- OAuth2:
- lucidchart.document.content.share.collaborator
- lucidchart.document.app.picker.share.collaborator
- lucidchart.document.app.folder
- lucidscale.document.content.share.collaborator
- lucidscale.document.app.picker.share.collaborator
- lucidscale.document.app.folder
- lucidspark.document.content.share.collaborator
- lucidspark.document.app.picker.share.collaborator
- lucidspark.document.app.folder
parameters:
- in: path
name: id
required: true
description: ID of the document.
schema:
type: string
format: uuid
example: 110808fd-4553-4316-bccf-4f25ff59a532
- in: path
name: userId
required: true
description: ID of the user to retrieve collaborator settings for.
schema:
type: number
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
role:
type: string
enum:
- editandshare
- edit
- comment
- view
example: comment
description: The Collaborator Role to assign to the user for this document.
responses:
'200':
description: OK when updating an existing Document User Collaborator. Contains the updated Document
User Collaborator Resource.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentUserCollaborator'
'201':
description: Created when creating a new Document User Collaborator. Contains the new Document
User Collaborator Resource.
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentUserCollaborator'
'403':
description: Forbidden if the token does not have permission to the document, or if the document
has been deleted or does not exist.
delete:
summary: Delete Document User Collaborator
description: Revokes all collaborator access to a document for the given user. The user may still
have access to the document through other means such as shared folders. Cannot be used to remove
the document owner's access.
operationId: deleteDocumentUserCollaborators
tags:
- Documents Collaboration
security:
- ApiKey:
- DocumentEdit
- OAuth2:
- lucidchart.document.content.share.collaborator
- lucidchart.document.app.picker.share.collaborator
- lucidchart.document.app.folder
- lucidscale.document.content.share.collaborator
- lucidscale.document.app.picker.share.collaborator
- lucidscale.document.app.folder
- lucidspark.document.content.share.collaborator
- lucidspark.document.app.picker.share.collaborator
- lucidspark.document.app.folder
parameters:
- in: path
name: id
required: true
description: ID of the document.
schema:
type: string
format: uuid
example: 110808fd-4553-4316-bccf-4f25ff59a532
- in: path
name: userId
required: true
description: ID of the user to retrieve collaborator sett
# --- truncated at 32 KB (388 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lucid/refs/heads/main/openapi/lucid-rest-api-openapi.yml