Conventions

Schemas

All data is sent and received as JSON objects.

Field Formats

Fields are named in lowercase and in snake case (ex: my_parameter).

Type	Format	Example
integer	number	`{"field_name": 234}`
float	number	`{"field_name": 234.56}`
string	string	`{"field_name": "text"}`
boolean	json boolean	`{"field_name": true}`
null	json null	`{"field_name": null}`
datetime	ISO-8601	`{"field_name": "2016-10-03T12:34:56+01:00"}`
uuid	base57 (shortuuid)	`{"field_name": "UNDTMBovdue9tFWfhamnDM"}`

Datetime Formats

Datetime fields use ISO-8601 format: YYYY-MM-DDThh:mm[:ss[.uuuuuu]][+HH:MM|-HH:MM|Z]

{"date": "2016-10-03"}
{"time": "12:34:56"}
{"datetime": "2016-10-03T12:34:56"}
{"datetime_tz": "2016-10-03T12:34:56+01:00"}
{"datetime_micro": "2016-10-03T12:34:56.123"}

Request Headers

All API requests must include:

Header	Value	Required
`Authorization`	`Bearer <access_token>`	yes
`Content-Type`	`application/json`	for POST, PUT, PATCH requests
`Accept`	`application/json`	recommended

See Authentication for how to obtain an access token.

Parameters

Many API methods take optional parameters. For GET and DELETE requests, any parameters not specified as a segment in the path can be passed as an HTTP query string parameter.

For POST and PUT requests, parameters not included in the URL should be encoded as JSON with a Content-Type of application/json.

The formatting used is the same as for fields.

Server Hosts

Production environments currently operate from the application hostname:

LucidSource: https://source.lucidgreen.io
LucidRetail: https://retail.lucidgreen.io

Testing environments are available, and will be provided for all integrations:

LucidSource: https://source-test.lucidgreen.io
LucidRetail: https://retail-test.lucidgreen.io

Test environments may become unusable or unavailable from time to time as they are upgraded and new services are tested. If you have any issues with connectivity, please contact us using the instructions provided in Contact and Support.

API Versioning

API versions are included in the URL path (e.g., /api/v1.5/products/). Current versions:

Product	Current Version
LucidSource	v1.5
LucidRetail	v1.2

New API versions are introduced for breaking changes. Existing versions remain available during a deprecation period. Non-breaking additions (new fields, new endpoints) are added to the current version without a version bump.

Rate Limiting

All API endpoints are subject to rate limiting. Exceeding the limit returns a 429 Too Many Requests response with a Retry-After header.

Product	Rate Limit
LucidSource	60 requests/minute
LucidRetail	1,000 requests/minute (authenticated)

For details on handling rate limits, see LucidSource Rate Limits and LucidRetail Rate Limits.