# Index API

The ISFR Index API provides free access to the public-facing ISFR surface for health monitoring, rate display, and visual exploration.

### Base URL

```
http://{host}:{port}
```

### Public Endpoints Overview

The following endpoints are available in the public/free tier:

* **Health check**: `GET /isfr/health`
* **Simple current rate**: `GET /isfr/v1/isfr/rate`
* **Interactive dashboard (HTML)**: `GET /isfr` or `GET /isfr/`

***

### `GET /isfr/health`

Returns a quick service and database health check with basic metadata.

#### Use cases

* Confirm the API is online
* Check whether the service currently has data
* Inspect last update time for monitoring or status pages

#### Example request

```bash
curl http://{host}:{port}/isfr/health
```

#### Response `200`

```json
{
  "status": "ok",
  "version": "0.1.0",
  "has_data": true,
  "last_update": "2026-01-01T12:00:00+00:00",
  "server_time": "2026-01-01T12:05:00+00:00",
  "database": {
    "total_entries": 168,
    "oldest_entry": "2025-12-25T00:00:00+00:00",
    "newest_entry": "2026-01-01T12:00:00+00:00",
    "storage": "sqlite",
    "db_path": "/app/data/isfr.db"
  }
}
```

#### Response fields

| Field                    | Type              | Description                                               |
| ------------------------ | ----------------- | --------------------------------------------------------- |
| `status`                 | string            | Service health status                                     |
| `version`                | string            | API/service version                                       |
| `has_data`               | boolean           | Whether the database currently contains ISFR observations |
| `last_update`            | string (ISO 8601) | Timestamp of the latest stored ISFR snapshot              |
| `server_time`            | string (ISO 8601) | Current server time                                       |
| `database.total_entries` | integer           | Number of stored entries                                  |
| `database.oldest_entry`  | string (ISO 8601) | Oldest stored entry                                       |
| `database.newest_entry`  | string (ISO 8601) | Most recent stored entry                                  |
| `database.storage`       | string            | Backing storage engine                                    |
| `database.db_path`       | string            | Internal database path                                    |

> `db_path` is primarily operational metadata and may be omitted or redacted in production deployments.

***

### `GET /isfr/v1/isfr/rate`

Returns the current ISFR value in a minimal format for simple integrations and UI display.

#### Use cases

* Display the latest ISFR value in an app or website
* Embed the rate in a widget, terminal, or status card
* Use as a lightweight public reference feed

#### Example request

```bash
curl http://{host}:{port}/isfr/v1/isfr/rate
```

#### Response `200`

```json
{
  "rate": "1.84%",
  "timestamp": "2026-01-01T12:00:00+00:00"
}
```

#### Response `503`

Returned when no data is available yet.

#### Response fields

| Field       | Type              | Description                                  |
| ----------- | ----------------- | -------------------------------------------- |
| `rate`      | string            | Human-readable current ISFR value            |
| `timestamp` | string (ISO 8601) | Timestamp of the underlying ISFR observation |

#### Example usage

```js
const res = await fetch('http://{host}:{port}/isfr/v1/isfr/rate');
const data = await res.json();

console.log(data.rate);
console.log(data.timestamp);
```

***

## `GET /isfr` and `GET /isfr/`

Serves the public HTML dashboard for visually exploring the ISFR index for quick visual inspection of ISFR behavior and for public-facing charts or internal monitoring pages.

#### Example request

Open in a browser:

```
http://{host}:{port}/isfr
```

or

```
http://{host}:{port}/isfr/
```

***

## Quickstart

{% stepper %}
{% step %}

#### Check service health

```bash
curl http://{host}:{port}/isfr/health
```

{% endstep %}

{% step %}

#### Fetch the latest public rate

```bash
curl http://{host}:{port}/isfr/v1/isfr/rate
```

{% endstep %}

{% step %}

#### Open the dashboard

Visit:

```
http://{host}:{port}/isfr
```

{% endstep %}
{% endstepper %}

The ISFR index API is designed for service discovery, public display, lightweight integrations, and exploratory usage. 

#### Versioning

The simple public rate endpoint is namespaced under `v1`:

* `GET /isfr/v1/isfr/rate`

Health and dashboard routes remain outside the versioned data namespace:

* `GET /isfr/health`
* `GET /isfr`
* `GET /isfr/`