# oak-agent API

`oak-agent` exposes an HTTP API for OAK Apps running on the same device. It is reachable only from the device itself, not from
other hosts on the network. Apps can use it to check Hub connectivity, reboot the device, stop or restart themselves, and manage
watchdogs that monitor their health.

## Accessing the API

The server listens on `localhost:9091` by default. Requests must originate from an environment that can reach the agent's loopback
interface. The API is not bound to the device's LAN address.

All routes require an `Authorization` header whose value must exactly match a password that is generated dynamically by the agent
at startup. The password is made available to OAK Apps via the environment variable `OAKAGENT_PRIVATE_HTTP_PWD`. Send the raw
password without a `Bearer` or `Basic` prefix.

For example, you can check connectivity and authentication from the app's runtime environment using the following request:

```bash
curl --fail-with-body \
  -H "Authorization: $OAKAGENT_PRIVATE_HTTP_PWD" \
  "http://localhost:9091/v1/health"
```

A successful request returns HTTP `200` with body `{"status":"ok"}`.

> **API health endpoint**
> This endpoint confirms API reachability and authentication, it does not assess app health or connectivity to Hub services.

### Request errors

Missing or incorrect credentials, an unmatched path or HTTP method, and most request parsing failures return HTTP `404` with the
JSON string `"error"`. This includes malformed JSON, missing required fields, and unsupported watchdog action values in watchdog
creation requests.

The connectivity endpoint returns HTTP `400` for invalid query parameters, as described below.

## Hub connectivity checks

`GET /v1/network/health`

Checks whether Luxonis Hub services and app/OS download paths are available from the device's network. Each request runs fresh
checks; Agent does not schedule checks, cache results, or invoke application callbacks.

Call it from your app using the private API password:

```bash
curl --fail-with-body \
  -H "Authorization: $OAKAGENT_PRIVATE_HTTP_PWD" \
  "http://localhost:9091/v1/network/health?timeoutMs=5000"
```

Agent uses the device's Hub credentials for authenticated checks. Your app does not need to provide a Hub token. Outbound Hub
requests carrying the device JWT require HTTPS; the local Agent endpoint uses HTTP on loopback.

### Timeout

`timeoutMs` defaults to `5000` and accepts integers from `1` to `60000`.

The timeout applies to each probe, not the entire endpoint request. For app downloads, it includes URL lookup and the full
download. For OS downloads, it includes redirects and the full download. Local configuration retrieval and Hub service discovery
each have separate five-second limits.

Set your client's request timeout higher than `timeoutMs` to allow for configuration discovery.

### Results

HTTP `200` means the checks completed. Inspect the JSON `status` to determine the outcome:

 * `complete-ok`: all seven checks passed.
 * `complete-error`: at least one check failed. Other results remain available.

The following successful response was captured on a device connected to production Hub. Service URLs depend on the device's Hub
environment; applications should identify results by `serviceName`.

```json
{
  "status": "complete-ok",
  "fetchUrls": [
    {
      "url": "https://apps-ingest.cloud.luxonis.com/health",
      "serviceName": "apps_api",
      "status": "ok",
      "statusCode": 200
    },
    {
      "url": "https://broker.cloud.luxonis.com/api/health",
      "serviceName": "broker",
      "status": "ok",
      "statusCode": 200
    },
    {
      "url": "https://events.cloud.luxonis.com/v2/api-usage",
      "serviceName": "events_api",
      "status": "ok",
      "statusCode": 200
    },
    {
      "url": "https://easyml.cloud.luxonis.com/models/api/v1/health/",
      "serviceName": "hubai",
      "status": "ok",
      "statusCode": 200
    },
    {
      "url": "https://signal.cloud.luxonis.com/health",
      "serviceName": "signaling_api",
      "status": "ok",
      "statusCode": 200
    },
    {
      "serviceName": "app_download",
      "status": "ok",
      "statusCode": 200,
      "phase": "download",
      "bytesReceived": 10240
    },
    {
      "url": "https://api.cloud.luxonis.com/v1/ota/firmware/releases/otr_PWsKQ69wjmTtf9ngd5AYMh/download",
      "serviceName": "os_download",
      "status": "ok",
      "statusCode": 200,
      "phase": "download",
      "bytesReceived": 31
    }
  ]
}
```

App download URLs are omitted because they may contain signed credentials. Optional fields such as `statusCode` and `error` are
omitted when unavailable, rather than returned as `null`.

### Failed checks

The following are individual `fetchUrls` entries from separate illustrative responses. Each would make the aggregate status
`complete-error`.

Unreachable service:

```json
{
  "serviceName": "events_api",
  "url": "https://events.cloud.luxonis.com/v2/api-usage",
  "status": "error",
  "error": "connection"
}
```

Incomplete download, despite receiving HTTP 200:

```json
{
  "serviceName": "app_download",
  "status": "error",
  "statusCode": 200,
  "phase": "download",
  "bytesReceived": 512,
  "error": "incomplete-body"
}
```

Download timed out after receiving some data:

```json
{
  "serviceName": "app_download",
  "status": "error",
  "statusCode": 200,
  "phase": "download",
  "bytesReceived": 512,
  "error": "timeout"
}
```

Hub rate-limited the app download URL lookup:

```json
{
  "serviceName": "app_download",
  "status": "error",
  "statusCode": 429,
  "phase": "lookup",
  "error": "rate-limited"
}
```

Other error values include `request`, `http`, `discovery`, `unexpected-body`, `body-too-large`, and `not-configured`. DNS, TLS,
and TCP connection failures are grouped under `connection`.

### Request-level errors

| HTTP status | Meaning |
| --- | --- |
| `200` | Checks completed; inspect the aggregate and individual results. |
| `400` | Invalid query or `timeoutMs` outside the allowed range. |
| `404` | Missing or incorrect private API credentials. Checks do not run. |
| `429` | Another connectivity check is already running. No new checks start. |
| `503` | Checks could not run because Hub configuration, authentication, or discovery was unavailable. |

For example, an overlapping request returns HTTP `429`:

```json
{
  "status": "complete-error",
  "fetchUrls": [],
  "error": "A connectivity check is already running"
}
```

This differs from a Hub service returning 429: that appears as an individual `rate-limited` result inside an HTTP 200 response.

### What a successful check proves

Service probes require HTTP 2xx. The broker probe uses HTTP health checking; it does not establish a WebSocket or MQTT connection.
The Events probe checks authenticated team access and a quota lookup, but does not establish that upload quota remains available.
The `apps_api` and `hubai` probes check endpoint liveness; `hubai` covers the Models endpoint only.

App and OS download probes retrieve small test artifacts through the team's selected direct or proxied delivery path. Downloads
require HTTP 200 and a complete, nonempty body; the OS probe also verifies the exact 31-byte content. Nothing is installed or
saved. Transfers are capped at 1 MiB.

Successful probes do not guarantee installation, update eligibility, release discovery, or download throughput. Download fixtures
are configured for staging and production; custom Hubs return `not-configured` for downloads and therefore `complete-error`
overall.

### Calling frequency

Applications decide when to request checks. Agent rejects overlapping requests but does not limit sequential calls.

For repeated fleet checks, the provisional guidance is at most one request per device every five minutes, with randomized timing
and caller-side caching. This is an estimate for approximately 10,000 devices, not a measured capacity guarantee or an enforced
limit.

Share results between application callers and back off after rate limiting or repeated failures. Each check generates Hub requests
and downloads; the app download lookup also increments its download counter.

## Device actions

### Reboot the device

`POST /v1/device/reboot`

Requests a device reboot. No request body is required. Rebooting interrupts running apps and device connections.

```bash
curl --fail-with-body -X POST \
  -H "Authorization: ${OAKAGENT_PRIVATE_HTTP_PWD}" \
  "http://localhost:9091/v1/device/reboot"
```

Returns HTTP `200` with body `{"status":"ok"}`, or HTTP `500` with body `{"status":"error"}`.

## App actions

In app route paths, replace `{app_id}` with the app's full UUID. The calling app's UUID is available in the environment variable
`OAKAGENT_APP_ID`.

### Stop an app

`POST /v1/apps/{app_id}/stop`

Stops the specified app. No request body is required.

```bash
curl --fail-with-body -X POST \
  -H "Authorization: ${OAKAGENT_PRIVATE_HTTP_PWD}" \
  "http://localhost:9091/v1/apps/${OAKAGENT_APP_ID}/stop"
```

Returns HTTP `200` with body `{"status":"ok"}`. An invalid app UUID returns `400`; an operation failure returns `500`.

### Restart an app

`POST /v1/apps/{app_id}/restart`

Restarts the specified app using the agent's default restart timeout. No request body is required.

```bash
curl --fail-with-body -X POST \
  -H "Authorization: ${OAKAGENT_PRIVATE_HTTP_PWD}" \
  "http://localhost:9091/v1/apps/${OAKAGENT_APP_ID}/restart"
```

Returns HTTP `200` with body `{"status":"ok"}`. An invalid app UUID returns `400`; an operation failure returns `500`.

## App health monitoring

A watchdog associates an OAK App with a timeout and an action to take if the app stops reporting progress. Each app can register
and use multiple watchdogs at the same time.

Create a watchdog, retain its UUID, and send pings while the app is healthy. Choose a ping interval comfortably below the watchdog
timeout to allow for scheduling delays.

> **Watchdog ping policy**
> Send pings after meaningful progress, such as processing a frame or completing a work cycle. An independent heartbeat loop can continue running while the main work is stuck, so it may hide the failure you want to detect. Delete a watchdog when its healthcheck is no longer needed.

### Create a watchdog

`POST /v1/apps/{app_id}/watchdogs/create`

Accepts a JSON object with these fields:

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `description` | String | Yes | Description of the work being monitored. |
| `timeout_seconds` | Unsigned 64-bit integer | Yes | Watchdog timeout in seconds. |
| `action` | String | Yes | Action to perform on timeout. Options: `degrade`, `restart_app`. |
| `activate_on_creation` | Boolean | No | Whether to activate the watchdog immediately. Defaults to `true` when omitted or `null`.
If `false`, the watchdog is activated on the first received ping. |

> **Watchdog actions**
> When an active watchdog's timeout expires without a ping, it performs its configured action:

 * it restarts the OAK App; or
 * it sets the health of the app to `degraded`, adding its UUID and description to the list of degradation reasons. Note that more
   than one watchdog can degrade the health of an app at the same time.

Example creation payload:

```json
{
  "description": "Example watchdog",
  "timeout_seconds": 30,
  "action": "degrade"
}
```

Example creation request:

```bash
curl --fail-with-body -X POST \
  -H "Authorization: ${OAKAGENT_PRIVATE_HTTP_PWD}" \
  -H "Content-Type: application/json" \
  -d '{"description":"Example watchdog","timeout_seconds":30,"action":"degrade"}' \
  "http://localhost:9091/v1/apps/${OAKAGENT_APP_ID}/watchdogs/create"
```

On successful watchdog creation, the request returns HTTP `200` with the new watchdog's UUID:

```json
{
  "status": "ok",
  "watchdog_uuid": "8d35db5a-f916-4095-98cb-1a7955e774e7"
}
```

An invalid app UUID returns HTTP `400` with body `{"status":"invalid app_id","watchdog_uuid":null}`. An operation failure returns
HTTP `500` with body `{"status":"error","watchdog_uuid":null}`.

### Ping a watchdog

`POST /v1/apps/{app_id}/watchdogs/{watchdog_uuid}/ping`

Reports progress to the specified watchdog. No request body is required. Store the UUID from creation in `WATCHDOG_UUID` before
using this example:

```bash
curl --fail-with-body -X POST \
  -H "Authorization: ${OAKAGENT_PRIVATE_HTTP_PWD}" \
  "http://localhost:9091/v1/apps/${OAKAGENT_APP_ID}/watchdogs/${WATCHDOG_UUID}/ping"
```

Returns HTTP `200` with body `{"status":"ok"}`. Invalid app or watchdog UUIDs return `400`; an operation failure returns `500`.

### List watchdogs

`POST /v1/apps/{app_id}/watchdogs/list`

Lists watchdogs for the specified app. No request body is required.

```bash
curl --fail-with-body -X POST \
  -H "Authorization: ${OAKAGENT_PRIVATE_HTTP_PWD}" \
  "http://localhost:9091/v1/apps/${OAKAGENT_APP_ID}/watchdogs/list"
```

Returns HTTP `200` with `status` set to `"ok"` and a `watchdogs` array. Each entry contains:

| Field | Type | Description |
| --- | --- | --- |
| `ident` | Object | Watchdog identity containing `uuid` and `description`. |
| `ident.uuid` | String | Watchdog UUID. Use this value as `{watchdog_uuid}` in ping and delete requests. |
| `ident.description` | String | Description provided when creating the watchdog. |
| `timeout_seconds` | Unsigned 64-bit integer | Configured timeout in whole seconds. |
| `action` | String | Configured timeout action. |

Example response:

```json
{
  "status": "ok",
  "watchdogs": [
    {
      "ident": {
        "uuid": "8d35db5a-f916-4095-98cb-1a7955e774e7",
        "description": "Example watchdog"
      },
      "timeout_seconds": 30,
      "action": "degrade"
    }
  ]
}
```

If the app has no watchdogs, the response is `{"status":"ok","watchdogs":[]}`.

An invalid app UUID returns HTTP `400` with body `{"status":"invalid app_id","watchdogs":null}`. An operation failure returns HTTP
`500` with body `{"status":"error","watchdogs":null}`.

### Delete a watchdog

`POST /v1/apps/{app_id}/watchdogs/{watchdog_uuid}/delete`

Removes the specified watchdog. No request body is required.

```bash
curl --fail-with-body -X POST \
  -H "Authorization: ${OAKAGENT_PRIVATE_HTTP_PWD}" \
  "http://localhost:9091/v1/apps/${OAKAGENT_APP_ID}/watchdogs/${WATCHDOG_UUID}/delete"
```

Returns HTTP `200` with body `{"status":"ok"}`. Invalid app or watchdog UUIDs return `400`; an operation failure returns `500`.

### Delete all watchdogs for an app

`POST /v1/apps/{app_id}/watchdogs/delete-all`

Removes all watchdogs associated with the specified app. No request body is required.

```bash
curl --fail-with-body -X POST \
  -H "Authorization: ${OAKAGENT_PRIVATE_HTTP_PWD}" \
  "http://localhost:9091/v1/apps/${OAKAGENT_APP_ID}/watchdogs/delete-all"
```

Returns HTTP `200` with body `{"status":"ok"}`. An invalid app UUID returns `400`; an operation failure returns `500`.
