Developer Guide

Quickstart

Deploying API Online on your VPS takes about five minutes:

1. Upload the project contents to your document root (e.g. /var/www/apionline).
2. Ensure the data/ directory is writable by the web server user.
3. Update config.php with your preferred app name, email settings, and base URL.
4. Visit /auth/register.php to create the first admin account.
5. Use the admin console to invite teammates, configure subscription tiers, and generate API keys.

Optional: enable nightly backups with php tools/backup.php and configure HTTPS via LetsEncrypt.

Environment Variables

Place secrets in a local .env file next to config.php or use web-server environment variables. Keys defined there (e.g. CURSOR_MODEL_CHAT_ADAPTER, CURSOR_OPENAI_KEY, billing credentials) are loaded automatically at bootstrap.

See Environment setup guide for an example file and Plesk tips.

Configuration

Key values in config.php:

• APP_NAME – branding shown on landing pages and dashboards.
• BASE_URL – canonical domain including protocol (e.g. https://test.apionline.co.uk).
• API_BACKEND_URL – leave empty to use the bundled Local AI Engine; set to a remote model gateway for hosted LLMs.
• TIER_LIMITS – configure rate limit window and custom endpoint allowances for Free, Pro, Enterprise plans.
• MAIL_FROM / SMTP_* – optional transactional email setup for invites and alerts.
• $MODEL_ROUTING / $MODEL_ADAPTERS – choose per-capability adapters (e.g. openai, ollama, or local) and provide API keys/base URLs.

For remote model integration, either configure API_BACKEND_URL to proxy every call, or set the per-capability environment variables (CURSOR_MODEL_CHAT_ADAPTER, etc.) to route selectively. API Online automatically falls back to the Local AI engine if an adapter is unavailable.

Branding & Theme

Super admins can personalize the interface from Admin → Theme. The Theme Manager updates the landing page, admin console, and client views without editing templates.

• Upload logos/favicons (stored under assets/branding/ with cache-busting query strings).
• Set brand name, tagline, hero copy, color palette, and font stacks.
• Inject custom CSS (sanitized) with access to var(--brand-*) variables.
• Preview changes instantly and reset to defaults if needed.

Configuration lives in data/theme.json. For more detail, see docs/theme_manager.md.

Authentication & API Keys

API calls are authenticated via bearer tokens:

Authorization: Bearer <api_key>

Admins can create, revoke, and delete keys from the dashboard (Admin > API Keys). Clients can self-manage keys under their account. Keys are tracked per tier with rolling counters in data/rate_limits.json.

To rotate a key programmatically, call POST /auth/rotate_key.php with the current key ID.

Billing Lifecycle

When BILLING_PROVIDER is set, point your provider webhooks to https://www.apionline.co.uk/webhooks/billing.php. The handler will:

• Persist invoices and payments into data/invoices.json and data/payments.json.
• Update subscriptions in data/subscriptions.json and flag users as past_due or active.
• Schedule dunning retries (default 1d → 3d → 7d) and expose the queue in the admin Payments page.

Customize the retry cadence via $BILLING_DUNNING_SCHEDULE in config.php. Exhausted retries automatically mark invoices as canceled and downgrade the subscription.

See docs/billing_providers.md for credential storage, webhook configuration, and the php tools/billing_smoke.php connectivity test.

Database & Backups

Manage schema migrations and backups from Admin → Database. The module supports:

• Running the JSON → MySQL migration script php tools/migrate_json_to_db.php.
• Triggering database-only or full-site archives via php tools/backup.php.
• Viewing the latest backup timestamp and storage footprint.

All maintenance actions are audited automatically. For scheduled jobs, consider cron entries such as 0 2 * * * php tools/backup.php --full.

Rate Limits

Rate limiting is enforced by drivers/RateLimiter.php. Each tier defines requests_per_hour, requests_per_day, and custom_endpoint_limit.

• Defaults and guardrails are stored in data/plan_limits.json (editable via Admin → Settings → Subscription Tiers).
• Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.
• Approaching the limit triggers banner warnings on dashboards.
• Admins can reset a user’s quota from the user detail view.
• Clients on eligible tiers can self-service their quota within guardrails; overrides live in the user’s metadata (metadata.limits).

Request Examples

Chat completion via curl:

curl https://your-domain/routes/v1/chat/completions.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"Draft onboarding email"}]}'

Moderation (accepts input or content):

curl https://your-domain/routes/v1/moderate.php \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"Example text"}'

See the Endpoint Reference for payload schemas and response structures.

Analytics & Alerts

Every API call is logged to data/analytics.json and aggregated in data/stats.json. The admin analytics dashboard provides historical charts, CSV export, and live telemetry.

• Live Analytics – streaming table, status distribution, and endpoint breakdowns.
• Alerting – configure latency/error thresholds via config.php. Alerts flow into data/alerts.json.
• Audit Trail – admin actions (invites, key rotations, alert acknowledgements) are stored in data/audit.json.

Command line smoke tests are available via php tools/smoke_test.php.

Local AI Engine

The bundled Local AI Engine (services/LocalAiEngine.php) provides deterministic heuristics when no external model is configured.

• Supports chat completions, code generation/explanation, embeddings, moderation, and mobile intent endpoints.
• Understands JSON knowledge packs stored in data/knowledge_packs/; add new packs to customize domain knowledge.
• Fallback logic ensures the engine responds instantly when the remote backend is unreachable.

To integrate real LLMs, set API_BACKEND_URL and ensure the remote service speaks OpenAI-compatible REST.

FAQ