> ## 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.

# Object Models

> Copy-pasteable JSON request and response examples for the ContraForce v2 API.

Use these models as a reference when building integrations. Request and response bodies use `application/json` (or `multipart/form-data` for SOP uploads). Successful responses are wrapped in the standard envelope; error responses follow RFC 7807 ProblemDetails — see the [error reference](/api-reference/errors) for the full catalogue.

***

## Response Envelopes

### Success response

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

### Paginated response

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

### Error response

Errors are RFC 7807 ProblemDetails, served as `application/problem+json`. Switch on the stable `code` extension; the `title` and `detail` strings are human-readable and may be reworded between releases.

```json theme={null}
{
  "type": "about:blank",
  "title": "Resource not found",
  "status": 404,
  "detail": "Incident 'INC-12345' not found",
  "instance": "/api/v2/workspaces/.../incidents/Sentinel/INC-12345",
  "code": "NOT_FOUND",
  "requestId": "0HN8Q3V0002",
  "timestamp": "2026-04-15T20:01:00.0000000+00:00"
}
```

The full set of `code` values, validation `errors` map shape, and resolution guidance live on the [error reference](/api-reference/errors) page.

***

## Incidents

### Incident object

Returned by `GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}`:

```json theme={null}
{
  "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": { }
}
```

**Enum values:**

| Field      | Values                                                                      |
| ---------- | --------------------------------------------------------------------------- |
| `source`   | `Sentinel`, `DefenderXDR`, `CrowdStrike`, `QRadar`, `Splunk`, `SentinelOne` |
| `severity` | `Informational`, `Low`, `Medium`, `High`                                    |
| `status`   | `New`, `Active`, `Closed`                                                   |

### Incident comment

Response object from `GET /workspaces/{workspaceId}/incidents/{source}/{incidentId}/comments`:

```json theme={null}
{
  "id": "comment-001",
  "message": "Confirmed this was a legitimate admin action.",
  "createdTime": "2026-04-15T16:00:00Z",
  "authorEmail": "analyst@contoso.example",
  "authorName": "Jane Doe",
  "isActivityComment": false,
  "isAgentComment": false,
  "agentName": null,
  "isClosingComment": false,
  "ticketNoteId": null,
  "ticketId": null
}
```

### List incidents across workspaces

Request body for `POST /incidents/across-workspaces`:

```json theme={null}
{
  "severities": ["High", "Medium"],
  "statuses": ["New", "Active"],
  "sources": ["Sentinel", "DefenderXDR"],
  "timeFilterSelection": {
    "type": "SevenDays"
  },
  "isFirstCall": true,
  "query": "malware",
  "assigneeEmails": ["analyst@contoso.example"],
  "includeUnassigned": true
}
```

**Time filter enum values for `type`:** `TwentyFourHours`, `SevenDays`, `ThirtyDays`, `Custom`

When using `Custom`, include `customStartUtc` and `customEndUtc`:

```json theme={null}
{
  "timeFilterSelection": {
    "type": "Custom",
    "customStartUtc": "2026-04-01T00:00:00Z",
    "customEndUtc": "2026-04-15T23:59:59Z"
  }
}
```

***

## Webhooks

### Webhook configuration

Response object from `GET /webhooks/{id}`:

```json theme={null}
{
  "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.example/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`:

```json theme={null}
{
  "name": "SIEM-ingest-prod",
  "url": "https://siem.contoso.example/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}`:

```json theme={null}
{
  "id": "log-001",
  "webhookConfigurationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "eventType": "incident.created",
  "httpStatusCode": 200,
  "success": true,
  "requestUrl": "https://siem.contoso.example/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}`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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`:

```json theme={null}
{
  "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"
}
```

<Warning>
  The `clientSecret` is returned **only once** in this response. Store it immediately in a secrets manager.
</Warning>

***

## Users

### User object

Response object from `GET /users/{userId}`:

```json theme={null}
{
  "id": "61eec97d-57b2-5b00-686e-8544a1b2c3d4",
  "displayName": "Jane Doe",
  "email": "jane.doe@contoso.example",
  "organizationalRole": "Member",
  "isActive": true
}
```