# API

Lorx's HTTP API: where it is, how to authenticate, errors, paging, and the OpenAPI document.

Everything the web app and bit do goes through the same API. It lives at:

```
https://git.lorx.space/api/v1
```

The whole API is described by an OpenAPI document at [`/api/v1/openapi.json`](https://git.lorx.space/api/v1/openapi.json). Generate a client from it, or read it to see every endpoint, request and response.

## Authenticate

Send a personal access token (see [Access tokens](/docs/account/tokens)) as a bearer token:

```sh
curl -H "Authorization: Bearer $LORX_TOKEN" https://git.lorx.space/api/v1/me
```

A request with a token needs nothing else. (The web app authenticates with a session cookie instead, and sends a CSRF token with every change.)

## Errors

An error has a status code and a body like this:

```json
{ "error": { "code": "validation_failed", "message": "Check the highlighted fields.", "request_id": "req_…", "fields": { "name": "…" } } }
```

`code` is stable, for your code to match on; `message` is for people. Quote `request_id` if you report a problem.

## Paging

Lists answer a page at a time. Most say `next_cursor`: pass it back as `?cursor=` for the next page, and stop when it is `null`. Runs (newest first by number) and an account's activity (newest first by time) say `next_before` instead: pass it back as `?before=`. Each list's parameters are in the OpenAPI document.

## A few calls to start with

| | Call |
|---|---|
| Who you are | `GET /me` |
| An account's repositories | `GET /users/{username}/repos` |
| Create a repository | `POST /repos` |
| A repository | `GET /repos/{owner}/{repo}` |
| A file | `GET /repos/{owner}/{repo}/raw?ref=main&path=README.md` |
| Change requests | `GET /repos/{owner}/{repo}/crs` |
| Runs | `GET /repos/{owner}/{repo}/runs` |