REST API v2 Endpoint Reference

The v2 API is REST + JSON over HTTPS. Every request authenticates with a service account using HTTP Basic, every response is wrapped in a standard envelope, and every error is RFC 7807 ProblemDetails. Base URL

https://portal.contraforce.com/api/v2

Authentication

Authorization: Basic <base64(clientId:clientSecret)>

Conventions

Content-Type: application/json (or multipart/form-data for operating procedure uploads)
Property names are camelCase; enum values are PascalCase (Sentinel, High, TwentyFourHours)
Workspace IDs and most other identifiers are GUIDs
Source segment values: Sentinel, DefenderXDR, CrowdStrike, QRadar, Splunk, SentinelOne, SumoLogic. The segment is case-insensitive, so the lowercased source from a webhook event can be used as is. Any other value returns 400 VALIDATION_ERROR with the accepted values listed under errors.source.

Workspace-Scoped Endpoints

Path prefix: /workspaces/{workspaceId}/... The workspace ID is a GUID and identifies the customer environment the request operates against. The credential’s service account must have a role on the target workspace, otherwise the request returns 403 INSUFFICIENT_WORKSPACE_ROLE.

Every incident is the child of one SIEM source — the source is encoded as a route segment, not a query parameter.

Method	Path	Description
`GET`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}`	Get the full incident detail, including alerts, entities, investigation details, and evidence.
`GET`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}/evidence`	Get the evidence table for an incident.
`GET`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}/last-gamebook`	Get the last gamebook run for an incident, or `404` if none has run.
`GET`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments`	List comments on an incident.
`GET`	`/workspaces/{workspaceId}/incidents/{source}/by-entity`	Find incidents in this source related to a specific entity.

Method	Path	Description
`PUT`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}/status`	Change the incident’s status. Body: `status` (`New`, `Active`, `Closed`), optional `comment`, and, when closing, `classification` and `classificationReason` (see Closing an incident below). Set `updateTicket: true` with `ticketId` to mirror the change to a linked service ticket. Returns `204`.
`PUT`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}/assignee`	Assign the incident. Body: `userId` (the ContraForce user id) or `email`. Returns `204`.

Closing an incident

Setting status to Closed requires a classification and a classificationReason for every detection module. The reason must belong to the chosen classification; ContraForce uses the same pairs for every source and translates them to each vendor’s vocabulary (see Incident Classification).

`classification`	Accepted `classificationReason` values
`TruePositive`	`MultistagedAttack`, `Malware`, `MaliciousUserActivity`, `UnwantedSoftware`, `Phishing`, `CompromisedUser`, `Apt`, `SuspiciousActivity`, `Other`
`FalsePositive`	`NotMalicious`, `NoEnoughDataToValidate`, `InaccurateData`, `IncorrectAlertLogic`, `Other`
`BenignPositive`	`SecurityTesting`, `ConfirmedUserActivity`, `LineOfBusinessApplication`, `SecurityPersonnel`, `SuspiciousButExpected`, `Other`
`Undetermined`	`Unknown`, `Other`

Other is accepted with every classification.

PUT /api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/incidents/DefenderXDR/55022/status
{
  "status": "Closed",
  "comment": "Closed after review; no malicious activity confirmed.",
  "classification": "Undetermined",
  "classificationReason": "Other"
}

A reason that does not belong to the classification (for example Undetermined with InaccurateData) is rejected with 400 VALIDATION_ERROR:

"errors": {
  "ClassificationReason": ["Classification reason does not apply to the selected classification"]
}

Method	Path	Description
`POST`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments`	Add a comment. Body: `{ "content": "..." }`. Returns `201` with the created comment.
`PUT`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments/{commentId}`	Replace a comment’s text. Body: `{ "content": "..." }`. Returns `204`.
`DELETE`	`/workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments/{commentId}`	Delete a comment. Supported for `Sentinel` and `SentinelOne`. Returns `204`.

The source in the route decides where the comment is written. Comments on a Defender XDR incident go to Defender XDR; comments on a Sentinel incident go to Sentinel, and Microsoft syncs them to the paired Defender XDR incident where one exists. An extensionId property or query parameter is accepted and ignored.

POST /api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/incidents/DefenderXDR/55025/comments
{ "content": "Escalated to the on-call analyst." }

Method	Path	Description
`GET`	`/workspaces/{workspaceId}/gamebooks/rules/{incidentTitle}`	Get playbooks matching an incident title.
`GET`	`/workspaces/{workspaceId}/gamebooks/history`	List gamebook execution history. Supports `?query=` and `?pageToken=`.
`GET`	`/workspaces/{workspaceId}/gamebooks/history/{gamebookId}/playbooks`	Get the playbooks recorded against a specific gamebook run.
`GET`	`/workspaces/{workspaceId}/gamebooks/by-incident/{incidentId}`	List all gamebooks that have run for an incident. `?withUserDetails=` (`true` or `false`) is required; `?source=` picks the incident’s source.

Method	Path	Description
`POST`	`/workspaces/{workspaceId}/gamebooks/run`	Submit a new gamebook run for an incident in the workspace.

gamebooks:execute does not imply gamebooks:read. Grant both to look up playbooks and poll the result. To run immediately, the service account needs the Owner or Incident Responder role on the route workspace; any other workspace role can only request approval with "isQueued": true. See Running Gamebooks with a service account for setup.Request

POST /api/v2/workspaces/6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1/gamebooks/run
{
  "incidentId": "<incident-id>",
  "source": "Sentinel",
  "incidentTitle": "Suspicious sign-in activity",
  "incidentNumber": 4182,
  "isQueued": false,
  "playbooks": [
    {
      "id": "scanendpoint",
      "entityId": "<entity-id-from-incident>",
      "entityType": "Endpoint",
      "sequence": 1
    }
  ]
}

Field	Required	Description
`incidentId`	Yes	Incident ID. The incident must belong to the route workspace.
`incidentTitle`	Yes	Incident title. Must not be empty.
`source`	Yes	Incident source, such as `Sentinel` or `DefenderXDR`.
`incidentNumber`	No	Incident display number.
`isQueued`	No	`true` submits the run for approval. Defaults to `false`. `false` never skips an approval that a policy or partner setting requires.
`playbooks`	Yes	One or more actions to run.
`playbooks[].id`	Yes	A playbook ID from the playbook catalog below, for example `scanendpoint`.
`playbooks[].entityType`	Yes	The playbook’s `entityType` from the playbook catalog. This is not the incident entity kind (use `Endpoint`, not `Host`).
`playbooks[].entityId`	For targeted actions	The `id` of the incident entity to act on, from `investigationDetails.entities[]` in the incident detail response. See Finding the entityId. General actions need no target.
`playbooks[].sequence`	Yes	Execution order. The values across the request must be exactly `1` to `N` with no gaps or duplicates.
`playbooks[].parameters`	No	Action-specific settings.

Validation rules:

Any field not listed above returns 400, including Portal-only fields such as reason, gamebookId, and isRetryGamebook.
Quarantine File (quarantinefile) needs a File entity that carries its own device ID and SHA-1 hash.
Delete Email (deleteemail) needs an email entity that carries both the message ID and the mailbox’s Entra object ID. A UPN alone is not enough.
Block IP (blockip) is not available to service accounts and returns 403, even with "isQueued": true.

Playbook catalogThis is the full set of playbook IDs. Send the id and entityType exactly as listed. A playbook does not have to be mapped to the incident’s analytic rule to run, but it still needs the matching integration on the workspace and must pass the workspace’s run policies. The kind column is the kind of incident entity that entityId must point to; see Finding the entityId.

`id`	Name	`entityType`	Entity `kind` to target	What it does
`acknowledgeresponse`	Acknowledge Response	`General`	None (omit `entityId`)	Adds a comment to the incident with a timestamp and the name of whoever ran it.
`invalidateexistingsessions`	Invalidate Existing Sessions	`User`	`Account`	Ends the user’s signed-in sessions.
`lockoutuser`	Lockout User	`User`	`Account`	Disables the user’s account so they cannot sign in. Undo with `unlockuser`.
`unlockuser`	Unlock User	`User`	`Account`	Re-enables the user’s account so they can sign in again.
`resetmfa`	Reset MFA	`User`	`Account`	Deletes the user’s registered MFA methods, so they must register MFA again at their next sign-in.
`resetuserpassword`	Reset User Password	`User`	`Account`	Forces the user to reset their password at their next sign-in.
`isolateendpoint`	Isolate Endpoint	`Endpoint`	`Host`	Disables the device’s external network access. Undo with `unisolateendpoint`.
`unisolateendpoint`	Release From Isolation	`Endpoint`	`Host`	Restores an isolated device’s external network access.
`scanendpoint`	Scan Endpoint	`Endpoint`	`Host`	Runs an antivirus scan on the device.
`quarantinefile`	Quarantine File	`Endpoint`	`File`	Stops the file from being used and deletes it, on the device recorded on the file entity.
`deleteemail`	Delete Email	`Email`	`MailMessage`	Deletes the email from the user’s mailbox.
`blockip`	Block IP	`Network`	`IP`	Not available to service accounts.

To list the playbooks ContraForce suggests for an incident’s analytic rule, call GET /workspaces/{workspaceId}/gamebooks/rules/{incidentTitle} with gamebooks:read.Finding the entityIdGet the incident with GET /workspaces/{workspaceId}/incidents/{source}/{incidentId} (incidents:read). Its investigationDetails.entities[] lists every entity on the incident. Pick the entity whose kind matches the playbook’s row in the catalog, and send its id as entityId, exactly as returned.

"investigationDetails": {
  "entities": [
    {
      "id": "<entity-id>",
      "kind": "Host",
      "displayName": "WIN-FINANCE-07",
      "deviceId": "<defender-device-id>"
    }
  ]
}

Use the entity id, not deviceId, userUpn, or another identifier on the entity.
The id must match exactly one entity on the incident. If the run returns 400 for the target, fetch the incident again and use the current id.
quarantinefile needs a File entity that has a deviceId and a SHA-1 fileHash.
deleteemail needs a MailMessage entity whose internetMessageId and aadUserId are both present.

Response

{
  "data": {
    "id": "<gamebook-id>",
    "status": "Running",
    "isQueued": false
  }
}

"status": "Running", "isQueued": false: sent for execution. Poll GET /workspaces/{workspaceId}/gamebooks/by-incident/{incidentId}?source={source}&withUserDetails=false and match on id for the outcome.
"status": "Pending", "isQueued": true: waiting for approval in the Portal. It has not run.

Errors

Status	Code	Cause
`400`	`VALIDATION_ERROR`	Invalid or unsupported fields, bad `sequence` values, missing target data, a blocking run policy, or unmet integration prerequisites.
`403`	`INSUFFICIENT_SCOPE`	The credential lacks `gamebooks:execute`.
`403`	`INSUFFICIENT_WORKSPACE_ROLE` / `FORBIDDEN`	No role on the route workspace, a non-queued run without Owner or Incident Responder, or a Block IP action.
`404`	`NOT_FOUND`	The workspace or incident was not found.
`415`	`UNSUPPORTED_MEDIA_TYPE`	Missing `Content-Type: application/json`.

Runs are not idempotent. Retrying the same request can start a second run. After a timeout, check the incident’s gamebook history before resubmitting. Approving, retrying, denying, and cancelling a gamebook remain Portal-only.

Method	Path	Description
`GET`	`/workspaces/{workspaceId}/datasources`	List data sources connected to the workspace.

Read (tickets:read):

Method	Path	Description
`GET`	`/workspaces/{workspaceId}/tickets/search`	Search service tickets. Supports `?groupingId=` and `?ticketNumber=`.

Manage (tickets:manage):

Method	Path	Description
`POST`	`/workspaces/{workspaceId}/tickets/link`	Link a service ticket to an incident.
`POST`	`/workspaces/{workspaceId}/tickets/unlink`	Unlink a service ticket from an incident.
`PUT`	`/workspaces/{workspaceId}/tickets/priority`	Update ticket priority.

ticketId in a link request is the ticketing system’s record id, not the ticket number: the ServiceNow sys_id (not INC0049162), the Jira issue id or key, or the numeric Autotask ticket id. If you only have the number, look it up with GET /workspaces/{workspaceId}/tickets/search?ticketNumber=<number> and send the id of the matching ticket. An unknown id returns 400 “Unable to find the selected ticket”.

Method	Path	Description
`GET`	`/workspaces/{workspaceId}/investigation/users/signin-logs`	List user sign-in logs.
`GET`	`/workspaces/{workspaceId}/investigation/users/directory-logs`	List directory audit logs.

Separate endpoints for the incident summary, entities, alert rules, bulk updates and the high-severity list are not on the v2 surface yet. They will be added once their handlers operate against an explicit source rather than implicitly defaulting to Sentinel. An incident’s entities are already returned in investigationDetails.entities by GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}.

Cross-Workspace Endpoints

These endpoints span every workspace your service account can see — no workspace ID in the path. The handlers filter results to the workspaces the credential has been mapped to.

Scope	Method	Path	Description
`incidents:read`	`POST`	`/incidents/across-workspaces`	List incidents across all visible workspaces.
`gamebooks:read`	`GET`	`/gamebooks/across-workspaces/history`	List gamebook history across visible workspaces. Supports `?workspaces=`, `?statuses=`, `?currentPage=`, `?query=`.
`datasources:read`	`POST`	`/datasources/across-workspaces/anomalies`	List data connector anomalies across visible workspaces.
`datasources:read`	`GET`	`/datasources/across-workspaces`	Group connected data sources by workspace. Repeat `?workspaceIds=` for each workspace ID.

Paginating `/incidents/across-workspaces`

The cross-workspace incidents list uses opaque continuation tokens. The first request leaves the token map empty; every subsequent request echoes the previous response’s tokens back unchanged. Tokens are server-encrypted strings — treat them as a single blob the API gave you, never parse or construct one yourself. First request:

POST /api/v2/incidents/across-workspaces
{
  "isFirstCall": true,
  "workspacePageTokens": [],
  "sources": ["Sentinel"],
  "timeFilterSelection": { "type": "TwentyFourHours" }
}

Response (truncated):

{
  "data": {
    "incidents": [ /* ...page of incidents... */ ],
    "sourcePageTokens": [
      {
        "workspaceId": "6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1",
        "sourceTokens": {
          "Sentinel": "Gd41DJgGnsDnbYHEdqbFaAKzlIbg6NVK...CQM8="
        }
      }
    ],
    "moreIncidentsAvailable": true
  }
}

Next-page request — set isFirstCall: false and pass sourcePageTokens back verbatim as workspacePageTokens:

POST /api/v2/incidents/across-workspaces
{
  "isFirstCall": false,
  "workspacePageTokens": [
    {
      "workspaceId": "6eca6a1f-b7d1-4bb8-a055-35ad6bb4b9b1",
      "sourceTokens": {
        "Sentinel": "Gd41DJgGnsDnbYHEdqbFaAKzlIbg6NVK...CQM8="
      }
    }
  ],
  "sources": ["Sentinel"],
  "timeFilterSelection": { "type": "TwentyFourHours" }
}

Iterate until the response returns moreIncidentsAvailable: false. A workspace that has finished paging drops out of sourcePageTokens on subsequent responses; do not synthesize entries for it. Page size is server-controlled. A token that has been modified or hand-built returns 400 VALIDATION_ERROR with the message One or more pagination tokens are invalid. Use the tokens from the previous response unmodified. Recover by restarting from the first call with an empty workspacePageTokens array.

Syncing incident updates with `filterByLastModified`

By default timeFilterSelection bounds the incident’s creation time, so a list call cannot tell you which existing incidents changed. If you mirror incidents into an external system and need to pick up updates, set filterByLastModified: true. The same window then bounds the incident’s last-modified time as recorded by the vendor (Microsoft Sentinel lastModifiedTimeUtc, Microsoft Defender XDR lastUpdateDateTime), and the page is ordered by last-modified time descending. Sentinel and Defender XDR move that timestamp on every change recorded on the incident: an alert grouped in, a severity change, a status change, an owner change, a label, or a comment. Incidents created long before the window are returned as soon as they are touched. Note that the two modes are not equivalent for a bounded window: an incident created inside the window but modified after its end matches the creation-time query and not the last-modified one. In a polling loop whose windows end at the time of each call, that incident simply shows up in the next poll. Polling pattern:

POST /api/v2/incidents/across-workspaces
{
  "isFirstCall": true,
  "workspacePageTokens": [],
  "filterByLastModified": true,
  "timeFilterSelection": {
    "type": "Custom",
    "customStartUtc": "2026-09-15T15:30:00Z",
    "customEndUtc": "2026-09-15T15:45:00Z"
  }
}

Poll on a fixed cadence, set customStartUtc to your previous customEndUtc minus a short overlap (one or two minutes), page until moreIncidentsAvailable is false, then fetch by id only the incidents whose lastModificationTime differs from the copy you stored. An unchanged incident returned twice because of the overlap compares equal and costs nothing. Things to know:

The filter uses the vendor’s last-modified time, not lastActivityTime. lastActivityTime is the event time of the latest alert and is usually earlier than the incident’s creation time; it does not move when an analyst edits the incident.
The response carries the incident as it is now, not the fields that changed. Keep comparing against your stored copy.
Supported for Sentinel and DefenderXDR. Leave sources empty to query both; naming any other source together with filterByLastModified returns 400 VALIDATION_ERROR (FilterByLastModified is supported for Sentinel, DefenderXDR only; …).
Changes that exist only inside ContraForce and are not written to the vendor incident do not move the vendor timestamp.
In this mode each workspace’s window is returned in full in one call unless it exceeds the server’s page cap (several hundred incidents per workspace). If moreIncidentsAvailable comes back true, narrow the window and call again rather than paging: vendor continuations are positional, and an incident edited past the window’s end between two calls can shift them. A short polling window never hits the cap.
Each page is ordered by last-modified time descending. Sources are merged per page, so if you do page, read every page before assuming you have the full window.

Organization-Scoped Endpoints

These endpoints operate on the organization (service provider). The credential’s service account must hold the relevant org-level scope; workspace mappings are not required.

webhooks:read / webhooks:manage
org:service-accounts:read / manage
org:users:read / manage / roles
org:azure:read / manage

Read (webhooks:read):

Method	Path	Description
`GET`	`/webhooks`	List all webhook configurations.
`GET`	`/webhooks/{id}`	Get a webhook by ID.
`GET`	`/webhooks/{id}/delivery-logs`	List delivery logs. Supports `?from=`, `?to=`, `?pageSize=`, `?continuationToken=`.
`GET`	`/webhooks/{id}/delivery-logs/{logId}?createdAt=`	Get a single delivery log entry. `createdAt` is the ISO-8601 partition key and is required.

Manage (webhooks:manage):

Method	Path	Description
`POST`	`/webhooks`	Create a webhook configuration.
`PUT`	`/webhooks/{id}`	Update a webhook configuration.
`DELETE`	`/webhooks/{id}`	Delete a webhook configuration.
`POST`	`/webhooks/{id}/pause`	Pause delivery.
`POST`	`/webhooks/{id}/resume`	Resume a paused webhook.
`POST`	`/webhooks/{id}/enable`	Re-enable a webhook auto-disabled by repeated delivery failures.
`POST`	`/webhooks/{id}/credentials`	Update webhook authentication credentials.
`POST`	`/webhooks/{id}/regenerate-secret`	Replace the webhook’s signing secret. The response’s `data.secret` is the only time the new secret is returned. The previous secret stops working immediately; authentication credentials are not changed.
`POST`	`/webhooks/{id}/test`	Send a test event.
`POST`	`/webhooks/{id}/delivery-logs/{logId}/redeliver?createdAt=`	Redeliver a previously failed event.

Read (org:service-accounts:read):

Method	Path	Description
`GET`	`/service-accounts`	List service accounts.
`GET`	`/service-accounts/{id}`	Get a service account by ID.

Manage (org:service-accounts:manage):

Method	Path	Description
`POST`	`/service-accounts`	Create a service account. Also needs the Admin organizational role.
`PUT`	`/service-accounts/{id}`	Update a service account. Also needs the Admin organizational role.
`DELETE`	`/service-accounts/{id}`	Delete a service account.
`POST`	`/service-accounts/{id}/disable`	Disable a service account.
`POST`	`/service-accounts/{id}/enable`	Re-enable a disabled service account. Also needs the Admin organizational role.
`POST`	`/service-accounts/{id}/credentials`	Issue a new credential. The `clientSecret` is returned once. Also needs the Admin organizational role.
`POST`	`/service-accounts/{id}/credentials/{credentialId}/revoke`	Revoke a credential.

Read (org:users:read):

Method	Path	Description
`GET`	`/users`	List organization users.
`GET`	`/users/profile`	Get the calling principal’s profile.
`POST`	`/users/workspace/users`	Get users for a specific workspace.

Manage (org:users:manage):

Method	Path	Description
`POST`	`/users`	Add users to the organization. A caller without the Admin organizational role can only add new users as Member, with no workspace access.
`PUT`	`/users`	Update a user. Needs the Admin organizational role.
`DELETE`	`/users/{id}`	Remove a user from the organization. Removing a user above Member needs the Admin organizational role, and the organization’s last Admin cannot be removed.

Roles (org:users:roles):

Method	Path	Description
`PUT`	`/users/organization/role`	Change a user’s organizational role. Needs the Admin organizational role.

Read (org:azure:read):

Method	Path	Description
`GET`	`/azure-resources/subscriptions`	List Azure subscriptions visible to the org’s tenant.
`GET`	`/azure-resources/subscriptions/is-owner?subscriptionId=`	Check whether the calling principal is an Owner of the subscription.
`GET`	`/azure-resources/subscriptions/{subscriptionId}/network-security-groups`	List NSGs in a subscription.
`GET`	`/azure-resources/subscriptions/{subscriptionId}/resource-groups`	List resource groups in a subscription.
`GET`	`/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/workspaces`	List Log Analytics workspaces in a resource group.
`GET`	`/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/sentinels`	List Sentinel instances in a resource group.
`GET`	`/azure-resources/subscriptions/{subscriptionId}/resource-groups/{resourceGroup}/workspaces/{workspaceName}/validate`	Validate a Sentinel-attached workspace.

Manage (org:azure:manage):

Method	Path	Description
`PUT`	`/azure-resources/analytical-rules/{ruleId}?enabled=true`	Enable or disable an analytical rule.

What Comes Back

Every successful response is wrapped in the standard envelope:

{
  "data": { /* … endpoint-specific payload … */ },
  "meta": {
    "requestId": "0HN8Q3V0001",
    "timestamp": "2026-04-15T20:00:00.0000000+00:00"
  }
}

List endpoints add a pagination block; see the object models page for shapes per endpoint family. Error responses are RFC 7807 ProblemDetails (application/problem+json) with a stable code extension you can switch on — the error reference lists every code.

​Workspace-Scoped Endpoints

​Closing an incident

​Cross-Workspace Endpoints

​Paginating /incidents/across-workspaces

​Syncing incident updates with filterByLastModified

​Organization-Scoped Endpoints

​What Comes Back

Workspace-Scoped Endpoints

Closing an incident

Cross-Workspace Endpoints

Paginating `/incidents/across-workspaces`

Syncing incident updates with `filterByLastModified`

Organization-Scoped Endpoints

What Comes Back