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, Lucid APIs may return 429 Too Many Requests when requests are throttled. Integrations should be built to handle this response.

Some endpoints have individual limits, which are described on their individual reference pages. These limits may be shared across requests from the same account, including requests made with different credentials. Related operations may also share limits.

Handling throttled requests

If the response includes a Retry-After header, wait at least the indicated number of seconds before retrying. If the header is absent, consider using exponential backoff; wait before retrying, then increase the delay after each consecutive 429 response. Limit the number of retries.

A retry may also be throttled. Continue to respect any returned Retry-After value, and avoid immediately repeating failed requests.

Example response

The following illustrates a throttling response. The retry interval is an example; use the value returned with your 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."
}

Long-Running Jobs

There are certain API endpoints that are designed with an asynchronous flow to handle potentially long-running actions.

For each action, there are two corresponding endpoints:

1. A job request endpoint
2. A status request endpoint

The job request endpoint is used to initiate a long-running job to be run. Upon success, these endpoints will return a unique job ID. These endpoints may also return relevant upfront information, listed in the specific endpoint's documentation.

The status request endpoint is used to track the progress of a long-running job via the job ID returned from the job request endpoint, which can take one of four values:

Upon success, the status request endpoint will also return the result of the job in the response. The specific schema varies by endpoint and is documented in the action-specific status endpoint.

Jobs are retained for 30 days from initial request. By default, subsequent identical job requests will not re-run the job, but instead return the existing job while extending its expiration to 30 days after last request. Status requests do not affect expiration in any way.

If the intention is to run the same job multiple times, include an Idempotency-Key header with both requests and use a different value between the two of them. These headers are limited to 256 characters in length and we recommend using the UUID format for uniqueness, but there is no strict expected format.