ProxmoxVE/docs/api/README.md

API Integration Documentation (/api)

This directory contains comprehensive documentation for API integration and the /api directory.

Overview

The /api directory contains the Proxmox Community Scripts API backend for diagnostic reporting, telemetry, and analytics integration.

Key Components

Main API Service

Located in /api/main.go:

• RESTful API for receiving telemetry data
• Installation statistics tracking
• Error reporting and analytics
• Performance monitoring

Integration with Scripts

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

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

Documentation Structure

API documentation covers:

• API endpoint specifications
• Integration methods
• Data formats and schemas
• Error handling
• Privacy and data handling

Key Resources

• 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 container installation data to API.

Usage:

post_to_api CTID STATUS APP_NAME

post_update_to_api()

Report application update status.

Usage:

post_update_to_api CTID APP_NAME VERSION

get_error_description()

Get human-readable error description from exit code.

Usage:

ERROR_DESC=$(get_error_description EXIT_CODE)

API Integration Points

In Container Creation (ct/AppName.sh)

• Called by build.func to report container creation
• Sends initial container setup data
• Reports success or failure

In Installation Scripts (install/appname-install.sh)

• Called at start of installation
• Called on installation completion
• Called on error conditions

Data Collected

• Container/VM ID
• Application name and version
• Installation duration
• Success/failure status
• Error codes (if failure)
• Anonymous usage metrics

Privacy

All API data:

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

API Architecture

Installation Scripts
    │
    ├─ Call: api.func functions
    │
    └─ POST to: https://api.community-scripts.org
                │
                ├─ Receives data
                ├─ Validates format
                ├─ Stores metrics
                └─ Aggregates statistics
                    │
                    └─ Used for:
                       ├─ Download tracking
                       ├─ Error trending
                       ├─ Feature usage stats
                       └─ Project health monitoring

Common API Tasks

• Enable API reporting → Built-in by default, no configuration needed
• Disable API → Set api_disable="yes" before running
• View API data → Visit https://community-scripts.org/stats
• Report API errors → GitHub Issues

Debugging API Issues

If API calls fail:

1. Check internet connectivity
2. Verify API endpoint availability
3. Review error codes in EXIT_CODES.md
4. Check API function logs
5. Report issues on GitHub

API Endpoint

Base URL: https://api.community-scripts.org

Endpoints:

• POST /install - Report container installation
• POST /update - Report application update
• GET /stats - Public statistics

---

Last Updated: December 2025 Maintainers: community-scripts team