HTTP API Quick Start

Alta provides an HTTP API with JSON requests and responses. The web interface uses the same API. This article shows how to log in and read the status of the application and the host.

Requirements

• Requests go to the API Server (default port 8100), not to the OTT Server. Read more HTTP Server.
• You need a user of the Alta web interface. Read more Users.

Authentication

The API supports two methods:

• Bearer token: Get a token with /api/login and send it in the Authorization: Bearer <token> header.
• HTTP Basic: Send the login and the password of the user in every request.

Log in:

curl -sS -X POST 'http://alta.example.com:8100/api/login' \
  -H 'Content-Type: application/json' \
  -d '{"id": "admin", "password": "PASSWORD"}'

The response is the token as plain text.

Note

The token is valid for about 30 days. Wrong credentials return 403 Forbidden.

Use the token in the next requests:

curl -sS -H "Authorization: Bearer $TOKEN" 'http://alta.example.com:8100/api/about'

Application Information

GET /api/about

Response:

{
    "service_name": "alta",
    "version": {
        "version": "261020",
        "commit": "349de372",
        "build": 1638139770
    },
    "runtime": {
        "instance_id": "8b1f6c3e-6a52-4c0e-9d1a-5f2f2a0c9e11",
        "uptime": 86400
    }
}

• service_name: Name of the service.
• version: Version, commit, and build of Alta.
• runtime.instance_id: Unique identifier of the Alta instance.
• runtime.uptime: Application uptime in seconds.

Host and Storage Status

GET /api/status

Response:

{
    "host": {
        "cpu": { "usage_percent": 12.5, "load_avg": [0.4, 0.5, 0.6], "cores": 8 },
        "mem": { "total_bytes": 16777216000, "used_bytes": 4294967296, "available_bytes": 12482248704 }
    },
    "storages": [
        {
            "name": "archive",
            "path": "/var/lib/alta/archive",
            "total_bytes": 1000000000000,
            "used_bytes": 250000000000,
            "free_bytes": 750000000000
        }
    ]
}

• host.cpu: CPU usage in percent, load average for 1, 5, and 15 minutes, and number of cores.
• host.mem: Total, used, and available memory in bytes.
• storages: Name, path, and total, used, and free space in bytes for each Storage.

Errors and Parameters

• 401 Unauthorized: No token, or the token is invalid or expired.
• 403 Forbidden: The user role does not allow the request.
• Requests for a single item, such as a channel or a receiver, use the id query parameter. For example, /api/ott/channel/storage/preview?id=discovery/hd. Read a complete example in Preview API.