Perfex CRM API Changelog

Fix MCP tool schema validation for estimates_create and credit_notes_create. Added required items sub-schema to array properties to pass OpenAI strict JSON Schema validation. Anthropic's API was lenient and accepted the bare array type; OpenAI (used by Hermes Agent via Codex) rejected it with HTTP 400. All 9 array types in MCP tools now have proper items sub-schemas.

Fix Claude.ai, Claude Desktop, and Claude Code only loading 50 of 170 MCP tools. Increased MCP tools/list page size from 50 to 250 so all tools load in a single request. Root cause: Anthropic MCP clients do not follow cursor-based pagination (nextCursor). All 170 tools including the full task management suite (22 tools) are now visible on first request.

Sub-resource pagination for Projects (tasks, milestones, files, discussions) and Invoices (payments). All sub-resource endpoints now support page and per_page/limit parameters (default 25, max 100) with full pagination metadata. Prevents oversized responses when projects have hundreds of tasks. Invoice payments pagination preserves total_paid/total_due summary in response metadata.

Fix Items API returning 401 for system API keys. Items_api.php used redundant user_id checks instead of requirePermission(), causing system keys (user_id=NULL) to be rejected even when fully authenticated. Replaced with standard permission pattern matching all other endpoints.

Fix blank/empty API response for system API keys (v2.8.3 regression). PerfexCRM core model methods internally call get_staff_user_id() which returned false when no session was set, producing invalid SQL and fatal TypeErrors on PHP 8.x. System API keys now impersonate the first active admin staff member in session context.

Fix system API keys denied access to all resources. System keys (user_id=NULL) were blocked by staff permission checks in getStaffVisibilityId(). Added early return to bypass visibility filtering for system keys, which have full access by design.

Fix route regeneration using safe string replacement instead of preg_replace (prevents regex corruption). Fix log_message crash when API response logger encounters non-string bodies. Fix undefined property warning in webhook delivery logging.

Fix query builder corruption in Projects, Invoices, and Leads endpoints caused by getStaffVisibilityId() resetting shared CI database state. Isolated visibility queries using independent DB connections to prevent cross-contamination of WHERE clauses.

MCP Server (Model Context Protocol) — AI agents can now discover and execute all 170 CRM operations via a single JSONRPC 2.0 endpoint. Works with Claude Desktop, ChatGPT, Cursor, n8n AI Agent, and 50+ MCP-compatible clients.

Permission-filtered tool discovery — AI agents only see operations the API key is authorized for. Built-in MCP documentation with curl examples, n8n AI Agent setup guide, and starter workflow template.

Admin MCP toggle in Settings > Advanced (disabled by default for security). Streamable HTTP transport with SSE support for real-time AI agent communication.

Staff-level permission filtering for all API endpoints. Non-admin staff members now only see data they have permission to access, matching PerfexCRM's native permission system. Applied to 44 methods across Projects, Leads, Tasks, Invoices, and Estimates — covering LIST, GET, UPDATE, DELETE, and all sub-resource operations. Uses PerfexCRM core permission functions (staff_can, user_can_view_invoice, user_can_view_estimate, staff_can_access_lead).

New global ?fields= query parameter for column-level response filtering. Request only the fields you need (e.g. ?fields=id,company,phonenumber) to reduce payload size. Applied automatically to all endpoints via the response layer — zero endpoint changes needed. Always includes id field. Also fixes route regeneration on update to ensure all (:num) endpoints are registered on existing installations.

New ?include= query parameter for all list endpoints. Related data (members, items, client, totals, etc.) is now opt-in, reducing default response size by up to 90% and eliminating N+1 query overhead. Affected endpoints: Projects, Invoices, Leads, Contracts, Estimates, Proposals, Credit Notes. Single-resource GET endpoints unchanged for backward compatibility.

Fix API 500 error on Projects and 12 other endpoints that use PerfexCRM core models. Root cause: get_staff_user_id() returned false in API context because no session was set, generating invalid SQL with empty IN() clauses. Fix: set PerfexCRM session context (staff_user_id, staff_logged_in) after API authentication so all core model methods work correctly. Subdomain matching for license activation: subdomains of an activated domain are now automatically recognized without consuming an additional activation slot.

Fix Auth_api.php: 17 broken response calls causing 500 errors on all auth endpoints (login, refresh, verify). Fix CI3 Session driver 503 error on Linux servers (defensive constructor workaround). Remove legacy Api.php catch-all router (root cause of Session 503 bug). Extract duplicate JWT generation into reusable buildJwt() method. Refactor routes from catch-all pattern to explicit per-endpoint routing. Remove duplicate lowercase auth_api.php file (Linux case-sensitivity fix).

Fix API response time always showing 0.000ms (protected → public $start_time). Server-side DataTables pagination for API and webhook logs. Add Clear All Logs buttons (admin-only) for API and webhook logs. Remove "All" option from log table length menu (memory safety). Display log retention info on logs page. Fix Auth_api.php case sensitivity for Linux server compatibility. Fix CSRF token missing on Regenerate Routes button (419 error).

Fixed ticket replies list still causing memory exhaustion. Root cause: SELECT * was loading full HTML email bodies with base64-encoded inline images. List replies now returns metadata only (id, date, sender). Full message content available via individual reply endpoint GET /tickets/{id}/replies/{replyId}.

Fixed ticket replies endpoint causing PHP memory exhaustion (512MB) on tickets with many or large replies. Added pagination support (page, per_page) to GET /tickets/{id}/replies. Embedded replies via ?include=replies now capped at 25 with reply_count metadata.

Fixed "Save Changes" button not working on Settings page. Root cause: nested HTML form for "Regenerate Routes" inside the main settings form (invalid HTML). Browser closed the outer form at the inner closing tag, leaving the Save button outside any form. Replaced nested form with JavaScript-based POST submission.

API completeness: Added POST /invoices (create invoice with full line items support) and POST /contracts (create contract). Added invoice.deleted and staff.login webhook events (100 total). Fixed ticket assign/status endpoints to accept both PUT and POST methods. n8n node aligned with API changes.

Fixed "Download Postman Collection" button returning 404 on production installations. Postman collection (193 requests, 21 resource folders) now included in distribution ZIP. Collection version bumped to v2.5.4

Standardized pagination across all 19 controllers: migrated Invoices, Leads, Projects, Contracts to getPaginationParams() helper. Added limit as backwards-compatible alias for per_page. Webhook docs enhanced with click-to-expand descriptions and payload field tags for all 98 events. 518 E2E tests passing (301 API + 217 webhook)

Documentation audit (21 fixes): Removed 4 ghost KB endpoints from admin docs, added JWT auth endpoint docs, added Resource Details for 12 API resources, added pagination/sorting docs. Postman collection updated to v2.5.1 with broken webhook test removed and 5 task operations added. README/COMPETITIVE-ANALYSIS updated with current numbers. Added 11 missing webhook event category language strings. 526 E2E tests passing (306 API + 220 webhook)

Auto-update security hardening: OPcache bypass for reliable file reads, concurrent update lock protection, download URL SSRF prevention, Throwable catch blocks for broader error handling. 301 E2E tests passing

Activation page security hardening: POST-only guards with CSRF tokens, XSS prevention on all dynamic outputs, download URL domain validation (MITM protection), double-submit prevention with loading spinners. License model instance-level caching. Removed dead KB routes. Restored contract.renewed webhook event. Expanded Postman collection. Critical routing and security fixes across all 5 new resources from v2.4.0. 526 E2E tests passing (306 API + 220 webhook)

Activation page security hardening: POST-only guards with CSRF tokens, XSS prevention on all dynamic outputs, download URL domain validation (MITM protection), double-submit prevention with loading spinners. License model instance-level caching (7 DB queries reduced to 1). Removed 4 dead KB routes. Restored contract.renewed webhook event (98 total). Postman collection expanded with Auth section and Invoice/Contract CRUD. 526 E2E tests passing (306 API + 220 webhook)

Removed OAuth 2.0 skeleton code (DB tables, model methods, auth chain, routes — never implemented). Settings page redesigned with 3-tab layout and conditional field visibility. Added Response Options (include_meta, include_timestamps) to settings UI. Fixed cache options not seeded in install. Fixed 12 input fields missing id attributes for label association. Fixed max_request_size input missing max attribute. Code cleanup across 29 files. 477 E2E tests passing (287 API + 190 webhook)

Dashboard & logs audit: Fixed XSS in all log views and dashboard, SQL performance optimization with 3 compound indexes, ISO week format fix, N+1 query elimination, MVC compliance (views no longer query DB directly), removed dead code, fixed exception message leak in Admin controller, fixed migration DB access pattern. 25 new localization keys. 477 E2E tests passing (287 API + 190 webhook)

Security & reliability fixes: API key management (expires_at saving, edit page display, per-key rate limiting, permissions list), webhook management (URL/event validation, retry enforcement, XSS prevention, secret standardization, header safety), ZIP build fix for views/logs/ directory. 469 E2E tests passing

Critical routing fix for v2.4.0 resources. Security fixes: notes permission bypass, items auth checks. Quality fixes: invoice status sync on payments, cascade deletes, input validation, cache wildcard support, lead.status_changed accuracy. 469 E2E tests passing (282 API + 187 webhook)

5 new standalone API resources: Payments, Items (full CRUD upgrade), Contacts, Timesheets, Notes. 15 new webhook events (3 per resource). Notes support polymorphic relations across 10 entity types. Timesheets support running timer concept. Updated Postman collection with 26 new requests. 282 E2E API tests passing + webhook tests. Total: 19 resources, 170+ endpoints, 98+ webhook events

Test update workflow

Auto-update download workflow verification

Update workflow verification release

Fix install update "Invalid request" error

Update verification release

Fix changelog display, file size extraction, version downgrade guard

Updated README with full feature overview

Release pipeline skill validation

Clear PHP opcache after auto-update for shared hosting

One-click auto-update feature

Security hardening, dead code cleanup

Security improvements

Initial public release