General endpoint design

The Public API returns json responses in a general format.

{
  "meta": {
  },
  "data": {
  },
  "errors": [
    {
      "code": "<error_code>",
      "message": "<error_message>"
    }
  ]
}

The response body will contain a json object in the body optionally containing the following parts:

Meta

If the response has relevant meta information it will be encapsulated within the meta key. Examples are optional success messages

{
  "meta": {
    "message": "Resource succesfully created",
  }
}

or linked resources (pagination).

{
  "meta": {
    "prevCursor": "<cursor_token>",
    "nextCursor": "<cursor_token>"
  }
}

Pagination

Cursor based pagination is used for large responses containing multiple resources of the same type. The API will return a prevCursor and nextCursor value when needed in the meta information containing a token. This token can be added to the request as a query parameter to fetch the previous or next page.

/v1/patients?cursor=<cursor_token>

In addition, the optional perPage query parameter can be used to control the number of resources returned in a single page.

Type	Value	Default
integer	1-200	50

/v1/patients?perPage=100

The request will return up to 100 patients per page, instead of the default 50.

Data

When requesting resources the API will return a data key in the response, the value of this can be either an object or an array depending on the type of resource that was requested (multiple or single entities).

{
  "data": [
    {
      "email": "demo@example.com",
      ...
    },
    ...
  ]
}

Errors

If the request results in errors these will be returned under the errors key. Errors are optional but if present will always be in the form of an array containing one or more errors.

{
    "errors": [
        {
            "code": "validation",
            "message": "Start date must be ISO8601 formatted",
            "attribute": "startDate"
        },
        {
             "code": "account_inactive",
             "message": "Your account is not active"
        }
    ]
}

Error objects will always contain a code which is a string in a machine friendly format which you can use to identify and handle specific errors. A human readable message will also be present in the error object.

Authorization

Access to the API is role-based. Each API key is tied to a user with a specific role, which determines what resources can be accessed and to what scope.

Role	Description
`HC_ADMIN`	Healthcare administrator. Can read and write all resources within their organization.
`HC_VIEW_ALL`	Read-only healthcare role. Can read all resources within their organization.
`HC_PRIMARY` / `HC_SECONDARY`	Caregiver accounts. Can access resources within their own groups only.
`FC_ADMIN`	Superadmin. Can access all resources across all organizations.
`PATIENT`	Can only access their own resources.

Resources outside of a user's scope return 404 Not Found rather than 403 Forbidden, to avoid exposing whether a resource exists outside the caller's scope.

Rate Limiting

The Luscii Public API enforces a limit of 1000 requests per minute. When a request is made, the response will include the X-RateLimit-Limit and X-RateLimit-Remaining headers indicating your current usage. If you exceed the limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

Versioning & Backward Compatibility

The Luscii Public API is versioned via the base URL (e.g. /v1/). We strive to keep the API stable and have no short or mid-term plans to introduce a new major version.

Under the current version, we may introduce non-breaking changes without prior notice. The following changes are considered non-breaking:

Adding new endpoints
Adding new fields to request or response bodies
Making previously required fields optional
Adding new optional query parameters or headers
Fixing unintended behaviour (bugs)

Breaking changes — such as removing or renaming endpoints, fields, or parameters — will only be introduced in a new major version of the API, with advance notice and a migration period.

Technical reference

A full list of endpoints can be found in our Technical reference