# Server Health API Reference

API endpoints for managing server health.

## Get Server Health

`GET` `https://api.igloohome.co/home/server-health`

Returns the caller's OAuth client/user billing status. Use it for integration health checks.

Requires a valid Bearer token but no specific scope. The endpoint runs the same billing check
as every other authenticated endpoint, so a lapsed trial/billing status returns
`402`/`403` before the API returns the health payload.

### Request Example

```bash
curl -X GET "https://api.igloohome.co/home/server-health" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

```go
package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.igloohome.co/home/server-health"
	req, _ := http.NewRequest("GET", url, nil)
	req.Header.Set("Authorization", "Bearer YOUR_ACCESS_TOKEN")
	req.Header.Set("Accept", "application/json")

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}
```

```javascript
const res = await fetch("https://api.igloohome.co/home/server-health", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
  }
});

const data = await res.json();
console.log(data);
```

```python
import requests

url = "https://api.igloohome.co/home/server-health"
headers = {
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
    "Accept": "application/json"
}
response = requests.get(url, headers=headers)
print(response.json())
```

```php
<?php
$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => "https://api.igloohome.co/home/server-health",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => "GET",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer YOUR_ACCESS_TOKEN",
        "Accept: application/json"
    ]
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;
```

```kotlin
val client = OkHttpClient()

val request = Request.Builder()
    .url("https://api.igloohome.co/home/server-health")
    .method("GET", null)
    .addHeader("Authorization", "Bearer YOUR_ACCESS_TOKEN")
    .addHeader("Accept", "application/json")
    .build()

val response = client.newCall(request).execute()
println(response.body?.string())
```

```swift
import Foundation

var request = URLRequest(url: URL(string: "https://api.igloohome.co/home/server-health")!)
request.httpMethod = "GET"
request.setValue("Bearer YOUR_ACCESS_TOKEN", forHTTPHeaderField: "Authorization")
request.setValue("application/json", forHTTPHeaderField: "Accept")

let task = URLSession.shared.dataTask(with: request) { data, response, error in
    if let data = data {
        print(String(data: data, encoding: .utf8) ?? "")
    }
}
task.resume()
```

### Responses

`200 OK`
`401 Unauthorized, invalid or expired authorization token`
`402 Response`
`403 Forbidden. The authenticated user has revoked access, or their account was removed.`
`500 Internal Server Error`

**Response body — `200`:**

- **`userRef`** `string`
- **`clientId`** `string`
- **`clientName`** `string`
- **`status`** `string`
- **`endsAt`** `string<date-time>`
- **`isAdminLogin`** `boolean`
- **`flow`** `string`\
  OAuth client flow (e.g. `code`, `client_credentials`)
- **`scopes`** `array of string`
- **`tier`** `string`
- **`codeUserRef`** `string`\
  Only present when `flow` is `code`

**Response body — `402`:**

- **`error`** `string`

**Example response — `200`:**

```json
{
  "clientId": "7k8m9n0p1q2r3s4t5u6v7w8x",
  "clientName": "igloohome-partners-app",
  "endsAt": "2026-09-08T00:00:00Z",
  "flow": "client_credentials",
  "isAdminLogin": false,
  "scopes": [
    "igloohomeapi/get-devices"
  ],
  "status": "active",
  "tier": "paid",
  "userRef": "user_abc123def456"
}
```

**Example response — `402`:**

```json
{
  "error": "30 days igloohome API trial has ended"
}
```