# REST API Documentation

This is the official API documentation for logistic.cloud.

# General

Request payloads to logistic.cloud must be sent as valid JSON with a mandatory Content-Type: application/json header. Responses are also sent as JSON.
All requests must be authenticated with an API key
Lists are paginated
Dates will always be returned in UTC

# Versioning

The API implements URL-based versioning. The table below lists the currently supported versions. If you try to access a version that is no longer supported, the API will return a 404 Not Found status.

Version	Description
v1-beta	The latest version.

# Endpoints and requests

The API endpoints are organized by resource type. All endpoints follow this pattern: https://{domain}.logistic.cloud/api/{version}/{resource}

We support the following request types:

POST - Create a new resource
GET - Retrieves a single or multiple resources
PUT - Replaces a resource
DELETE - Deletes a resource

# Authentication

To authenticate against the API you need to add the header X-Api-Key: <your api key> to the request. The API key has a dedicated lifetime and permission scopes to allow you to access resource endpoints.

You can get your API key from the system administrator. If you have access to the logistic.cloud website and the required permission scopes, you can get the API key by creating a new App for the customer. You can configure the API key lifetime and permission scopes for each App.

# Rate Limiting

You can expect to be able to fire 1 request per second. If you exceed this limit, the server will respond with 429 Too Many Requests.

# Pagination

Filtered responses are paginated with a common default of 50 items per page. The maximum page size is 250. The HTTP response header returns the page index, the page size and the total number of items.

X-Page – 0
X-PageSize – 50
X-Total – 452

# Permission Scopes

A permission scope allows you to access a resource endpoint. If the scope is not set the response returns a 403 Forbidden status.

# Errors and HTTP status codes

The logistic.cloud API largely conforms to the general HTTP status codes.

Here are the most common errors you will see:

400 BadRequest - Check for errors in the problem details response body
401 Unauthorized - Check the Authentication section
403 Forbidden - Check the Permissions section
404 Not Found - Check that the resource exists (maybe it was deleted in the meantime)
429 Too Many Requests - Check the Rate Limiting section

You can always expect a Problem Details json as the response body. For example:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.5", 
  "title": "Not Found", 
  "status": 404,
  "instance": "/api/articles",
  "traceId": "0HN4579FEF7G2:00000004" 
}

In the case of 400 BadRequest we provide additional information such as the detail value, which describes the problem in general, and the optional error attribute, which describes the error more specifically.

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Create order",
  "status": 400,
  "detail": "The request body contains invalid data to create an order.",
  "instance": "/api/orders",
  "errors": {
    "lineItems[0].quantity": [
      "The quantity must be greater than 0."
    ]
  },
  "traceId": "0HN4579FEF7G2:00000004"
}