Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.contraforce.com/llms.txt

Use this file to discover all available pages before exploring further.

Use these models as a reference when building integrations. All request and response bodies use JSON (Content-Type: application/json). Every response is wrapped in the standard envelope.

​
Response Envelopes

​
Success response

{
  "data": { ... },
  "meta": {
    "requestId": "0HN8Q3V0001",
    "timestamp": "2026-04-15T20:00:00.0000000+00:00"
  }
}

​
Paginated response

{
  "data": [ ... ],
  "pagination": {
    "continuationToken": "eyJjb250...",
    "hasMore": true
  },
  "meta": {
    "requestId": "0HN8Q3V0001",
    "timestamp": "2026-04-15T20:00:00.0000000+00:00"
  }
}

​
Error response

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Incident 'INC-999' not found",
    "target": "incidentId",
    "details": ["No incident exists with the given ID in this workspace"]
  },
  "meta": {
    "requestId": "0HN8Q3V0002",
    "timestamp": "2026-04-15T20:01:00.0000000+00:00"
  }
}

​
Incidents

​
Incident object

Returned by GET /workspaces/{workspaceId}/incidents/{incidentId}: 
{
  "source": "Sentinel",
  "incident": {
    "id": "INC-12345",
    "title": "Suspicious sign-in from anonymous IP address",
    "severity": "High",
    "status": "Active",
    "workspaceId": "ws-abc123",
    "createdAt": "2026-04-15T10:30:00Z",
    "updatedAt": "2026-04-15T14:22:00Z"
  },
  "investigationDetails": {
    "entities": [ ],
    "alerts": [ ]
  },
  "evidence": { },
  "gamebookCatalog": { }
}

​
Update incident status

Request body for PUT /workspaces/{workspaceId}/incidents/{incidentId}/status: 
{
  "source": "Sentinel",
  "status": "Closed",
  "comment": "Confirmed benign. User was traveling.",
  "classification": "FalsePositive",
  "classificationReason": "InaccurateData"
}
Enum values:
FieldValues
sourceSentinel, DefenderXDR
statusNew, Active, Closed
classificationUndetermined, TruePositive, FalsePositive, BenignPositive
classificationReasonSuspiciousActivity, SuspiciousButExpected, ConfirmedActivity, InaccurateData, IncorrectAlertLogic, Other

​
Assign user to incident

Request body for PUT /workspaces/{workspaceId}/incidents/{incidentId}/assign: 
{
  "userId": "61eec97d-57b2-5b00-686e-8544a1b2c3d4",
  "email": "analyst@contoso.com",
  "source": "Sentinel"
}

​
Incident comment

Response object from GET /workspaces/{workspaceId}/incidents/{incidentId}/comments: 
{
  "id": "comment-001",
  "message": "Confirmed this was a legitimate admin action.",
  "createdTime": "2026-04-15T16:00:00Z",
  "authorEmail": "analyst@contoso.com",
  "authorName": "Jane Doe",
  "isActivityComment": false,
  "isAgentComment": false,
  "agentName": null,
  "isClosingComment": false,
  "ticketNoteId": null,
  "ticketId": null
}
Create/update request body for POST /workspaces/{workspaceId}/incidents/{incidentId}/comments: 
{
  "content": "Escalating to Tier 2 — lateral movement indicators confirmed.",
  "source": "Sentinel",
  "extensionId": "ext-sentinel-001"
}

​
List incidents across workspaces

Request body for POST /incidents/across-workspaces: 
{
  "severities": ["High", "Medium"],
  "statuses": ["New", "Active"],
  "sources": ["Sentinel", "DefenderXDR"],
  "timeFilterSelection": {
    "type": "SevenDays"
  },
  "isFirstCall": true,
  "query": "malware",
  "assigneeEmails": ["analyst@contoso.com"],
  "includeUnassigned": true
}
Time filter enum values for type: TwentyFourHours, SevenDays, ThirtyDays, Custom When using Custom, include customStartUtc and customEndUtc: 
{
  "timeFilterSelection": {
    "type": "Custom",
    "customStartUtc": "2026-04-01T00:00:00Z",
    "customEndUtc": "2026-04-15T23:59:59Z"
  }
}

​
Webhooks

​
Webhook configuration

Response object from GET /webhooks/{id}: 
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "serviceProviderId": "00000000-0000-0000-0000-000000000001",
  "targetAccountId": "00000000-0000-0000-0000-000000000001",
  "targetAccountName": "Contoso MSP",
  "workspaceId": null,
  "name": "SIEM-ingest-prod",
  "url": "https://siem.contoso.com/api/webhook",
  "status": "Active",
  "eventTypes": ["incident.created", "incident.updated"],
  "monitoredAccountIds": [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ],
  "authenticationType": "Bearer",
  "hasSigningToken": true,
  "disableReason": null,
  "disabledAt": null,
  "createdAt": "2026-03-01T12:00:00Z",
  "lastModifiedAt": "2026-04-10T09:30:00Z"
}

​
Create webhook

Request body for POST /webhooks: 
{
  "name": "SIEM-ingest-prod",
  "url": "https://siem.contoso.com/api/webhook",
  "eventTypes": ["incident.created", "incident.updated"],
  "monitoredAccountIds": [
    "11111111-1111-1111-1111-111111111111"
  ],
  "authenticationType": "Bearer",
  "token": "your-bearer-token",
  "signingToken": "your-hmac-signing-secret"
}
Enum values for authenticationType: None, Bearer, Basic, ApiKey

​
Delivery log

Response object from GET /webhooks/{id}/delivery-logs/{logId}: 
{
  "id": "log-001",
  "webhookConfigurationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "incident.created",
  "httpStatusCode": 200,
  "success": true,
  "requestUrl": "https://siem.contoso.com/api/webhook",
  "requestHeaders": { "Content-Type": "application/json" },
  "requestBody": "{ ... }",
  "responseBody": "OK",
  "durationMs": 142,
  "createdAt": "2026-04-15T19:30:00Z",
  "redelivered": false
}

​
Service Accounts

​
Service account

Response object from GET /service-accounts/{id}: 
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "accountId": "00000000-0000-0000-0000-000000000001",
  "name": "Jira-incident-sync-prod",
  "description": "Syncs incidents to Jira Service Management",
  "isActive": true,
  "organizationalRole": "Member",
  "clientSecretPrefix": "cf_sa_",
  "credentialExpirationDate": "2027-04-15T00:00:00Z",
  "workspaceAssignments": [
    {
      "workspaceId": "ws-abc123",
      "workspaceName": "Contoso Prod",
      "role": "Analyst"
    }
  ],
  "credentials": [
    {
      "id": "cred-001",
      "scopes": ["incidents:read", "incidents:write"],
      "status": "Active",
      "expiresAt": "2027-04-15T00:00:00Z",
      "lastUsedAt": "2026-04-15T19:00:00Z",
      "createdAt": "2026-04-01T12:00:00Z"
    }
  ],
  "lastUsedAt": "2026-04-15T19:00:00Z",
  "createdAt": "2026-04-01T12:00:00Z",
  "lastModifiedAt": "2026-04-10T09:30:00Z"
}

​
Create service account

Request body for POST /service-accounts: 
{
  "name": "Jira-incident-sync-prod",
  "description": "Syncs incidents to Jira Service Management",
  "organizationalRole": "Member",
  "workspaceAssignments": [
    {
      "workspaceId": "ws-abc123",
      "role": "Analyst"
    }
  ],
  "scopes": ["incidents:read", "incidents:write"],
  "expirationDate": "2027-04-15T00:00:00Z"
}

​
Credential created (shown once)

Response from POST /service-accounts/{id}/credentials: 
{
  "clientId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "clientSecret": "cf_sa_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345678==",
  "id": "cred-002",
  "scopes": ["incidents:read"],
  "status": "Active",
  "expiresAt": "2027-04-15T00:00:00Z",
  "lastUsedAt": null,
  "createdAt": "2026-04-15T20:00:00Z"
}
The clientSecret is returned only once in this response. Store it immediately in a secrets manager.

​
Users

​
User object

Response object from GET /users/{userId}: 
{
  "id": "61eec97d-57b2-5b00-686e-8544a1b2c3d4",
  "displayName": "Jane Doe",
  "email": "jane.doe@contoso.com",
  "organizationalRole": "Member",
  "isActive": true
}