> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qlty.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

<Warning>
  The Qlty API is currently in an early access period and subject to change without warning.
</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](https://qlty.sh/user/settings/tokens)

Authentication is performed either by HTTP Basic Auth or by passing the token in the `Authorization` header. To use HTTP Basic Auth, you must pass the token as the username and leave the password blank. For example:

```bash lines theme={"system"}
curl -u <token>: https://api.qlty.sh/...
```

Alternatively, you can pass the token in the `Authorization` header:

```bash lines theme={"system"}
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.

```json Error response lines theme={"system"}
{
    "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 is used to specify the number of items to return per page. The `page[offset]` query parameter is used to specify the offset of the first item to return.

When additional records are available, the response will include a `meta` key with a `hasMore: true` property.

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

```json Pagination response lines theme={"system"}
{
    "data": [
        {
            "id": "1",
            "name": "John Doe"
        },
        {
            "id": "2",
            "name": "Jane Doe"
        }
    ],
    "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 1,000 requests per hour per workspace.

## 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.