> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.alexxweb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Health & Status

> Check whether AlexWeb is ready, read its uptime, and measure response time.

<div className="aw-doc-intro">
  <span className="aw-doc-label">Service monitoring</span>
  <p>Use health checks to decide whether a service can handle work. Use status to understand its readiness and uptime at the time of your request.</p>
</div>

These requests are public. They do not require an API key, and the responses contain no private account data or internal infrastructure addresses.

<div className="aw-doc-actions">
  <a className="aw-doc-button aw-doc-button-primary" href="https://api.alexxweb.com/api/v1/status">Open live status</a>
  <a className="aw-doc-button" href="https://api.alexxweb.com/developers">Open developer console</a>
</div>

## Try it

Send the request in this page's interactive panel, or use cURL:

<CodeGroup>
  ```powershell cURL theme={null}
  curl -i https://api.alexxweb.com/api/v1/status
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.alexxweb.com/api/v1/status");
  const status = await response.json();
  console.log(response.status, status.status);
  ```
</CodeGroup>

## What you'll see

This is an illustrative response; uptime and timings change with each request.

```json theme={null}
{
  "service": "AlexWeb API",
  "version": "1.2.0",
  "status": "operational",
  "uptime_seconds": 86400,
  "timestamp": "2026-10-18T12:00:00.000Z",
  "checks": {
    "storage": {
      "status": "ok",
      "latency_ms": 0.45
    }
  }
}
```

| Field | Meaning |
| - | - |
| `service` | The service name, **AlexWeb API**. |
| `version` | The software version serving the request. |
| `status` | `operational` when storage is ready; `degraded` when it is unavailable. |
| `uptime_seconds` | Seconds since this API process started. A restart resets this number. |
| `timestamp` | The time of this check in UTC. |
| `checks.storage.status` | Whether a lightweight storage read succeeded. |
| `checks.storage.latency_ms` | Time spent on that storage check, in milliseconds. |

The status response checks the API process and its storage. It does not test every webhook receiver, OAuth callback, or connected Home Assistant instance.

## Health checks

<CardGroup cols={2}>
  <Card title="Readiness" icon="circle-check">
    `GET /api/v1/health` verifies a storage read. Use this when deciding whether the API is ready to serve requests.
  </Card>

  <Card title="Liveness" icon="heart-pulse">
    `GET /health` confirms that the API process can answer HTTP. It remains available for existing monitors.
  </Card>
</CardGroup>

A successful readiness response is:

```json theme={null}
{ "status": "ok" }
```

If the storage check fails, `/api/v1/health` returns HTTP **503** and:

```json theme={null}
{ "status": "unavailable" }
```

`/api/v1/status` also returns **503** when degraded. Use the HTTP status code in your monitor, and inspect the JSON to understand the result. A liveness response alone does not prove storage is ready.

## Understand the timing

**Storage latency** is one small operation inside the API. It excludes the time spent reaching the service over the internet.

**Client response time** includes the network path and the time it takes to receive a response. You can measure it with cURL:

```bash theme={null}
curl -s -o /dev/null -w 'HTTP %{http_code}; total %{time_total}s\n' https://api.alexxweb.com/api/v1/status
```

The developer console displays a browser measurement when it loads status. Your account's [usage analytics](/v1/usage) measures server response time for authenticated requests. These measure different parts of a request and should not be expected to match.

## Use it in a monitor

1. Point your monitor at `https://api.alexxweb.com/api/v1/health`.
2. Treat HTTP **200** as ready and **503** as unavailable.
3. Use a reasonable interval, such as once per minute, and confirm repeated failures before alerting.
4. Keep the `X-Request-Id` header from failed checks when requesting help.

Status and health are point-in-time checks. This API does not promise a historical uptime percentage or a service-level agreement.

## Other requests

| Request | Purpose |
| - | - |
| `GET /health` | Process liveness, compatible with existing monitors. |
| `GET /api/v1/health` | Storage readiness. |
| `GET /api/v1/status` | Readiness, uptime, version, and storage timing. |
| `GET /api/v1/capabilities` | Supported features and configured limits. |

For request counts, error rates, and latency statistics belonging to your account, use [Usage & Limits](/v1/usage).


## OpenAPI

````yaml GET /api/v1/status
openapi: 3.1.0
info:
  title: AlexWeb API
  version: 1.3.0
  description: >-
    Manage AlexWeb API data, applications, events, and installation file
    downloads, with a custom Home Assistant integration for resources and live
    updates.
servers:
  - url: https://api.alexxweb.com
    description: Public API
security:
  - BearerAuth: []
  - ApiKeyAuth: []
tags:
  - name: Base API
  - name: Health & Status
  - name: Echo
  - name: Developer Accounts
  - name: API Keys
  - name: OAuth
  - name: Applications
  - name: Resources
  - name: Installations
  - name: Events
  - name: Webhooks
  - name: Schedules
  - name: Usage
  - name: Home Assistant
paths:
  /api/v1/status:
    get:
      tags:
        - Health & Status
      summary: Read service status and uptime
      description: >-
        Public point-in-time readiness, process uptime, version, and
        storage-check latency. Does not test external webhook receivers or
        connected apps.
      operationId: getServiceStatus
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatus'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '400':
          description: Invalid input
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '401':
          description: Missing or invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
            WWW-Authenticate:
              schema:
                type: string
              description: Bearer authentication challenge.
        '403':
          description: Required scope not granted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '410':
          description: Event cursor is no longer available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '412':
          description: Resource version does not match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '413':
          description: Request body is too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '415':
          description: Wrong content type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '429':
          description: Rate limit reached
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
            Retry-After:
              schema:
                type: integer
              description: Seconds until retry.
        '500':
          description: Internal server error
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
        '503':
          description: Service degraded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceStatus'
          headers:
            X-Request-Id:
              schema:
                type: string
              description: Identifier for this request.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                Request allowance for this one-minute window. The legacy /health
                liveness route is exempt.
            RateLimit-Remaining:
              schema:
                type: integer
                minimum: 0
              description: Requests remaining in this window.
            RateLimit-Reset:
              schema:
                type: integer
                minimum: 1
              description: Seconds until the current window resets.
      security: []
components:
  schemas:
    ServiceStatus:
      type: object
      properties:
        service:
          type: string
          const: AlexWeb API
        version:
          type: string
          const: 1.3.0
        status:
          type: string
          enum:
            - operational
            - degraded
        uptime_seconds:
          type: integer
          minimum: 0
        timestamp:
          type: string
          format: date-time
        checks:
          type: object
          properties:
            storage:
              type: object
              properties:
                status:
                  type: string
                  enum:
                    - ok
                    - unavailable
                latency_ms:
                  type: number
                  minimum: 0
              required:
                - status
                - latency_ms
              additionalProperties: false
          required:
            - storage
          additionalProperties: false
      required:
        - service
        - version
        - status
        - uptime_seconds
        - timestamp
        - checks
      additionalProperties: false
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            requestId:
              type: string
          required:
            - code
            - message
            - requestId
          additionalProperties: false
      required:
        - error
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        API key or OAuth access token in Authorization: Bearer. Keep credentials
        out of URLs.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: Alternative header for an API key. OAuth access tokens use Bearer.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.