# 3. Using the API

The JSONAir API is a simple, read-only HTTP API. Agents use it to retrieve configuration data. There are no write endpoints — JSONAir is intentionally uni-directional.

***

## Base URL

All endpoints are versioned under:

```
/api/v1/jsonair/
```

***

## Authentication Flow

The API uses a two-step authentication model:

1. **Exchange your PAT for a short-lived JWT.** Send your plain-text Personal Access Token (PAT) to the `/auth/token` endpoint. The server hashes it, looks it up in the database, and returns a signed JWT.
2. **Use the JWT as a Bearer token.** Include the JWT in the `Authorization` header on all subsequent requests. When it expires, repeat step one.

This means your long-lived PAT is only ever sent once per session, and the short-lived JWT is what travels with every API call.

***

## Endpoints at a Glance

| Method | Path                         | Auth Required | Description                 |
| ------ | ---------------------------- | ------------- | --------------------------- |
| `POST` | `/api/v1/jsonair/auth/token` | No            | Exchange a PAT for a JWT    |
| `GET`  | `/api/v1/jsonair/config`     | Yes           | Retrieve configuration data |
| `GET`  | `/api/v1/jsonair/reload`     | Yes           | Retrieve the reload key     |
| `GET`  | `/api/v1/jsonair/debug`      | Yes           | Retrieve the debug level    |

***

## Content Type

All request bodies must be JSON. All responses are JSON or plain text depending on the endpoint.

```
Content-Type: application/json
```

***

## Input Validation

The `type` and `name` fields in all requests are sanitized server-side. Only the following characters are accepted — any others are silently stripped:

```
a-z  A-Z  0-9  -  _  .
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.k9.io/key9-identity/jsonair/3-using-the-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.