Types

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

Errors

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:

📘

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

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."
}