Skip to content
/
Update a detection

Push Security REST API (v1)

Overview

The Push Security REST API provides programmatic access to the administrative functionality of the Push platform. This API adheres to RESTful principles, featuring resource-oriented URLs that are predictable and easy to navigate.

The API uses JSON-formatted request bodies and responses along with standard HTTP response codes, authentication methods, and HTTP verbs.

Rate limits are in place to ensure consistent performance for all users.

Authentication

To interact with the Push Security API, you'll need an API key for authentication. To create or manage your API keys, go to the Settings page in the Push admin console.

When generating a new key, you have two permission levels to choose from: Read only and Full access. A Read only key lets you make GET requests, while Full access allows for all types of requests.

To authenticate your API requests, include a header named x-api-key and set its value to your API key.

All API calls must be made over HTTPS.

Rate limits

The Push Security API enforces rate limiting to ensure equitable access and maintain performance. Each user is permitted up to 10 API requests per second, with a temporary burst capacity that allows an additional 10 requests for brief intervals.

If you surpass these limits, the API will return a 429 status code as an indication.

Errors

The Push Security API uses standard HTTP response codes to signal the outcome of an API call. Here's what you need to know:

2xx codes: These indicate that your request was successful.

4xx codes: A client-side issue, usually because something is missing or incorrect in your request.

5xx codes: These suggest a problem on our end, although these occurrences are infrequent.

Common Response Codes

HTTP CodeDescription
200 OKYour request was successfully processed.
400 Bad RequestYour request is missing something or is incorrect. Double-check your parameters.
429 Too Many RequestsYou've exceeded the rate limits. Consider implementing exponential backoffs in your API calls.
500 Server ErrorSomething's not right on our end.

Versioning

You're currently working with version 1 of the Push Security API. Should there be any breaking changes in the future, we'll bump up the API version number. If you hold an active API key, we'll send you notifications over email about the deprecation date for the older version.

Download OpenAPI description
rest-v1.json
rest-v1.yaml
Overview
URL
https://pushsecurity.com/contact/
support
support@pushsecurity.com
License
Commercial
Terms of Service
Languages
Servers
https://api.pushsecurity.com/

Accounts

These objects represent the accounts (owned by employees) in your organization.

Operations

Accounts (Other)

These objects represent the accounts (other) (owned by employees) in your organization.

Operations

Apps

These objects represent the apps that have been found in your organization.

Operations

Apps (Other)

These objects represent the apps (other) that have been found in your organization.

Operations

Browsers

These objects represent the browsers (used by employees) in your organization.

Operations

Browser Extensions

Operations

Detections

Operations

Retrieve a detection

Request

Security
x-api-key
Path
idstringrequired

Unique identifier for the detection

curl -i -X GET \
  'https://api.pushsecurity.com/v1/detections/{id}' \
  -H 'x-api-key: YOUR_API_KEY_HERE'

Responses

OK

Bodyapplication/json
idstring

Identifier of the detection

Example: "c478966c-f927-411c-b919-179832d3d50c"
employeeIdstring

Identifier for the employee that triggered the detection.

Example: "37cda962-7e78-49bc-8721-1becd16276a3"
employeeobject(Employee)

This object represents an employee in your organization.

employee.​idstring

Unique identifier for the employee

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
employee.​emailstring(email)

Primary email address of the employee

Example: "john.hill@example.com"
employee.​firstNamestring

First name of the employee

Example: "John"
employee.​lastNamestring

Last name of the employee

Example: "Hill"
employee.​departmentstring

Department - as provided by connected API integrations

Example: "Security Engineering"
employee.​locationstring

Location - as provided by connected API integrations

Example: "New York"
employee.​licensedboolean

Whether the employee is licensed on the Push platform

Example: true
employee.​creationTimestampinteger

When this employee was created, formatted as a UNIX timestamp (in seconds)

Example: 1698669223
employee.​chatopsEnabledbooleanDeprecated

Whether the employee has ChatOps enabled

Deprecation notice: this value no longer does anything unless you still have access to the legacy Employee chat topics functionality on your account. It will be removed in the next API version.

Example: true
browserIdstring

Identifier of the browser that was used when the detection was triggered.

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
severityany(SeverityType)

The severity of the detection

Enum"LOW""MEDIUM""HIGH""CRITICAL"
detectionTypeany(DetectionType)

The type of detection

Enum"PHISHING""STOLEN_CREDENTIALS""BLOCKED_URL""MALWARE_DELIVERY"
responseany(ResponseType)

The response for the detection

Enum"BLOCKED""EMPLOYEE_IGNORED_WARNING""EMPLOYEE_WARNED""NOT_BLOCKED"
creationTimestampinteger

When the detection was created. Formatted as a UNIX timestamp (in seconds).

Example: 1698604061
archivedboolean

Whether the detection has been archived.

Example: true
classificationstring or null

The classification of the detection.

Enum"TRUE_POSITIVE""BENIGN_TRUE_POSITIVE""FALSE_POSITIVE"
Example: "FALSE_POSITIVE"
eventsArray of objects(DetectionChildEvent)

The events associated with the detection.

events[].​idstring

Identifier of the detection event.

Example: "c478966c-f927-411c-b919-179832d3d50c"
events[].​creationTimestampinteger

When the event was created. Formatted as a UNIX timestamp (in seconds).

Example: 1698604061
events[].​detectionEventTypeany(DetectionEventType)

The type of detection event.

Enum"PHISHING_TOOL_DETECTED""CLONED_LOGIN_PAGE_DETECTED""SSO_PASSWORD_USED""PROTECTED_PASSWORD_ENTERED""STOLEN_CREDENTIALS""BLOCKED_URL_VISITED""MALICIOUS_COPY_PASTE_DETECTED"
events[].​accountIdstring or null

Identifier of the account that the detection event is associated with.

Example: "37cda962-7e78-49bc-8721-1becd16276a3"
events[].​appTypestring or null

The type of app that the detection event is associated with.

Example: "PUSH_SECURITY"
events[].​phishingToolIndicatorstring or null
Example: "AITM_TOOL_EVILGINX_01"
events[].​controlModestring or null(ControlModeType)

All possible ENUM values for control modes.

Enum"INFORM""ACKNOWLEDGE""REASON""BLOCK""WARN""MONITOR"
events[].​descriptionstring or null

The description of the detection event. Note: this is subject to change and should not be used to match on this object.

Example: "Phishing attempt detected"
events[].​clonedLoginPageIndicatorstring or null
Example: "MICROSOFT_01"
events[].​responseany(ResponseType)

The response for the detection event.

Enum"BLOCKED""EMPLOYEE_IGNORED_WARNING""EMPLOYEE_WARNED""NOT_BLOCKED"
events[].​emailstring or null

The email associated with the account related to the detection event.

Example: "john.hill@example.com"
events[].​urlstring or null

The URL that the detection event was triggered on.

Example: "https://example.com/phishing"
events[].​referrerUrlstring or null

The referrer URL.

Example: "https://mail.google.com"
events[].​clonedLoginPageUrlsArray of strings or null

The legitimate login page URL that was cloned.

Example: ["https://example.com/phishing"]
events[].​sourceIpAddressstring

The source IP address.

Example: "8.158.25.38"
events[].​metadatastring

The metadata associated with the detection event.

Example: "{\"source_type\": \"Telegram\", \"breach_type\": \"Stealer Malware Logs\", \"breach_publication_date\": \"2025-04-01\"}"
events[].​experimentalboolean

Indicates if this detection event is experimental.

Example: false
Response
application/json
{
  "id": "c478966c-f927-411c-b919-179832d3d50c",
  "employeeId": "37cda962-7e78-49bc-8721-1becd16276a3",
  "employee": {
    "id": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
    "email": "john.hill@example.com",
    "firstName": "John",
    "lastName": "Hill",
    "department": "Security Engineering",
    "location": "New York",
    "licensed": true,
    "chatopsEnabled": true,
    "creationTimestamp": 1698669223
  },
  "browserId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  "severity": "LOW",
  "detectionType": "PHISHING",
  "response": "BLOCKED",
  "creationTimestamp": 1698604061,
  "archived": true,
  "classification": "FALSE_POSITIVE",
  "events": [
    {
      "id": "c478966c-f927-411c-b919-179832d3d50c",
      "creationTimestamp": 1698604061,
      "detectionEventType": "PHISHING_TOOL_DETECTED",
      "accountId": "37cda962-7e78-49bc-8721-1becd16276a3",
      "appType": "PUSH_SECURITY",
      "phishingToolIndicator": "AITM_TOOL_EVILGINX_01",
      "controlMode": "INFORM",
      "description": "Phishing attempt detected",
      "clonedLoginPageIndicator": "MICROSOFT_01",
      "response": "BLOCKED",
      "email": "john.hill@example.com",
      "url": "https://example.com/phishing",
      "referrerUrl": "https://mail.google.com",
      "clonedLoginPageUrls": [
        "https://example.com/phishing"
      ],
      "sourceIpAddress": "8.158.25.38",
      "metadata": "{\"source_type\": \"Telegram\", \"breach_type\": \"Stealer Malware Logs\", \"breach_publication_date\": \"2025-04-01\"}",
      "experimental": false
    }
  ]
}

Update a detection

Request

Security
x-api-key
Path
idstringrequired

Unique identifier for the detection

Bodyapplication/jsonrequired

Update a detection's archive status.

archivedboolean

The desired archive status for the detection.

Example: true
classificationstring or null

The desired classification for the detection.

Enum"TRUE_POSITIVE""BENIGN_TRUE_POSITIVE""FALSE_POSITIVE"
Example: "FALSE_POSITIVE"
curl -i -X PATCH \
  'https://api.pushsecurity.com/v1/detections/{id}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY_HERE' \
  -d '{}'

Responses

OK

Bodyapplication/json
idstring

Identifier of the detection

Example: "c478966c-f927-411c-b919-179832d3d50c"
employeeIdstring

Identifier for the employee that triggered the detection.

Example: "37cda962-7e78-49bc-8721-1becd16276a3"
browserIdstring

Identifier of the browser that was used when the detection was triggered.

Example: "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0"
severitystring

The severity of the detection.

Enum"LOW""MEDIUM""HIGH""CRITICAL"
Example: "HIGH"
detectionTypestring

The type of detection.

Enum"PHISHING""BLOCKED_URL""STOLEN_CREDENTIALS""MALWARE_DELIVERY"
Example: "PHISHING"
responsestring

The response to the detection.

Enum"BLOCKED""EMPLOYEE_IGNORED_WARNING""EMPLOYEE_WARNED""NOT_BLOCKED"
Example: "BLOCKED"
classificationstring or null

The classification of the detection.

Enum"TRUE_POSITIVE""BENIGN_TRUE_POSITIVE""FALSE_POSITIVE"
Example: "FALSE_POSITIVE"
creationTimestampinteger

When the detection was created. Formatted as a UNIX timestamp (in seconds).

Example: 1698604061
archivedboolean

Whether the detection has been archived.

Example: true
Response
application/json
{
  "id": "c478966c-f927-411c-b919-179832d3d50c",
  "employeeId": "37cda962-7e78-49bc-8721-1becd16276a3",
  "browserId": "2a2197de-ad2c-47e4-8dcb-fb0f04cf83e0",
  "severity": "HIGH",
  "detectionType": "PHISHING",
  "response": "BLOCKED",
  "classification": "FALSE_POSITIVE",
  "creationTimestamp": 1698604061,
  "archived": true
}

Employees

These objects represent the employees in your organization.

Operations

Findings

These objects represent the findings that have been found in your organization.

Operations

URL blocking

These objects represent the blocked URLs configured in your organization.

Operations

Stolen credential detection

Manage custom stolen credentials that you have added to your organization for monitoring and enforcement.

Operations