Contraforce Service tickets API

openapi: 3.2.0
info:
  title: ContraForce Service tickets API
  description: ContraForce platform API for security operations management.
  version: '2.0'
tags:
- name: Service tickets
paths:
  /api/v2/workspaces/{workspaceId}/tickets/search:
    get:
      tags:
      - Service tickets
      summary: Search tickets
      operationId: v2-search-tickets
      parameters:
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      - name: groupingId
        in: query
        schema:
          type: string
      - name: ticketNumber
        in: query
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedApiResponseOfServiceTicketResponse'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/workspaces/{workspaceId}/tickets/link:
    post:
      tags:
      - Service tickets
      summary: Link ticket
      description: 'Links an existing ticket in the workspace''s connected ticketing system to an incident.


        `ticketId` must be the ticketing system''s record id, not the ticket number people see:


        | Ticketing system | Send | Not |

        | --- | --- | --- |

        | ServiceNow | The incident `sys_id` (32 hex characters) | The incident number, such as `INC0049162` |

        | Jira Service Management | The issue id or the issue key, such as `SUP-123` | |

        | Autotask | The numeric ticket id | The ticket number, such as `T20261007.0001` |


        If you only have the ticket number, call `GET /api/v2/workspaces/{workspaceId}/tickets/search?ticketNumber=` first and send the `id` of the matching ticket (`serviceNowTicket.id`, `jiraTicket.id` or `autotaskTicket.id`). When the ticketing system cannot find a ticket with the given id, the request returns `400` with "Unable to find the selected ticket".'
      operationId: v2-link-ticket
      parameters:
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkServiceTicketRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfServiceTicketResponse'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/workspaces/{workspaceId}/tickets/unlink:
    post:
      tags:
      - Service tickets
      summary: Unlink ticket
      operationId: v2-unlink-ticket
      parameters:
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UnlinkServiceTicketRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfboolean'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
  /api/v2/workspaces/{workspaceId}/tickets/priority:
    put:
      tags:
      - Service tickets
      summary: Update ticket priority
      operationId: v2-update-ticket-priority
      parameters:
      - name: workspaceId
        in: path
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ServiceTicketUpdatePriorityRequest'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiResponseOfboolean'
        '400':
          description: Bad request — validation or parameter binding failed.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '401':
          description: Unauthorized — missing or invalid Bearer token.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '403':
          description: Forbidden — insufficient scope or workspace access.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '404':
          description: Not found — workspace or resource is missing.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
        '500':
          description: Internal server error.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ApiProblemDetails'
components:
  schemas:
    ResponseMeta:
      type: object
      properties:
        requestId:
          type:
          - 'null'
          - string
        timestamp:
          type:
          - 'null'
          - string
    ServiceNowTicketCommentResponse:
      type: object
      properties:
        sysId:
          type:
          - 'null'
          - string
          description: ServiceNow journal entry sys_id.
        elementId:
          type:
          - 'null'
          - string
          description: sys_id of the record the comment belongs to.
        value:
          type:
          - 'null'
          - string
          description: Comment text.
        createdOn:
          type: string
          description: When the comment was created.
          format: date-time
        createdBy:
          type:
          - 'null'
          - string
          description: ServiceNow user who created the comment.
        element:
          type:
          - 'null'
          - string
          description: Journal field the comment was written to.
      description: v2 view of a comment on a ServiceNow incident.
    JiraRequestTypeResponse:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
          description: Request type id.
        name:
          type:
          - 'null'
          - string
          description: Request type name.
      description: v2 view of a Jira Service Management request type.
    JiraTicketPriorityUpdateRequest:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        priorityId:
          type:
          - 'null'
          - string
        priorityName:
          type:
          - 'null'
          - string
    JiraIssueTypeResponse:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
          description: Issue type id.
        name:
          type:
          - 'null'
          - string
          description: Issue type name.
        projectId:
          type:
          - 'null'
          - string
          description: Project the issue type belongs to.
        subtask:
          type: boolean
          description: Whether the issue type is a subtask type.
      description: v2 view of a Jira issue type.
    IncidentReference:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        source:
          $ref: '#/components/schemas/IncidentSource'
        workspaceId:
          type:
          - 'null'
          - string
        number:
          type:
          - 'null'
          - string
    AuditedResourceType:
      enum:
      - None
      - Incident
      - Account
      description: Specifies the types of resources that can be audited within the system.
    ServiceTicketAutotaskPriority:
      enum:
      - High
      - Medium
      - Low
      - Critical
      description: Autotask ticket priorities in the v2 service-ticket contract.
    AutotaskTicketPriority:
      enum:
      - High
      - Medium
      - Low
      - Critical
    ApiProblemDetails:
      type: object
      properties:
        type:
          type:
          - 'null'
          - string
        title:
          type:
          - 'null'
          - string
        status:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
          format: int32
        detail:
          type:
          - 'null'
          - string
        instance:
          type:
          - 'null'
          - string
        code:
          type:
          - 'null'
          - string
        requestId:
          type:
          - 'null'
          - string
        timestamp:
          type:
          - 'null'
          - string
        target:
          type:
          - 'null'
          - string
        errors:
          type:
          - 'null'
          - object
          additionalProperties:
            type: array
            items:
              type: string
      description: 'API extension of ProblemDetails that surfaces the stable error code,

        trace identifier, timestamp, optional target, and optional field-keyed validation

        error map alongside the RFC 7807 members.'
    ServiceNowTicketResponse:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
          description: ServiceNow record sys_id.
        description:
          type:
          - 'null'
          - string
          description: Incident description.
        shortDescription:
          type:
          - 'null'
          - string
          description: Incident short description.
        number:
          type:
          - 'null'
          - string
          description: Incident number as ServiceNow shows it.
        state:
          description: Incident state.
          $ref: '#/components/schemas/ServiceTicketServiceNowState'
        urgency:
          description: Incident urgency.
          $ref: '#/components/schemas/ServiceTicketServiceNowUrgency'
        comments:
          type:
          - 'null'
          - array
          items:
            description: v2 view of a comment on a ServiceNow incident.
            $ref: '#/components/schemas/ServiceNowTicketCommentResponse'
          description: Comments on the incident; null when they were not loaded.
      description: v2 view of a ServiceNow incident linked as a ticket.
    AutotaskTicketResponse:
      type: object
      properties:
        id:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Autotask ticket id.
          format: int32
        companyId:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Autotask company the ticket belongs to.
          format: int32
        projectId:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
          description: Autotask project the ticket belongs to, if any.
          format: int32
        assignedResourceId:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
          description: Resource the ticket is assigned to, if any.
          format: int64
        assignedResourceRoleId:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
          description: Role of the assigned resource, if any.
          format: int64
        billingCodeId:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - 'null'
          - integer
          - string
          description: Billing code, if any.
          format: int32
        categoryId:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Ticket category id.
          format: int32
        number:
          type:
          - 'null'
          - string
          description: Ticket number as Autotask shows it.
        type:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Autotask ticket type id.
          format: int32
        title:
          type:
          - 'null'
          - string
          description: Ticket title.
        description:
          type:
          - 'null'
          - string
          description: Ticket description.
        priority:
          description: Ticket priority.
          $ref: '#/components/schemas/ServiceTicketAutotaskPriority'
        status:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Autotask status id.
          format: int32
        queueId:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Autotask queue id.
          format: int32
        dueDateTime:
          type: string
          description: When the ticket is due.
          format: date-time
        notes:
          type:
          - 'null'
          - array
          items:
            description: v2 view of a note on an Autotask ticket.
            $ref: '#/components/schemas/AutotaskTicketNoteResponse'
          description: Notes on the ticket; null when they were not loaded.
      description: v2 view of an Autotask ticket.
    JiraUserResponse:
      type: object
      properties:
        accountId:
          type:
          - 'null'
          - string
          description: Atlassian account id.
        displayName:
          type:
          - 'null'
          - string
          description: Display name.
        active:
          type: boolean
          description: Whether the account is active.
      description: v2 view of a Jira user.
    UnlinkServiceTicketRequest:
      type: object
      properties:
        incident:
          $ref: '#/components/schemas/IncidentReference'
    JiraStatusResponse:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
          description: Status id.
        name:
          type:
          - 'null'
          - string
          description: Status name.
      description: v2 view of a Jira issue status.
    AutotaskTicketPriorityUpdateRequest:
      type: object
      properties:
        id:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          format: int32
        priority:
          $ref: '#/components/schemas/AutotaskTicketPriority'
    JiraPriorityResponse:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
          description: Priority id.
        name:
          type:
          - 'null'
          - string
          description: Priority name.
      description: v2 view of a Jira priority.
    IncidentSource:
      enum:
      - Sentinel
      - DefenderXDR
      - QRadar
      - Splunk
      - CrowdStrike
      - SentinelOne
      - SumoLogic
    JiraProjectResponse:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
          description: Project id.
        name:
          type:
          - 'null'
          - string
          description: Project name.
        key:
          type:
          - 'null'
          - string
          description: Project key.
      description: v2 view of a Jira Service Management project.
    ServiceNowTicketUrgencyUpdateRequest:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
        urgency:
          $ref: '#/components/schemas/ServiceNowTicketUrgency'
    ServiceTicketUpdatePriorityRequest:
      type: object
      properties:
        autotaskRequest:
          $ref: '#/components/schemas/AutotaskTicketPriorityUpdateRequest'
        serviceNowRequest:
          $ref: '#/components/schemas/ServiceNowTicketUrgencyUpdateRequest'
        jiraRequest:
          $ref: '#/components/schemas/JiraTicketPriorityUpdateRequest'
        resourceId:
          type:
          - 'null'
          - string
          description: Gets or sets the unique identifier of the associated resource. Used to identify the target resource like Incident IDs.
        resourceType:
          description: Gets or sets the type of the resource represented by this instance.
          $ref: '#/components/schemas/AuditedResourceType'
        resourceName:
          type:
          - 'null'
          - string
          description: An optional human-readable name of the resource.
      description: This DTO is a wrapper for priority (urgency for Snow) update calls.
    ApiResponseOfboolean:
      type: object
      properties:
        data:
          type: boolean
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ServiceTicketServiceNowState:
      enum:
      - New
      - InProgress
      - OnHold
      - Resolved
      - Closed
      - Canceled
      description: ServiceNow incident states in the v2 service-ticket contract.
    ApiResponseOfServiceTicketResponse:
      type: object
      properties:
        data:
          description: v2 view of an incident's service ticket in the workspace's connected ticketing system.
          $ref: '#/components/schemas/ServiceTicketResponse'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for single-item responses.
    ServiceTicketServiceNowUrgency:
      enum:
      - High
      - Medium
      - Low
      description: ServiceNow urgency levels in the v2 service-ticket contract.
    ServiceNowTicketUrgency:
      enum:
      - High
      - Medium
      - Low
    ServiceTicketProvider:
      enum:
      - Autotask
      - ServiceNow
      - Jira
      - Zendesk
      - None
      description: Ticketing systems in the v2 service-ticket contract.
    PaginatedApiResponseOfServiceTicketResponse:
      type: object
      properties:
        data:
          type:
          - 'null'
          - array
          items:
            description: v2 view of an incident's service ticket in the workspace's connected ticketing system.
            $ref: '#/components/schemas/ServiceTicketResponse'
        pagination:
          $ref: '#/components/schemas/PaginationInfo'
        meta:
          $ref: '#/components/schemas/ResponseMeta'
      description: Standard v2 API response envelope for paginated list responses.
    ServiceTicketResponse:
      type: object
      properties:
        autotaskTicket:
          description: The linked Autotask ticket; null unless the workspace uses Autotask and a ticket was returned.
          $ref: '#/components/schemas/AutotaskTicketResponse'
        serviceNowTicket:
          description: The linked ServiceNow incident; null unless the workspace uses ServiceNow and a ticket was returned.
          $ref: '#/components/schemas/ServiceNowTicketResponse'
        jiraTicket:
          description: The linked Jira Service Management issue; null unless the workspace uses Jira and a ticket was returned.
          $ref: '#/components/schemas/JiraTicketResponse'
        ticketingSystemType:
          description: The ticketing system the workspace is connected to.
          $ref: '#/components/schemas/ServiceTicketProvider'
        isTicketSet:
          type: boolean
          description: Whether a ticket was returned.
        unavailableTicketId:
          type:
          - 'null'
          - string
          description: Provider id of the incident's linked ticket when the provider no longer returns it; otherwise null.
        isTicketUnavailable:
          type: boolean
          description: Whether the incident is linked to a ticket the provider no longer returns.
      description: v2 view of an incident's service ticket in the workspace's connected ticketing system.
    PaginationInfo:
      type: object
      properties:
        continuationToken:
          type:
          - 'null'
          - string
        hasMore:
          type: boolean
    LinkServiceTicketRequest:
      type: object
      properties:
        ticketId:
          type:
          - 'null'
          - string
          description: 'Record id of the ticket in the connected ticketing system: the ServiceNow `sys_id`, the Jira issue id or key, or the numeric Autotask ticket id. Ticket numbers such as `INC0049162` are not accepted; resolve them with `GET tickets/search?ticketNumber=` and send the returned `id`.'
          examples:
          - 9d385017c611228701d22104cc95c371
        incident:
          $ref: '#/components/schemas/IncidentReference'
    AutotaskTicketNoteResponse:
      type: object
      properties:
        id:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Autotask note id.
          format: int32
        description:
          type:
          - 'null'
          - string
          description: Note text.
        ticketId:
          pattern: ^-?(?:0|[1-9]\d*)$
          type:
          - integer
          - string
          description: Ticket the note belongs to.
          format: int32
        title:
          type:
          - 'null'
          - string
          description: Note title.
      description: v2 view of a note on an Autotask ticket.
    JiraTicketResponse:
      type: object
      properties:
        id:
          type:
          - 'null'
          - string
          description: Jira issue id.
        description:
          type:
          - 'null'
          - string
          description: Issue description.
        summary:
          type:
          - 'null'
          - string
          description: Issue summary.
        number:
          type:
          - 'null'
          - string
          description: Issue key as Jira shows it.
        currentStatus:
          description: Current issue status.
          $ref: '#/components/schemas/JiraStatusResponse'
        priority:
          description: Issue priority.
          $ref: '#/components/schemas/JiraPriorityResponse'
        assignee:
          description: User the issue is assigned to, if any.
          $ref: '#/components/schemas/JiraUserResponse'
        project:
          description: Service desk project the issue belongs to.
          $ref: '#/components/schemas/JiraProjectResponse'
        issueType:
          description: Issue type.
          $ref: '#/components/schemas/JiraIssueTypeResponse'
        requestType:
          description: Service desk request type.
          $ref: '#/components/schemas/JiraRequestTypeResponse'
        labels:
          type:
          - 'null'
          - array
          items:
            type: string
          description: Issue labels.
        availablePriorities:
          type:
          - 'null'
          - array
          items:
            description: v2 view of a Jira priority.
            $ref: '#/components/schemas/JiraPriorityResponse'
          description: Priorities the issue can be set to.
        availableStatuses:
          type:
          - 'null'
          - array
          items:
            description: v2 view of a Jira issue status.
            $ref: '#/components/schemas/JiraStatusResponse'
          description: Statuses the issue can move to from its current status.
      description: v2 view of a Jira Service Management issue linked as a ticket.