# KLCKSTART API Catalog

This catalog summarizes the most useful API surfaces currently present in the project for developer onboarding, technical handoff, and implementation planning.

## Core response pattern
Most endpoints are easiest to consume if client code assumes a simple JSON structure:
- `ok` — boolean success flag
- `message` — friendly state or error message
- `status` / `request_status` — workflow state where relevant
- `data`, `items`, or endpoint-specific keys for payload content

## Auth + Sessions
- `POST /api/login.php` — authenticate a user and start a session
- `POST /api/logout.php` — end the current session
- `GET /api/auth/sessions.php` — list active sessions for the current account
- `POST /api/auth/revoke_session.php` — revoke one session
- `POST /api/auth/revoke_other_sessions.php` — revoke all sessions except the current one

### Approval flow guidance
- Registrations should remain `pending` until admin review is complete.
- Product access should be blocked until user status becomes `active`.
- New signups should trigger admin visibility through dashboard notifications and any configured email alerting.
- Browser clients calling protected endpoints should send same-origin credentials.

### Example auth responses
Successful login:
```json
{
  "ok": true,
  "message": "Login successful.",
  "status": "active",
  "redirect": "/dashboard.php"
}
```

Pending account:
```json
{
  "ok": false,
  "message": "Your account is awaiting admin approval.",
  "status": "pending"
}
```

## Billing
- `GET /api/billing/plan_catalog.php`
- `GET /api/billing/plans.php`
- `GET /api/billing/modules.php`
- `GET /api/billing/payment_methods.php`
- `POST /api/billing/payment_method_add.php`
- `POST /api/billing/payment_method_deactivate.php`
- `POST /api/billing/payment_method_set_default.php`
- `POST /api/billing/subscription_create.php`
- `POST /api/billing/subscription_change_request.php`
- `POST /api/billing/subscription_change_cancel.php`
- `GET /api/billing/recovery_summary.php`
- `POST /api/billing/retry_failed_invoice.php`
- `POST /api/billing/execute_change.php`

### Example billing payload
```json
{
  "plan_id": 3,
  "payment_method_id": 18,
  "modules": ["klckpay", "klckanalytics"],
  "billing_cycle": "monthly"
}
```

### Example billing response
```json
{
  "ok": true,
  "message": "Subscription created successfully.",
  "subscription_id": 42,
  "status": "active"
}
```

## Dashboard
- `GET /api/dashboard/summary.php`
- `GET /api/dashboard/summary_cached.php`

## Analytics
- `GET /api/analytics/summary.php`
- `GET /api/analytics/events.php`
- `GET /api/analytics/events_filtered.php`
- `GET /api/analytics/chart.php`
- `POST /api/track_event.php`
- `GET /api/admin/analytics_rollups.php`

### Example event payload
```json
{
  "event_name": "pricing_cta_clicked",
  "product": "klckpay",
  "page": "pricing"
}
```

## Shield
- `GET /api/shield/summary.php`
- `GET /api/shield/alerts.php`
- `GET /api/shield/alerts_filtered.php`
- `GET /api/admin/shield_alerts.php`
- `GET /api/admin/shield_high_risk.php`

## Wallet + Payouts
- `GET /api/wallet/my_wallet.php`
- `GET /api/wallet/my_payouts.php`
- `POST /api/wallet/request_payout.php`
- `POST /api/payout_request.php`
- `GET /api/wallet_balance.php`
- `GET /api/wallet_transactions.php`

## Admin Operations
- `GET /api/admin/users.php`
- `POST /api/admin/update_user_status.php`
- `POST /api/admin/update_user_role.php`
- `GET /api/admin/notifications.php`
- `GET /api/admin/notifications_unread_count.php`
- `POST /api/admin/notification_mark_read.php`
- `POST /api/admin/notification_dismiss.php`
- `GET /api/admin/ops_overview.php`
- `GET /api/admin/launch_status.php`
- `GET /api/admin/environment_diagnostics.php`
- `GET /api/admin/production_readiness.php`
- `GET /api/admin/regression_suite.php`
- `GET /api/admin/release_candidate_snapshot.php`
- `GET /api/admin/release_candidate_export.php`

### Example admin approval response
```json
{
  "ok": true,
  "message": "User status updated.",
  "user_id": 128,
  "status": "active"
}
```

## Reports + Export
- `GET /api/report_data.php`
- `GET /api/report_export_csv.php`
- `GET /api/report_export_pdf.php`
- `GET /api/admin/billing_export_csv.php`
- `GET /api/admin/audit_logs_export_csv.php`
- `GET /api/admin/live_validation_export.php`

## Health + Validation
- `GET /api/health/services.php`
- `GET /api/health/full_stack.php`
- `GET /api/health/deployment_stack.php`
- `GET /api/health/worker_stack.php`
- `GET /api/health/billing_stack.php`
- `GET /api/health/analytics_shield_stack.php`
- `GET /api/health/launch_stack.php`
- `GET /api/health/environment_stack.php`
- `GET /api/health/admin_access_stack.php`

## Notes
- User APIs require an authenticated user session unless explicitly public.
- Admin APIs require an authenticated admin session.
- Health and validation APIs are best used during deployment checks, launch review, and ongoing operations.
- The public `docs.php` and `api-reference.php` pages provide a friendlier implementation surface for developers and partners.