API Reference

API Reference

All endpoints live under api/ and return JSON. Every endpoint requires an active session ($_SESSION['analyst_id']), except api/external/* and api/watchtower/* which use API-key authentication for external integrations and the browser extension.

Standard Pattern

session_start();
require_once '../../config.php';
require_once '../../includes/functions.php';

header('Content-Type: application/json');

if (!isset($_SESSION['analyst_id'])) {
    echo json_encode(['success' => false, 'error' => 'Not authenticated']);
    exit;
}

All endpoints return either { "success": true, ... } or { "success": false, "error": "..." }.

Endpoint Groups (~155 endpoints)

Folder	Count	Purpose
api/tickets/	~59	Tickets, mailboxes, email templates, analysts, teams, rota, dashboard widgets, trash (soft-delete/restore/purge)
api/assets/	8	Assets, user assignments, vCenter sync, server inventory
api/knowledge/	16	Articles, AI chat, OpenAI embeddings, email settings, review workflow
api/change-management/	15	Changes, attachments, calendar, approvals, CAB workflow, settings
api/calendar/	7	Events and categories
api/morning-checks/	8	Check definitions, daily results, trend charts, reorder
api/reporting/	2	System logs
api/software/	5	Software inventory and licence management
api/forms/	10	Forms CRUD, submissions, settings, AI-generate (streaming SSE)
api/contracts/	~28	Contracts, suppliers, contacts, RFP Builder, terms, payment schedules
api/service-status/	7	Services CRUD, incident management, dashboard aggregation
api/self-service/	~12	End-user portal: register, login, MFA, new ticket, ticket detail
api/lms/	9	Courses, learning groups, assignments, progress, SCORM data
api/process-mapper/	4	List/get/save/delete process maps
api/cmdb/	~20	Classes, properties, objects, relationships, AI suggest, AI summary, impact, search
api/tasks/	~12	Tasks, subtasks, comments, ticket/change linking
api/watchtower/	1	Cross-module attention aggregation (also used by browser extension)
api/system/	~10	Encryption status, module access, SSO providers, multi-tenant topology, orphaned-ticket reassignment
api/system/debug-tools/	4	Self-contained diagnostics (demo import, ticket delete, self-service SSO, local login forensics)
api/settings/	2	Global system settings (auto-encrypts sensitive keys)
api/myaccount/	6	Password change, MFA setup/verify/disable
api/auth/	5	Password reset request/confirm, login resolution + OIDC SSO login/callback (portal-aware) (public)
api/external/system-info/submit/	1	External — full asset inventory ingestion (hardware, disks, network, software)
api/external/software-inventory/submit/	1	External — software inventory only
api/external/device-manager/submit/	1	External — Windows Device Manager device enumeration

Recently Added Endpoints

Tickets — trash & mailboxes (api/tickets/)

Method	Path	Description
GET	get_sendable_mailboxes.php	Mailboxes the active company can send replies from (pinned + shared, active + signed-in). Powers the New Ticket mailbox picker.
POST	delete_ticket.php	Moves a ticket to the trash (soft-delete) — no longer a hard delete.
POST	restore_ticket.php	Restores a ticket from the trash.
POST	permanently_delete_ticket.php	Permanently deletes a trashed ticket and all its data (irreversible).
POST	empty_trash.php	Permanently purges all trashed tickets in the active company.

System — topology & orphaned tickets (api/system/)

Method	Path	Description
GET	get_topology.php	Aggregated company-rooted topology (companies, mailboxes, domains, providers, analyst access, ticket/requester counts) for System → Topology.
GET	get_orphaned_tickets.php	Tickets whose department no longer exists, plus the valid departments available for reassignment.
POST	assign_ticket_department.php	Reassigns one or many tickets to a department (or none); used by Orphaned tickets.
GET	get_sso_providers.php	Lists SSO providers; each row now includes its owning company (tenant_name).

System debug tools (api/system/debug-tools/)

Self-contained diagnostics with their own authentication. Read-only unless stated; never print secrets.

Method	Path	Description
GET	D003_selfservice_sso.php	Self-service SSO check by email — reports end-to-end whether self-service sign-in is correctly wired for a requester.
POST	D004_local_login.php	Local login / password-hash forensics.

Auth — portal-aware SSO (api/auth/)

resolve_login.php, oidc_login.php and oidc_callback.php now accept a portal=self-service flag so SSO login can be driven from the end-user portal as well as the analyst login.

Authentication

Analyst session

Every internal endpoint checks $_SESSION['analyst_id'] after session_start(). Sessions are established by login.php after username/password + (optional) TOTP verification.

Self-service session

The self-service portal uses a separate session key — $_SESSION['ss_user_id'] — so analyst sessions and end-user portal sessions don't collide on the same browser.

API key

For external integrations and the browser extension. Generated at Software → Settings → API Keys, sent as a bearer token in the Authorization header. Rate limited (60 requests/min per key by default).

Common Conventions

Success / error shape

{ "success": true, "data": { ... } }
{ "success": false, "error": "Human-readable error" }

Identity

After insert, PHP-side returns the new id via lastInsertId():

{ "success": true, "id": 1234 }

Soft delete

User-facing records use is_active flags rather than physical deletion. APIs typically filter by is_active = 1 unless an include_inactive=1 query param is provided.

Sensitive settings

• api/settings/get_system_settings.php returns masked values (****<last4>) for keys in MASKED_SETTING_KEYS
• api/settings/save_system_settings.php treats blank or asterisk-prefixed submissions as "leave unchanged" — re-saving the form doesn't wipe the secret

Module-Specific Endpoints

Each module's page lists its key endpoints inline — see for example:

• Tickets — ticket lifecycle, email integration, dashboard widgets, rota
• CMDB — class/property CRUD, object relationships, AI suggest, impact
• Contracts — supplier register, contract terms, payment schedules, RFP Builder
• Forms — form definition, AI-generate streaming, submissions
• LMS — SCORM data API, assignments, progress

For the comprehensive endpoint list see the API Reference section of README.md in the main repo.