Getting Started

API Reference

The API Reference provides full documentation of all available endpoints and fields. It includes our most detailed technical documentation and should serve as your primary point of reference when using the API.

Authentication

The LeafLink API uses JWT tokens for authentication. JWT's a short lived, cryptographically secured tokens. Theses tokens should be kept secret as they can be used to access your LeafLink data.

Tokens are passed via bearer auth in request headers:

curl --header "Authorization: Bearer <YOUR_JWT>" https://api.leaflink.com/<PATH>

Unauthenticated requests will fail and return a 401 Unauthorized code.

Getting Tokens

Please reach out to our Support Team to get access to the LeafLink API.

Pagination

All "list" APIs support pagination, these are GET requests to endpoints which provide a collection of resources. Pagination is done with three parameters: page, page_size, and ordering.

Parameters

ParameterTypeDescription
pageintThe page in the collection to return. Defaults to 1.
page_sizeintThe number of items to include per page. Defaults to 50.
orderingstrThe attribute of the collection's item type to use for ordering.

Page

If an invalid page parameter is given, the API will return a 404 Not Found code. Valid page values are greater than 1 and less than or equal to the greatest page for the collection. 0 and non-numbers are invalid.

Page Size

The LeafLink API defaults to 50 items per page. A minimum of 1 and maximum of 500 may be requested. Anything else is invalid and a 404 Not Found code will be returned.

Ordering

Ordering can be specified for each collection, the default order of pagination is dependent on the collection. The value of the ordering parameter is the name of an attribute on the collection's item type. Providing just the attribute name is ascending order, prepending the attribute name with a dash(-) is descending order.

Example

Say a Product item type has an attribute called created_date.

  • Ascending Order: ?ordering=created_date
  • Descending Order: ?ordering=-created_date

List Response Attributes

The response of a list API is always a single page of zero(0) or more resources of the same type along with some pagination metadata attributes.

AttributeTypeDescription
countintA zero or positive number of the total number of items in the collection.
nextstr|nullIf there are addition items in the collection, this will be the URL to the next page.
previousstr|nullIf there are previous items in the collection, this will be the URL to the previous page.
resultsarray<object>An array of items from the collection.

List Response Example

{
  "count": 7,
  "next": "https://api.leaflink.com/product_categories?page=3&page_size=2",
  "previous": "https://api.leaflink.com/product_categories?page_size=2",
  "results": [
    {
      "id": 5,
      "name": "Concentrates",
      "slug": "concentrates",
      "description": "Concentrates"
    },
    {
      "id": 7,
      "name": "Edibles & Ingestibles",
      "slug": "edible",
      "description": "Edible"
    }
  ]
}

Rate Limiting

The LeafLink API is rate limited with the following:

  • 400/minute
  • 8/second

When rate limits are reached, a 429 Too Many Requests code is returned.

Rate limit headers are included in all responses:

HeaderDescription
RateLimit-LimitThe allowed limit.
RateLimit-RemainingThe number of available requests left.
RateLimit-ResetThe number of seconds until the quota is reset.
X-RateLimit-Limit-minuteThe Limit specifically for the minute window.
X-RateLimit-Remaining-minuteThe Remaining specifically for the minute window.
X-RateLimit-Limit-secondThe Limit specifically for the second window.
X-RateLimit-Remaining-secondThe Remaining specifically for the second window.

When a limit is reached the following header is included:

HeaderDescription
Retry-AfterThe number of seconds to wait before another request will be accept, from the time the response was received.

Versioning

When backwards-incompatible changes are made to the LeafLink API, a new version is released. LeafLink API versions are dates, which represented the date the API was first published. The current version is 2022-10-31.

All requests to the LeafLink API use a version. If a version is not provided, the current version is used.

To set the version on a request, use the LeafLink-Version header:

curl --header "LeafLink-Version: 2022-10-31" https://api.leaflink.com/<PATH>

Backwards-Incompatible Changes

The following changes are considered backward-incompatible:

  • Changing the name of:
    • an attribute of an item
    • query parameter
    • request/response header
  • Changing the path of an endpoint
  • Changing existing response codes of an endpoint
  • Changing the data type:
    • an item's attribute
    • a query parameter
  • Removal of any:
    • item's attribute
    • query parameter
    • request/response header
  • Removal of an endpoint
  • Addition of a new required:
    • item attribute
    • query parameter
    • request header
Last Updated: