Introduction

The Qlty API is currently in an early access period and subject to change without warning.

The Qlty API is organized around REST. The API provides predictable, resource-oriented URLs, accepts JSON-encoded request bodies, and returns JSON-encoded responses. We strive to make use of standard HTTP response codes, authentication, and verbs.

Authentication

The Qlty API uses tokens to authenticate requests. You can generate an API token through your user settings at https://qlty.sh/user/settings/tokens Authentication is performed by passing the token as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer <token>" https://api.qlty.sh/...

All API requests must be made over HTTPS. Calls made over plain HTTP or without authentication will fail.

Errors

Qlty uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). Codes in the 5xx range indicate an error with Qlty’s server.

Code	Status	Description
200	OK	The request was successful.
400	Bad Request	The request was invalid, often due to a missing input.
401	Unauthorized	Authentication failed.
403	Forbidden	The API token does not have permission to access the resource.
404	Not Found	The requested resource was not found.
429	Too Many Requests	Too many API requests were sent in too short of a period.
500, 502, 503, 504	Server Error	An unexpected error occurred on the server.

Errors are returned in the errors key of the response.

Error response

{
    "errors": [
        {
            "status": "400",
            "title": "Bad Request",
            "detail": "The request was invalid."
        }
    ]
}

Pagination

Many list API endpoints return paginated results. The Qlty API uses offset-based pagination. The page[limit] query parameter specifies the number of items to return per page. It defaults to 20 and may not exceed 100. The page[offset] query parameter specifies the offset of the first item to return, and defaults to 0. When additional records are available, the response will include a meta key with a hasMore: true property.

curl -X GET "https://api.qlty.sh/workspaces?page[limit]=2&page[offset]=0" \
    -H "Authorization: Bearer <token>"

Pagination response

{
    "data": [
        {
            "id": "01998c1e-0000-7000-8000-000000000001",
            "key": "acme"
        },
        {
            "id": "01998c1e-0000-7000-8000-000000000002",
            "key": "globex"
        }
    ],
    "meta": {
        "hasMore": true
    }
}

Rate Limiting

Qlty uses rate limiting to ensure that the API is not overwhelmed by too many requests. If you exceed the rate limit, you will receive a 429 Too Many Requests response. The rate limit is measured in units, not raw request counts. Most requests cost a single unit, but some endpoints that return larger or more expensive results cost more. By default, the limit is 5,000 units per hour, applied as a fixed window. Requests to workspace and project endpoints count against a per-workspace limit, and requests to user endpoints count against a per-user limit. Contact support if you need a higher rate limit. Responses include headers reporting your current rate limit usage:

Header	Description
`x-ratelimit-limit`	Maximum number of units allowed in the current window
`x-ratelimit-remaining`	Number of units remaining in the current window
`x-ratelimit-used`	Number of units used in the current window
`x-ratelimit-reset`	Unix timestamp (in seconds) when the rate limit window resets

You can also check your current rate limit status without consuming any of your limit by calling the GET /rate_limit endpoint.

Versioning

The Qlty API does not currently have a versioning scheme. Today, all endpoints are available at https://api.qlty.sh/. Prior to the general availability of the API, we are evaluating a versioning scheme that will allow us to make breaking changes without affecting existing users.

API Overview

Endpoints

Authentication

Errors

Rate Limiting

Versioning

​Authentication

​Errors

​Pagination

​Rate Limiting

​Versioning

Authentication

Errors

Pagination

Rate Limiting

Versioning