API Reference

API Reference

Tip

Building an integration? You probably want the public REST API (/api/v1/, key-authenticated, versioned) and its per-module guides such as REST API: Tickets. This page documents the internal AJAX endpoints the FreeITSM UI itself uses.

All endpoints live under api/ and return JSON. Every endpoint requires an active session ($_SESSION['analyst_id']), except api/v1/* (the public REST API) and api/external/* / 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.

Per-Endpoint Tables (Selected Modules)

The group table above shows the shape of the whole surface; the tables below list the individual endpoints for a selection of modules. Where a table is marked selected, the folder contains further endpoints beyond those listed.

Tickets (api/tickets/) — selected

Method	Path	Description
GET	get_emails.php	List tickets with latest email (filtered by dept/status)
GET	get_email_detail.php	Full email content and ticket info
POST	create_ticket.php	Create manual ticket (stamps the chosen send-from mailbox_id on the initial email)
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	Move a ticket to the trash (soft-delete — restorable)
POST	restore_ticket.php	Restore a ticket from the trash
POST	permanently_delete_ticket.php	Permanently delete a trashed ticket + all its data (irreversible)
POST	assign_ticket.php	Assign ticket to analyst
POST	update_ticket_owner.php	Set ticket owner
POST	schedule_ticket.php	Set work_start_datetime
POST	search_tickets.php	Search by ticket#, email, or subject
POST	send_email.php	Send email via Microsoft Graph API
GET	get_ticket_attachments.php	List attachments for a ticket
GET	get_attachment.php	Download attachment file
POST	check_mailbox_email.php	Import emails for a mailbox
GET	get_departments.php	List all departments
GET	get_my_departments.php	List analyst's team-filtered departments
POST	save_department.php	Create/update department
GET	get_analysts.php	List all analysts
POST	save_analyst.php	Create/update analyst
GET	get_teams.php	List teams
POST	save_team.php	Create/update team
GET	get_mailboxes.php	List mailbox configurations
POST	save_mailbox.php	Create/update mailbox
GET	get_mailbox_whitelist.php	Get whitelist entries for a mailbox
POST	save_mailbox_whitelist.php	Replace whitelist entries for a mailbox
GET	get_mailbox_activity.php	Paginated activity log for a mailbox
POST	verify_mailbox_folder.php	Verify a mail folder exists via Graph API
GET	get_email_templates.php	List email templates
POST	save_email_template.php	Create/update an email template
POST	delete_email_template.php	Delete an email template
GET	get_notes.php	Get notes for a ticket
POST	save_note.php	Add internal note
GET	get_ticket_audit.php	Get change history
GET	get_ticket_counts.php	Counts by department/status
GET	get_rota_shifts.php	List rota shift definitions
POST	save_rota_shift.php	Create/update rota shift
POST	delete_rota_shift.php	Delete rota shift
GET	get_rota.php	Get rota entries for a week
POST	save_rota_entry.php	Create/update rota entry
POST	delete_rota_entry.php	Delete rota entry
GET	get_ticket_dashboard.php	Get analyst's dashboard widgets
GET	get_ticket_widget_data.php	Aggregated data for a widget chart
GET	get_ticket_widget_library.php	List all widget definitions
POST	add_ticket_dashboard_widget.php	Add widget to dashboard
POST	remove_ticket_dashboard_widget.php	Remove widget from dashboard
POST	save_ticket_dashboard_widget.php	Create/update widget definition
POST	reorder_ticket_dashboard_widgets.php	Reorder dashboard widgets
POST	delete_ticket_dashboard_widget.php	Soft-delete a widget

Assets (api/assets/)

Method	Path	Description
GET	get_assets.php	List assets with user counts
GET	get_asset_users.php	Users assigned to an asset
POST	assign_asset_user.php	Assign user to asset
POST	unassign_asset_user.php	Remove user from asset
GET	get_servers.php	List VMs and ESXi hosts from servers table
POST	get_vcenter.php	Sync VMs from vCenter REST API
GET	debug_vcenter.php	Dump raw vCenter API responses
GET	get_software.php	Software inventory for a server

Knowledge (api/knowledge/) — selected

Method	Path	Description
GET	knowledge_articles.php	List articles (with search)
GET	knowledge_article.php	Get single article
POST	knowledge_save.php	Create/update article (auto-generates embedding)
POST	knowledge_delete.php	Delete article
GET	knowledge_tags.php	List available tags
POST	ai_chat.php	AI-powered Q&A over knowledge base
POST	generate_embedding.php	Generate OpenAI embedding for article
GET	get_email_settings.php	Get email & AI settings (keys masked)
POST	save_email_settings.php	Save email & AI settings (keys encrypted)

Forms (api/forms/)

Method	Path	Description
GET	get_forms.php	List all forms with field/submission counts
GET	get_form.php	Single form with fields (for builder & filler)
POST	save_form.php	Create/update form with fields
POST	delete_form.php	Delete form and all submissions
POST	submit_form.php	Submit a filled-in form
POST	ai_generate.php	Streaming SSE endpoint — generates a form definition from a plain-English description
GET	get_submissions.php	Submissions for a form (with field data)
POST	delete_submission.php	Delete a submission
GET	get_settings.php	Get forms module settings (logo alignment)
POST	save_settings.php	Save forms module settings

Settings (api/settings/)

Method	Path	Description
GET	get_system_settings.php	Get all settings (auto-decrypts sensitive keys)
POST	save_system_settings.php	Save settings (auto-encrypts sensitive keys)

My Account (api/myaccount/)

Method	Path	Description
POST	change_password.php	Validate current password, update to new (min 8 chars)
GET	get_mfa_status.php	Return { mfa_enabled: bool } for current analyst
POST	setup_mfa.php	Generate TOTP secret, return secret + otpauth URI for QR
POST	verify_mfa.php	Verify OTP against pending secret, encrypt and enable MFA
POST	disable_mfa.php	Verify password and disable MFA for current analyst
POST	verify_login_otp.php	Verify OTP during login MFA challenge, complete 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

The per-endpoint tables above cover the busiest modules; each module's own wiki page documents its endpoints in context, and the public REST API is documented under REST API — how it works.