Changelog#
Client API additions, behavior changes, deprecations, fixes, and documentation updates, newest first. Entries flagged Breaking altered an existing request or response contract.
Incident history documented around authorDetails
The Incident History page is now in the navigation and documents authorDetails as the structure to build new integrations on. Classifying entries by the author string or the type field is documented as the legacy structure: still supported, to be deprecated in the future with plenty of notice, with a step-by-step migration guide and fallback code for moving existing integrations. History examples on the single incident endpoints now show the full entry. No API behavior changes.
GET /v1/incident/{incidentId}GET /v1/incident/subject/{subject}POST /v1/incident/{id}/commentComment length limit documented
The comment field is limited to 5,000 characters on the report endpoints and on the add comment endpoint. A longer comment returns 400 and nothing is saved: the incident is not created, or the comment is not added. The limit is already enforced; this entry documents it.
POST /v1/incident/tkdPOST /v1/incident/monitorPOST /v1/incident/{id}/commentRe-open and takedown review requests return what was sent
History entries for a re-open or takedown review request now carry a reopen object with the requester's reason, reasonCode, requestedAction, the incident's previousStatus, and any evidence sent with it (attachmentId, fileName, url). The entry's message is Re-open requested or Takedown review requested, and author names the requester. A file attached with the request is described in reopen.evidence instead of appearing as a separate history entry.
GET /v1/incident/{incidentId}GET /v1/incident/subject/{subject}Reported URLs and domains are corrected instead of saved as sent
The report endpoints now correct the url and domain fields before saving them: leading and trailing spaces are removed, defanged values are restored (hxxp/hxxps schemes, [.], [:] and [://]), and the scheme and host are lowercased while the path and query are kept as sent. For example, hxxps://Example[.]com/Login is saved as https://example.com/Login. Duplicate checks use the corrected value, so a defanged or upper-case report of an existing incident returns 409. Values with inner spaces or several comma-separated values are still rejected with 400.
POST /v1/incidentPOST /v1/incident/tkdPOST /v1/incident/monitorIncident report submissions limited to 60 per minute per account
The report endpoints now enforce a budget of 60 submissions per minute per account, counted across all report endpoints and across every key and sub-client of the account. A submission beyond the budget returns 429 with a Retry-After header giving the seconds until the budget resets; the incident is not created. Integrations that submit in batches should send sequentially and honor Retry-After. Other endpoints are unchanged.
POST /v1/incident/tkdPOST /v1/incident/monitorRetryable 409 for a just-reported incident on write endpoints
Calling the attachment, comment, review (tkd/monitor/safe), or approve-takedown endpoint with an inc_… id in the first few minutes after reporting it, while the incident is still being linked to its full record, now returns 409 with a Retry-After header (typically 30 seconds) instead of 404. Retry after the indicated delay. An id that still cannot be resolved outside that window returns 404 as before.
POST /v1/incident/{id}/attachPOST /v1/incident/{id}/commentPOST /v1/incident/{id}/{action}POST /v1/incident/{id}/approve-takedownTakedown-attempt default page size raised to 100
GET /v1/incidents/resolutions and its singular alias now return up to 100 incidents per page when limit is not specified, up from 25. Maximums are unchanged: 2000 for cursor-paginated lists and 100 with search. Send an explicit limit to keep smaller pages.
GET /v1/incidents/resolutionsGET /v1/incident/resolutionsTakedown-attempt page limit lowered to 2000
GET /v1/incidents/resolutions and its singular alias now accept an explicit limit up to 2000 for cursor-paginated lists, down from 5000. Requests with a limit above 2000 return 400. The default remains 25 and the search lookup keeps its maximum of 100. Use paging.next to read more results.
GET /v1/incidents/resolutionsGET /v1/incident/resolutionsTakedown-attempt usage guidance
Clarifies completed-attempt eligibility, empty search results, unsupported filters, response fields and pagination termination. Corrects code examples and distinguishes repeat attempts from proof that content returned online. Adds Takedown Attempts to endpoint navigation. No API behavior changes.
GET /v1/incidents/resolutionsLarger takedown-attempt pages
GET /v1/incidents/resolutions and its singular alias accept an explicit limit up to 5000 for cursor-paginated lists. The default remains 25. The separate search lookup keeps its existing maximum of 100 results and does not return a cursor.
GET /v1/incidents/resolutionsGET /v1/incident/resolutionsFilters for incidents taken down more than once
GET /v1/incidents/resolutions accepts two new filters. reinitiatedAfter=success returns incidents where a new takedown started after a successful one, and reinitiatedAfter=resolved accepts any earlier outcome. minTakedownAttempts returns incidents with at least that many takedown starts. Both combine with clientId, incidentType, status, fromDate, toDate, cursor, limit and includeTotal, apply before pagination, and return each incident with all of its takedown attempts. Combining them with search or statusVerbose, or sending them to GET /v1/incidents, returns 400. List pages without these filters also load faster.
GET /v1/incidents/resolutionsTakedown attempts endpoint
GET /v1/incidents/resolutions lists your incidents with every takedown attempt on each: startedAt, resolvedAt and outcome (success, failed, not_actionable or closed). Supports the incident list filters, search and cursor pagination (default 25, maximum 100 per page). Requires the incidents:read scope and must be enabled for your account by PhishFort support.
GET /v1/incidents/resolutionsauthorDetails on incident history entries
Incident history entries can include an authorDetails object alongside author, giving structured access to author type, client id, email, and automation status without parsing the display string. Enabled per account on request; absent until switched on, so treat it as optional.
GET /v1/incident/{incidentId}GET /v1/incident/subject/{subject}API changelog feed and MCP tool
Client API changes are available as a rendered changelog, a machine-readable JSON feed and the get_changelog tool on the Docs MCP server.
DocumentationConsistent incidentClass values
incidentClass now uses the documented six-value vocabulary across incident responses and webhook payloads. Values are derived from the threat classification, and unclassified incidents return other instead of n/a.
GET /v1/incidentsGET /v1/incident/{incidentId}statusVerbose deprecation date updated
The planned deprecation date for statusVerbose is December 25, 2026. Use status for filtering and reading the computed verbose status value.
GET /v1/incidentsGET /v1/incident/{incidentId}Optional author on incident comments
Adding a comment accepts an optional author email so the comment is attributed to the right person in your organization. Omitting it attributes the comment to the API key owner.
POST /v1/incident/{incidentId}/commentApprove takedowns via the API
New endpoint to approve a takedown that is waiting on your confirmation, as an alternative to approving from the dashboard.
POST /v1/incident/{incidentId}/approve-takedownBlocklist listings on incident detail
The incident detail response includes a new blocklists field showing which blocklist partners the threat has been submitted to and where it is actively listed.
GET /v1/incident/{incidentId}Credit usage endpoint
New endpoint returning your plan's credit usage and remaining balance.
GET /v1/usageIncident snapshots endpoint documented
The endpoint returning page snapshots captured for an incident is now documented.
GET /v1/incident/{incidentId}/snapshotsTechnical insights on incident detail
The incident detail response includes a new insights field with technical detail about the threat, including hosting, page and capture indicators.
GET /v1/incident/{incidentId}Docs MCP server
This documentation site is available as an MCP server at https://api-docs.phishfort.com/mcp, so AI assistants can search pages, read full docs and fetch OpenAPI specs while helping you build an integration.
DocumentationTotal counts for incident lists
Passing includeTotal=true to the incident list returns the total number of matching incidents in paging.total.
GET /v1/incidentsClients and Documents endpoints documented
The endpoints for listing your client accounts and retrieving documents (including signed download URLs) are now documented.
GET /v1/clientsGET /v1/documentsGET /v1/documents/{documentId}GET /v1/documents/{documentId}/signed-urlList users endpoint
New endpoint listing the dashboard users of your organization.
GET /v1/usersAuthor attribution on incident history
Incident history entries now identify who wrote each entry (a PhishFort analyst or a member of your organization) via the author classification documented in Data Structures.
GET /v1/incident/{incidentId}Attachment and throttling limits clarified
The Limits page now states attachment size limits and request throttling behavior precisely.
DocumentationWebhooks
Webhook subscriptions deliver HTTP notifications for incident events (created, status changed, history added, takedown updated, action required), signed with HMAC-SHA256.
POST /v1/webhooksGET /v1/webhooksPATCH /v1/webhooks/{id}DELETE /v1/webhooks/{id}Cursor-based pagination for incident lists
The incident list supports cursor-based pagination for stable iteration over large result sets, alongside the existing limit/offset paging.
GET /v1/incidentsRegistrar, hosting provider and expanded threat taxonomy on incident detail
The incident detail response includes registrar and hostingProvider fields and an expanded threatTaxonomy structure.
GET /v1/incident/{incidentId}Migration from statusVerbose
The status parameter began returning verbose values, starting the migration away from statusVerbose. statusVerbose remains accepted and returned for compatibility and is planned for deprecation on December 25, 2026.
GET /v1/incidentsGET /v1/incident/{incidentId}Threat taxonomy and classification fields
Incident responses include threatTaxonomy, incidentClass and related classification fields describing the type of threat.
GET /v1/incidentsGET /v1/incident/{incidentId}Verbose status values
Incident status values moved to the verbose set (pending_review, case_building, takedown_in_progress, …) and the other status was replaced by closed.
GET /v1/incidentsGET /v1/incident/{incidentId}Comments must be non-empty
Adding a comment with a null or empty body is rejected with a validation error.
POST /v1/incident/{incidentId}/commentAdd a comment to an existing incident
New endpoint to add a comment to an incident you have already reported.
POST /v1/incident/{incidentId}/comment50 MB attachment limit
Attachment uploads are limited to 50 MB per request.
POST /v1/incident/{incidentId}/attachcase_building status
New case_building incident status, covering incidents where PhishFort is gathering evidence before enforcement.
GET /v1/incidentsGET /v1/incident/{incidentId}reportedBy on incident reports
Reporting an incident accepts an optional reportedBy field identifying the reporter.
POST /v1/incident/tkdIncident attachments
Attachments can be included when reporting an incident and added to existing incidents.
POST /v1/incident/{incidentId}/attachstatusVerbose parameter and new incident types
The incident list gained the statusVerbose parameter (since deprecated in favor of status) and support for additional incident types.
GET /v1/incidents