ProxmoxVED/docs/api/README.md

API Integration Documentation

Overview

The telemetry and diagnostics API uses PocketBase as backend, hosted at http://db.community-scripts.org. All telemetry data is stored in the _dev_telemetry_data collection.

The Go/MongoDB API server (/api directory) has been replaced entirely by PocketBase.

Key Components

PocketBase Backend

• URL: http://db.community-scripts.org
• Collection: _dev_telemetry_data
• Admin UI: http://db.community-scripts.org/_/#/collections
• RESTful API for receiving telemetry data
• Installation statistics tracking
• Error reporting and analytics

Integration with Scripts

The API is integrated into all installation scripts via api.func:

• Sends installation start/completion events
• Reports errors and exit codes with numeric values
• Collects anonymous usage statistics
• Enables project analytics

Documentation Structure

• misc/api.func/ - API function library documentation
• misc/api.func/README.md - Quick reference
• misc/api.func/API_FUNCTIONS_REFERENCE.md - Complete function reference

API Functions

The api.func library provides:

post_to_api()

Send LXC container installation data to PocketBase.

Creates a new record in _dev_telemetry_data with status installing.

post_to_api_vm()

Send VM installation data to PocketBase.

Creates a new record with type=vm and ct_type=2.

post_update_to_api(status, exit_code)

Update installation status via PocketBase PATCH.

Maps status values:

• "done" → PocketBase status "sucess"
• "failed" → PocketBase status "failed"

explain_exit_code(code)

Get human-readable error description from exit code.

Usage:

ERROR_DESC=$(explain_exit_code 137)
# → "Killed (SIGKILL / Out of memory?)"

PocketBase Collection Schema

Field	Type	Required	Description
id	text (auto)	yes	PocketBase record ID
random_id	text	yes	Session UUID (unique)
type	select	yes	lxc, vm, addon, pve
ct_type	number	yes	1=LXC, 2=VM
nsapp	text	yes	Application name
status	select	yes	installing, sucess, failed, unknown
disk_size	number	no	Disk size in GB
core_count	number	no	CPU cores
ram_size	number	no	RAM in MB
os_type	text	no	OS type (debian, ubuntu, etc.)
os_version	text	no	OS version
pve_version	text	no	Proxmox VE version
method	text	no	Installation method
error	text	no	Error description
exit_code	number	no	Numeric exit code
created	autodate	auto	Record creation timestamp
updated	autodate	auto	Last update timestamp

API Endpoints (PocketBase REST)

Base URL: http://db.community-scripts.org

Method	Endpoint	Description
POST	/api/collections/_dev_telemetry_data/records	Create telemetry record
PATCH	/api/collections/_dev_telemetry_data/records/{id}	Update record status
GET	/api/collections/_dev_telemetry_data/records	List/search records

Query Parameters (GET)

• filter – PocketBase filter syntax, e.g. (nsapp='debian' && status='failed')
• sort – Sort fields, e.g. -created,nsapp
• page / perPage – Pagination
• fields – Limit returned fields

API Integration Points

In Container Creation (ct/AppName.sh)

• Called by build.func to report container creation via post_to_api
• Sends initial container setup data with status installing
• Reports success or failure via post_update_to_api

In VM Creation (vm/AppName.sh)

• Calls post_to_api_vm after VM creation
• Status updates via post_update_to_api

Data Flow

Installation Scripts
    │
    ├─ Call: api.func functions
    │
    ├─ POST → PocketBase (create record, status=installing)
    │           └─ Returns record ID (stored in PB_RECORD_ID)
    │
    └─ PATCH → PocketBase (update record with final status)
                └─ status=sucess/failed + exit_code + error

Privacy

All API data:

• ✅ Anonymous (no personal data)
• ✅ Aggregated for statistics
• ✅ Used only for project improvement
• ✅ No tracking of user identities
• ✅ Can be disabled via diagnostics settings

Debugging API Issues

If API calls fail:

1. Check internet connectivity
2. Verify PocketBase endpoint: curl -s http://db.community-scripts.org/api/health
3. Review error codes in EXIT_CODES.md
4. Check that DIAGNOSTICS=yes in /usr/local/community-scripts/diagnostics
5. Report issues on GitHub

---

Last Updated: February 2026 Maintainers: community-scripts team