Reference

Types

Type	Example	Description
Boolean	true	An RFC7159 JSON boolean value.
String	"title"	An RFC7159 JSON string value.
Number	102 or 1.02E2	An RFC7159 JSON number value.
Integer	18567	An integer value formatted as an RFC7159 JSON number value.
Decimal	123.45	A decimal value formatted as an RFC7159 JSON number value.
DateTime	"2020-06-26T16:29:37Z"	The date formatted as an RFC3339 timestamp string in the UTC time zone.
Timestamp	1605732868411	Number of milliseconds since the Unix epoch (January 1, 1970 in the UTC timezone).
UUID	"110808fd-4553-4316-bccf-4f25ff59a532"	A universally unique identifier (UUID) in the canonical textual representation format.
URI	"https://lucid.app/lucidchart/328caaff-08d6-4461-bd52-bb2fbd556420/edit"	A uniform resource identifier (URI) as defined in RFC3986.
Array	["in progress"] or [1, 2, 3]	An array of values of other primitive types.
Map	Map[String,String] or Map[String,Optional[String]]	A JSON object as defined in RFC7159.
Product	"lucidchart"	See Products below.

Products

The Lucid suite contains multiple products and many APIs accept a Product parameter to dictate which to execute against. The valid Products are:

lucidchart
lucidscale
lucidspark

Status Codes and Errors

Lucid APIs use standard HTTP codes to indicate the result of the request.

Successful Responses

HTTP Status	Description
200 Ok	The request completed successfully.
201 Created	The request succeeded and the resource was created.
204 No Content	Completed successfully, but returned no response body. Often used with DELETE endpoints.

Errors

HTTP Status	Error Code	Description
400 Bad Request	unknownOperation	The requested operation is unrecognized or not supported for this resource
400 Bad Request	badRequest	Bad or malformed request
401 Unauthorized	unauthorized	The request token is missing, expired or invalid
403 Forbidden	accessForbidden	Access to this resource is forbidden
404 Not Found	notFound	Resource not found
406 Not Acceptable	invalidExportType	The requested export type is not supported
409 Conflict	alreadyExists	Entity already exists
415 Unsupported Media Type	invalidImportType	Importing the provided file type is not supported
429 Too Many Requests	tooManyRequests	The requests received have exceeded the allowed rate limit
500 Internal Server Error	internalServerError	An unknown error occurred
503 Service Unavailable		The service is down for maintenance

Examples

{
    "code": "unknownOperation",
    "message": "The requested operation is unrecognized or not supported for this resource"
}

{
    "code": "invalidExportType",
    "message": "The requested export type is not supported",
    "details": {
        "requested": "application/json",
        "supported": ["image/jpeg", "image/png"]
    },
    "requestId": "47CA40AE3BD1A335"
}

Pagination

Some API endpoints may return a large number of records in response to a query. To make handling large payloads scalable, Lucid's API uses pagination to limit the number of records returned in a response.

Every paginated endpoint takes two optional query parameters: pageSize and pageToken.

The pageSize parameter is used to indicate the maximum number of records returned per page. By default, each page will contain a maximum of 200 records. If a pageSize greater than 200 is requested, only 200 will be returned. Any endpoints that override this default will document it explicitly.

The pageToken is provided by the API response and acts as a pointer to the next set of records.

curl 'https://api.lucid.co/users?pageSize=20&pageToken=eyJvIjoiMSIsImUiOj' \
     --request 'GET' \
     --header 'Authorization: Bearer <OAuth 2.0 Access Token>' \
     --header 'Lucid-Api-Version: 1'

Responses by paginated endpoints contain a URI in the Link header called next. This URI is provided to the client to facilitate getting the next paged response and will have the same pageSize as the previous request. Page tokens are included in the next URI and should be considered opaque tokens.

Link: <https://api.lucid.co/users?pageSize=20&pageToken=eyJvIjoiMSIsImUiOjE2Mjg2OTc3OTF9>; rel="next"

Rate Limiting

To protect the stability of the platform and prevent undue stress on the system, the Lucid API has a rate limiting feature (sometimes called throttling) that restricts requests when the load exceeds a configured amount.

When the number of requests received within a period of time exceeds the allowed threshold, all API requests will respond with 429 Too Many Requests. This response will include a Retry-After header containing the number of seconds until requests will be accepted again.

The rate limits are configured high enough that they should never be hit under reasonable normal usage. However, an integration should be built to handle this response, and wait at least until the Retry-After period has passed before sending further requests. Sending additional requests during the rate-limited window could extend its duration.

Rate limits are applied based on the access token type:

Access Token Type	Rate Limit
Account Tokens	50 requests per second
User Tokens	15 requests per second

📘
The rate limit may be hit sooner when making requests to APIs that are computationally expensive.

These limits apply to each token's principle individually. For example, an integration could make 15 requests per second using one user's token and an additional 15 requests per second using another user's token. Account and user limits are handled separately, even if the user is on the account token's account. When a request gets throttled, only requests matching the same token principle will be throttled.

Response


429 Too Many Requests	with a `Retry-After` header indicating how many seconds to wait until re-attempting any request.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 3600

{
    "code": "tooManyRequests",
    "message": "You have sent too many requests in a given amount of time."
}