API Integration Guide

This document captures the automation patterns previously maintained in codex/collab/api-integration.md. The guidance has been validated against the production Usenet Media Stack CLI and current service versions.

Core Principles

1. Treat every service as stateless. Persist data in volumes that are already part of the storage profiles generated by usenet storage.
2. Use the CLI as your entry point. The ./usenet services commands ensure authentication, hostnames, and port mappings stay consistent.
3. Respect rate limits. Public APIs such as Overseerr or Prowlarr enforce throttling; queue automation jobs instead of firing bursts.

Service Authentication Matrix

Service	Auth Source	Token Scope
Overseerr	config/overseerr	read + manage
Prowlarr	config/prowlarr	Indexer CRUD
Sonarr/Radarr	config/*/config.xml	Full automation
Plex	config/plex	Library management
Bazarr	config/bazarr	Subtitle sync

Tokens are rotated automatically when you run ./usenet backup create. Store rotation logs in your password manager to keep track of changes.

Automation Workflow

1. Request an API key through the service web UI.
2. Store the key in the .env overlay managed by ./usenet env edit.
3. Extend the CLI by creating a shell script under lib/commands that exports USENET_ENV before invoking curl or python clients.
4. Add the script to the completions file so the command appears in the interactive help.

Example: Creating a Custom Overseerr Import

#!/usr/bin/env bash
set -euo pipefail

source "$(dirname "$0")/../lib/core/bootstrap.sh"
API_KEY=$(usenet env get OVERSEERR_TOKEN)
BASE_URL=$(usenet services url overseerr)

curl -sS -X POST "$BASE_URL/api/v1/imports" \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"library-sync\",\"enabled\":true}"

Run the script with ./usenet custom overseerr-import. The CLI context resolves the container hostname, so this works on localhost and tunnels.

Webhook Integration

• Prefer HTTPS webhooks through the Cloudflare tunnel exposed by the stack. Create DNS entries in config/tunnel/records.yml.
• Queue heavy jobs with usenet services exec <service> -- enqueue to avoid blocking the webhook sender.
• Version control webhook payloads alongside the scripts that consume them so you can diff changes triggered by upstream providers.

Monitoring and Auditing

• Enable Netdata integration by posting metrics to localhost:8125.
• Log every automation run to /var/log/usenet-automation.log inside the control host. Forward logs with the existing Loki pipeline if enabled.
• Review API key usage weekly; revoke stale credentials via the CLI.