Examples

Introduction

Our API uses resource-oriented URLs that leverage built in features of HTTP, like authentication, verbs and response codes.
All request and response bodies are JSON encoded, including error responses.
Any off-the-shelf HTTP client can be used to communicate with the API.

We believe an API is a user interface for a developer - accordingly, we've made sure our API can be easily explored from the browser!

Changes

This is a versionless API.
Advance notification of breaking changes will be available in this document and will be sent by email to our developer mailing list.
Please contact us at support@lucidmeetings.com to connect with the team.

Authentication

This API is authenticated using an application-defined, user-specific API token over HTTPS.
Any requests over plain HTTP will fail.

The API tokens can be either Read-Only or Read/Write.
A Read-Only token restricts the API caller to the GET, HEAD, and OPTIONS methods.
The Read-Write tokens are "full access" tokens that allow the API caller to modify data on behalf of the user.

Requests

The base URL of the API is https://site.lucidmeetings.com/lucid/api/v1 where site should be replaced with your site subdomain.
For Lucid Meetings on-demand customers, the base URL is https://meet.lucidmeetings.com/lucid/api/v1 .

JSON Bodies

All POST, PUT, and PATCH requests are JSON encoded and must have have content type of application/json , or the API will return a 415 Unsupported Media Type status code.

HTTP Verbs

OPTIONS - To retrieve the set of allowable verbs for the resource and requestor

HEAD - To retrieve the HTTP headers for a resource or a collection of resources

GET - To retrieve a resource or a collection of resources

POST - To create a resource

PATCH - To modify a resource

PUT - To set a resource

DELETE - To delete a resource

PATCH Support For Incremental Updates

The Lucid Meetings API supports both PATCH and PUT methods for updating its resources.
The PATCH method performs partial updates via instructions
that indicate which fields should be modified. For Lucid Meetings resources, all instructions are implicitly
"REPLACE", with the field names and replacement values represented as key : value pairs.

{ "email" : "new.email@example.org" }

Limited HTTP Clients

If you are using an HTTP client that doesn't support PUT, PATCH or DELETE requests, send a POST request with an X-HTTP-Method-Override header specifying the desired verb.

Rate Limiting

The API is rate limited to 100 credits per minute for a single user.
A request is typically worth 1 credit.
However, embedding can increase the the amount of required credits for a request.
All responses include headers describing the current rate limit status:

Field Types

Most resource fields are typed as basic types, such as plain text , html , email address , enum , integer , boolean , etc.
In addition to these basic types, the Lucid Meetings API presents some data as timestamps or tuples that include both the raw
value and a more readily usable or display-ready value. This is essentially a light form of embedding.

Timestamps

Internally, the application stores all dates and times as Unix timestamps,
deferring conversion to the user's local timezone and language as a matter of the user interface. For programmer convenience,
we present timestamps as a tuple containing both the Unix timestamp (value) and an ISO 8601 date/time represenation.
The ISO 8601 format is a bit more user friendly and is compatible with a variety of API client usage scenarios.

The API can use either format when processing dates and times, though internally we always convert the ISO 8601 values to
Unix timestamps via strtotime (or equivalent). The strtotime() conversion also accepts
Relative Formats, such as "today",
"tomorrow", "next week", etc.

Tuples

Internally, the application uses integer IDs throughout as either references or as tokens associated with
display values for named properties. All named properties are translatable and subject to change in the application
interfaces. For programmer convenience, we strive to include both the reference ID and a display value when presenting
coded fields.

When dealing with the field programmatically, we use the ID portion of the tuple.
For example, role_id, member_id, organization_id.
To reduce API round trips, we also provide the translated (if available) display value for the reference or field constant value.
While this breaks with resource presentation simplicity, ready access to the display value has proved to be a useful tradeoff.

Enveloping

If your HTTP client makes it difficult to read status codes or headers, we can package everything neatly into the response body.
Just include envelope=true as a request parameter and the API will always return a 200 HTTP status code.
The real status, headers and response will be within the body.

Sorting

Some endpoints offer result sorting, triggered using the sort query parameter.
The value of sort is a comma separated list of fields to sort by.
You can specify descending sort by prepending - to a field.
Not all fields can be sorted on. The endpoint documentation will list supported sort options.

Unless otherwise specified in the endpoint doucmentation, the default sort for all endpoints is descending order of creation.

To get upcoming scheduled meetings, sorted in descending order of meeting date: