Lucid Document Access API
Create, import, copy, retrieve, update, search, export, and trash documents across the Lucid Suite, and access their contents.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/lucid-document-access-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Lucid REST Document Access 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
servers:
- url: https://api.lucid.co
tags:
- name: Document Access
description: Create, import, copy, retrieve, update, search, export, and trash documents across the Lucid Suite, and access their contents.
paths:
/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/documents:
post:
summary: Create Document
description: 'Creates a new document for the requesting user, with the specified title. Requires `title` and `product`. Optionally, a `parent` folder, `extensionBootstrapData`, or Lucid Standard Import `content` can be provided to customize the new document.
> 📘
>
> This endpoint can only create a new Lucidchart or Lucidspark document. It cannot modify an existing document''s contents.
> 📘 ##### Document Creation Location
>
> When there is no `parent` field on the request, the new document will be created in a default location depending on the authorizing token''s scopes.
>
> - If the token authorizing the request uses one of the `document.app` scopes, then the document will be created in an `app-specific folder`.
> - If one of the `document.content` scopes is used, the document will be created in the user''s ''My Documents folder''.
> - If both types of scopes are authorized on the token, the `document.content` behavior will take priority and the document will be created in the user''s ''My Documents'' folder.
> 📘 ##### Bootstrap Data for Create Document
>
> Bootstrap data can be attached to the created document to be consumed by a specific [Extension Package](https://lucid.readme.io/docs/lucid-extension-api). See [Bootstrap Data for documents created via API](https://lucid.readme.io/docs/editor-extension-data#bootstrap-data-for-documents-created-via-api) for usage.
> 📘 Standard Import
>
> When `content` is provided, it must conform to the Lucid Standard Import schema. For more information on how to use the Standard Import, refer to the extensive reference documentation [here](doc:overview-si).
>
> For examples of how to use the Standard Import, refer to the `/standard-import` folder in Lucid''s repository of [Sample Lucid REST Applications](https://github.com/lucidsoftware/sample-lucid-rest-applications/tree/main/standard-import). This repo also contains some example `.zip` Standard Import files you can reference or use in your own projects.
## Valid Authentication Methods
**API Key Grants:**
- `DocumentEdit`
**OAuth 2.0 User Token Scopes:**
- `lucidchart.document.content`
- `lucidchart.document.app.folder`
- `lucidspark.document.content`
- `lucidspark.document.app.folder`
'
operationId: createDocument
tags:
- Document Access
security:
- ApiKey:
- DocumentEdit
- OAuth2:
- lucidchart.document.content
- lucidchart.document.app.folder
- lucidspark.document.content
- lucidspark.document.app.folder
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- title
- product
properties:
title:
type: string
description: Title that should be given to the newly created document.
product:
$ref: '#/components/schemas/CreatableProduct'
parent:
type: number
description: Folder ID for the new document.
extensionBootstrapData:
$ref: '#/components/schemas/BootstrapData'
content:
$ref: '#/components/schemas/LucidStandardImportContent'
responses:
'201':
description: 'Created with Document resource containing information about the newly created document.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'400':
description: Bad Request. * `'content' and 'extensionBootstrapData' cannot both be provided` — the `content` field is mutually exclusive with `extensionBootstrapData`. * Invalid `content` JSON — the provided content does not conform to the Lucid Standard Import schema.
'403':
description: Forbidden. * if the user doesn't have access to or permissions to create within the specified parent folder. * if the token authorizing the request has the document.app scope with a specified parent folder that is outside the app folder's folder tree.
/v1/documents/create:
post:
summary: Create Document with Standard Import File
description: 'Creates a new document from a Lucid Standard Import file (`.zip` archive) uploaded as multipart/form-data. Requires `file`, `type`, and `product`. Optionally, a `title` and `parent` folder can be provided. If no `title` is provided, the new document''s title will be the imported filename.
> 📘
>
> This endpoint can only create a new Lucidchart or Lucidspark document. It cannot modify an existing document''s contents.
> 📘 ##### Document Creation Location
>
> When there is no `parent` field on the request, the new document will be created in a default location depending on the authorizing token''s scopes.
>
> - If the token authorizing the request uses one of the `document.app` scopes, then the document will be created in an `app-specific folder`.
> - If one of the `document.content` scopes is used, the document will be created in the user''s ''My Documents folder''.
> - If both types of scopes are authorized on the token, the `document.content` behavior will take priority and the document will be created in the user''s ''My Documents'' folder.
> 📘 Standard Import
>
> For more information on how to use the Standard Import, refer to the extensive reference documentation [here](doc:overview-si).
>
> For examples of how to use the Standard Import, refer to the `/standard-import` folder in Lucid''s repository of [Sample Lucid REST Applications](https://github.com/lucidsoftware/sample-lucid-rest-applications/tree/main/standard-import). This repo also contains some example `.zip` Standard Import files you can reference or use in your own projects.
## Valid Authentication Methods
**API Key Grants:**
- `DocumentEdit`
**OAuth 2.0 User Token Scopes:**
- `lucidchart.document.content`
- `lucidchart.document.app.folder`
- `lucidspark.document.content`
- `lucidspark.document.app.folder`
'
operationId: createDocumentWithStandardImport
tags:
- Document Access
security:
- ApiKey:
- DocumentEdit
- OAuth2:
- lucidchart.document.content
- lucidchart.document.app.folder
- lucidspark.document.content
- lucidspark.document.app.folder
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- type
- product
properties:
file:
type: string
format: binary
description: The Lucid Standard Import specification (`.zip` archive) from which to create the document.
type:
type: string
enum:
- x-application/vnd.lucid.standardImport
product:
$ref: '#/components/schemas/CreatableProduct'
title:
type: string
description: Title that should be given to the newly created document. If no title is specified, the document will be automatically assigned the file name.
parent:
type: number
description: Folder ID for the new document.
responses:
'201':
description: 'Created with Document resource containing information about the newly created document.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'400':
description: 'Bad Request.
* Invalid request body — the provided payload does not conform to the Lucid Standard Import schema.
'
'403':
description: 'Forbidden.
* if the user doesn''t have access to or permissions to create within the specified parent folder.
* if the token authorizing the request has the document.app scope with a specified parent folder that is outside the app folder''s folder tree.
* if the token does not have the correct scope for the import type.
'
'415':
description: Unsupported Media Type. The file type provided is not supported.
/v1/documents/import:
post:
summary: Import Document
description: 'Imports an external non-Lucid file as a new document within Lucid. The file is uploaded as multipart/form-data. Requires `file`, `type`, and `product`. Optionally, a `title` and `parent` folder can be provided. If no `title` is provided, the new document''s title will be the imported filename.
> 📘
>
> This endpoint can only create a new Lucidchart or Lucidspark document. It cannot modify an existing document''s contents.
> 📘 ##### Document Creation Location
>
> When there is no `parent` field on the request, the new document will be created in a default location depending on the authorizing token''s scopes.
>
> - If the token authorizing the request uses one of the `document.app` scopes, then the document will be created in an `app-specific folder`.
> - If one of the `document.content` scopes is used, the document will be created in the user''s ''My Documents folder''.
> - If both types of scopes are authorized on the token, the `document.content` behavior will take priority and the document will be created in the user''s ''My Documents'' folder.
> 📘 Board import
>
> - The `board` import type only accepts pdfs that are exports of digital whiteboards.
> - The `board` import type can only be authorized by users with a Lucidspark Enterprise license.
> - The `board` import type is experimental and importing the same board may produce varying results over time.
## Valid Authentication Methods
**API Key Grants:**
- `DocumentEdit`
**OAuth 2.0 User Token Scopes:**
- `lucidchart.document.content`
- `lucidchart.document.app.folder`
- `lucidspark.document.content`
- `lucidspark.document.app.folder`
'
operationId: importDocument
tags:
- Document Access
security:
- ApiKey:
- DocumentEdit
- OAuth2:
- lucidchart.document.content
- lucidchart.document.app.folder
- lucidspark.document.content
- lucidspark.document.app.folder
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
required:
- file
- type
- product
properties:
file:
type: string
format: binary
description: The file from which to import the document.
type:
type: string
enum:
- x-application/vnd.lucid.drawio
- x-application/vnd.lucid.visio
- x-application/vnd.lucid.gliffy
- x-application/vnd.lucid.board
description: 'The type of file provided for import. Supported types:
* `x-application/vnd.lucid.drawio` — draw.io files (.drawio, .xml) for Lucidchart
* `x-application/vnd.lucid.visio` — Visio files (.vsdx, .vdx) for Lucidchart
* `x-application/vnd.lucid.gliffy` — Gliffy files (.gliffy, .gon, .gxml) for Lucidchart
* `x-application/vnd.lucid.board` — Board files (.pdf) for Lucidspark
'
product:
$ref: '#/components/schemas/CreatableProduct'
title:
type: string
description: Title that should be given to the newly imported document. If no title is specified, the document will be automatically assigned the file name.
parent:
type: number
description: Folder ID for the new document.
responses:
'201':
description: 'Created with Document resource containing information about the newly imported document.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'403':
description: 'Forbidden.
* if the user doesn''t have access to or permissions to create within the specified parent folder.
* if the token authorizing the request has the document.app scope with a specified parent folder that is outside the app folder''s folder tree.
* if the token does not have the correct scope for the import type.
* if the token requesting a board import does not have a Lucidspark Enterprise License.
'
'415':
description: Unsupported Media Type. The file type provided is not supported.
/v1/documents/copy:
post:
summary: Copy Document
description: 'Copies one of the requesting user''s existing documents, with the specified title. Requires `title` and `template` (the ID of the document to copy). Optionally, a `parent` folder can be provided. Note that collaborator permissions are not transferred to the copied document.
> 📘
>
> This endpoint can only create a new Lucidchart or Lucidspark document. It cannot modify an existing document''s contents.
> 📘 ##### Document Creation Location
>
> When there is no `parent` field on the request, the new document will be created in a default location depending on the authorizing token''s scopes.
>
> - If the token authorizing the request uses one of the `document.app` scopes, then the document will be created in an `app-specific folder`.
> - If one of the `document.content` scopes is used, the document will be created in the user''s ''My Documents folder''.
> - If both types of scopes are authorized on the token, the `document.content` behavior will take priority and the document will be created in the user''s ''My Documents'' folder.
## Valid Authentication Methods
**API Key Grants:**
- `DocumentEdit`
**OAuth 2.0 User Token Scopes:**
- `lucidchart.document.content`
- `lucidchart.document.app.folder`
- `lucidspark.document.content`
- `lucidspark.document.app.folder`
'
operationId: copyDocument
tags:
- Document Access
security:
- ApiKey:
- DocumentEdit
- OAuth2:
- lucidchart.document.content
- lucidchart.document.app.folder
- lucidspark.document.content
- lucidspark.document.app.folder
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- title
- template
properties:
title:
type: string
description: Title that should be given to the copied document.
template:
type: string
format: uuid
description: ID of the document to copy.
parent:
type: number
description: Folder ID for the new document.
responses:
'201':
description: 'Created with Document resource containing information about the newly copied document.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'403':
description: 'Forbidden.
* if the user doesn''t have access to or permissions to create within the specified parent folder.
* if the user doesn''t have permissions to access the specified template to copy from.
* if the token authorizing the request has the document.app scope with a specified parent folder that is outside the app folder''s folder tree.
'
/v1/documents/{id}:
get:
summary: Get/Export Document
description: 'Retrieves information about the requested document or exports it as an image.
**Get Document:** Requires at least read-only access. Document owner information is only returned if the requesting user has view access and the document is unpublished. If published, the user must be at least a collaborator.
**Export Document:** Exports a given document in a specified image format. When exporting oversized images, the resolution may be automatically scaled down to enable performant API requests.
**Admin flow:** Account owners and document admins can access any document belonging to their account without needing a direct share by setting the `Lucid-Request-As: admin` header and authenticating with an admin scope or `DocumentAdmin` API key grant.
'
operationId: getOrExportDocument
tags:
- Document Access
security:
- ApiKey:
- DocumentReadonly
- DocumentAdmin
- OAuth2:
- lucidchart.document.content:readonly
- lucidchart.document.content:admin.readonly
- lucidchart.document.app.picker:readonly
- lucidchart.document.app.folder
- lucidscale.document.content:readonly
- lucidscale.document.content:admin.readonly
- lucidscale.document.app.picker:readonly
- lucidscale.document.app.folder
- lucidspark.document.content:readonly
- lucidspark.document.content:admin.readonly
- lucidspark.document.app.picker:readonly
- lucidspark.document.app.folder
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the document to be retrieved or exported.
example: 110808fd-4553-4316-bccf-4f25ff59a532
- name: Lucid-Request-As
in: header
required: false
description: 'If the requesting user is an account owner or document admin with the required permissions and they make the
request with the value of "admin" as this header and include an admin scope or `DocumentAdmin` API key grant,
the request will be made using their admin permissions and will succeed for any document belonging to their
account.
'
schema:
type: string
example: admin
- name: Accept
in: header
description: "When using the Export Document API, the format of the exported document is set via the `Accept` header. This header contains up to two parts, separated by a semicolon:\n * A prefix stating which type of image you would like the document exported as. Options are:\n * `image/jpeg`\n * `image/png`\n * Optionally, you can also supply the dots per inch (DPI) you want the exported image to have. If this value is not provided, a default of 160 will be used. For example:\n * `image/png;dpi=256`\n * `image/jpeg;dpi=64`"
required: false
schema:
type: string
example: image/png
- name: page
in: query
description: 1-based page index of the document to export. Defaults to the first page. Only a single page is allowed. Optional for export operation. Cannot be provided when pageId is provided.
required: false
schema:
type: number
default: 1
- name: pageId
in: query
description: Specific page of the document to export. Only a single page is allowed. Optional for export operation. Cannot be provided when page is provided.
example: J~65X_X714o2
required: false
schema:
type: string
- name: crop
in: query
description: "Specifies the crop settings for the document export. Optional for export operation. Possible values are\n * Default (no crop parameter) - Exports the entire page canvas area that contains your content. Automatically adjusts to include all items on the page, including the space between them and maintains the relative positioning and spacing of your document elements\n * `x, y, width, height` - Crop to the specified region (in pixels) on the page. Example crop=1000,300,30,7\n * Note: The region (in pixels) is accurate to the number of pixels on the canvas. The number of pixels of the outputted image will only match the crop window at a DPI of 160.\n * `content` - Crop to page content. Example crop=content"
required: false
schema:
type: string
responses:
'200':
description: OK with Document resource containing information about the requested document or the binary data in the response body for exports. The Accept header specifies the type of image for exports.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
image/png:
schema:
type: string
format: binary
'400':
description: Bad Request. More than one page and/or pageId was provided for export.
'403':
description: Forbidden. 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. The specified page or pageID could not be found for export.
'406':
description: Not Acceptable. The specified image type is not supported for export.
'429':
description: Too Many Requests. If the account makes more than 75 requests in 5 seconds.
patch:
summary: Update Document
description: 'Updates properties of an existing document. Supports partial updates via JSON for title, parent, and classification.
Supports moving documents into (but not out of) repositories by providing a repo_-prefixed repository ID as the parent.
'
operationId: updateDocument
tags:
- Document Access
security:
- OAuth2:
- lucidchart.document.content
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the document to update.
example: 110808fd-4553-4316-bccf-4f25ff59a532
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PatchDocumentRequestBody'
responses:
'200':
description: OK with Document resource containing information about the updated document.
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'400':
description: Bad Request. * Title must be non-empty when included. * Title must be at most 300 characters. * Title must not start or end with whitespace. * Invalid parent ID. Must be either a string prefixed with repo_ (for repositories) or a number. * Custom tag values must be non-empty when included. * Custom tag values must not start or end with whitespace. * Classification ID must either be null or an existing classification ID.
'403':
description: Forbidden. The app making the request does not have permission to the document, or the document does not exist.
'409':
description: Conflict. A conflict occurred when saving the document.
/v1/documents/{id}/trash:
post:
summary: Trash Document
description: 'Moves the specified document to the trash for the requesting user.
If the document is shared or part of a team folder, other users will still have access to the document. Requires the user to be the owner of the requested document or have the appropriate team folder permissions.
'
operationId: trashDocument
tags:
- Document Access
security:
- ApiKey:
- DocumentEdit
- OAuth2:
- lucidchart.document.content
- lucidchart.document.app.folder
- lucidscale.document.content
- lucidscale.document.app.folder
- lucidspark.document.content
- lucidspark.document.app.folder
parameters:
- name: id
in: path
required: true
schema:
type: string
format: uuid
description: ID of the document to be moved to the trash.
example: 110808fd-4553-4316-bccf-4f25ff59a532
responses:
'204':
description: No Content when the document is successfully moved into the trash or is already trashed.
'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.
/v1/documents/search:
post:
summary: Search Documents
operationId: searchDocuments
tags:
- Document Access
security:
- ApiKey:
- DocumentReadonly
- OAuth2:
- lucidchart.document.content:readonly
- lucidscale.document.content:readonly
- lucidspark.document.content:readonly
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
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
createdStartTime:
type: string
format: date-time
default: '0001-01-01T00:00:00Z'
description: Date and time to filter documents that have been created after. Default value assumes the beginning of time.
createdEndTime:
type: string
format: date-time
default: '9999-12-31T23:59:59Z'
description: Date and time to filter documents that have been c
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/lucid/refs/heads/main/openapi/lucid-document-access-api-openapi.yml