> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tracecat.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cases

## `core.cases.create_case`

Create a new case.

### Inputs

<ParamField path="description" type="string" required>
  The description of the case.
</ParamField>

<ParamField path="summary" type="string" required>
  The summary of the case.
</ParamField>

<ParamField path="dropdown_values" type="array[CaseDropdownValueInput] | null">
  Dropdown selections to set on the case. Each item must include either definition\_id or definition\_ref, and either option\_id or option\_ref (or null to clear).

  Default: `null`.
</ParamField>

<ParamField path="fields" type="object | null">
  Custom fields for the case.

  Default: `null`.
</ParamField>

<ParamField path="payload" type="object | null">
  Payload for the case.

  Default: `null`.
</ParamField>

<ParamField path="priority" type="string">
  The priority of the case.

  Default: `"unknown"`.

  Allowed values: `unknown`, `low`, `medium`, `high`, `critical`, `other`.
</ParamField>

<ParamField path="severity" type="string">
  The severity of the case.

  Default: `"unknown"`.

  Allowed values: `unknown`, `informational`, `low`, `medium`, `high`, `critical`, `fatal`, `other`.
</ParamField>

<ParamField path="status" type="string">
  The status of the case.

  Default: `"unknown"`.

  Allowed values: `unknown`, `new`, `in_progress`, `on_hold`, `resolved`, `closed`, `other`.
</ParamField>

<ParamField path="tags" type="array[string] | null">
  List of tag identifiers (IDs or refs) to add to the case.

  Default: `null`.
</ParamField>

### Examples

**Create and fetch a case**

```yaml theme={null}
- ref: create_case
  action: core.cases.create_case
  args:
    summary: "Investigate alert ${{ TRIGGER.alert_id }}"
    description: "Created from workflow trigger."
    priority: high
    severity: high
    tags:
      - phishing
- ref: get_case
  action: core.cases.get_case
  depends_on:
    - create_case
  args:
    case_id: ${{ ACTIONS.create_case.result.id }}
```

## `core.cases.get_case`

Get details of a specific case by ID.

### Inputs

<ParamField path="case_id" type="string" required>
  The ID of the case to retrieve.
</ParamField>

### Examples

**Create and fetch a case**

```yaml theme={null}
- ref: create_case
  action: core.cases.create_case
  args:
    summary: "Investigate alert ${{ TRIGGER.alert_id }}"
    description: "Created from workflow trigger."
    priority: high
    severity: high
    tags:
      - phishing
- ref: get_case
  action: core.cases.get_case
  depends_on:
    - create_case
  args:
    case_id: ${{ ACTIONS.create_case.result.id }}
```

## `core.cases.update_case`

Update an existing case.

### Inputs

<ParamField path="case_id" type="string" required>
  The ID of the case to update.
</ParamField>

<ParamField path="append" type="boolean">
  If true, append the provided description to the existing description when it is not empty.

  Default: `false`.
</ParamField>

<ParamField path="description" type="string | null">
  The updated description of the case.

  Default: `null`.
</ParamField>

<ParamField path="dropdown_values" type="array[CaseDropdownValueInput] | null">
  Dropdown selections to set or clear. Each item must include either definition\_id or definition\_ref, and either option\_id or option\_ref (or null to clear).

  Default: `null`.
</ParamField>

<ParamField path="fields" type="object | null">
  Updated custom fields for the case.

  Default: `null`.
</ParamField>

<ParamField path="payload" type="object | null">
  Updated payload for the case.

  Default: `null`.
</ParamField>

<ParamField path="priority" type="string | null">
  The updated priority of the case.

  Default: `null`.
</ParamField>

<ParamField path="severity" type="string | null">
  The updated severity of the case.

  Default: `null`.
</ParamField>

<ParamField path="status" type="string | null">
  The updated status of the case.

  Default: `null`.
</ParamField>

<ParamField path="summary" type="string | null">
  The updated summary of the case.

  Default: `null`.
</ParamField>

<ParamField path="tags" type="array[string] | null">
  List of tag identifiers (IDs or refs) to set on the case. This will replace all existing tags.

  Default: `null`.
</ParamField>

### Examples

**Update case fields**

```yaml theme={null}
- ref: update_case
  action: core.cases.update_case
  args:
    case_id: ${{ TRIGGER.case_id }}
    status: in_progress
    priority: critical
    append: true
    description: |
      Analyst note:
      - Escalated after credential theft indicators were confirmed.
```

## `core.cases.list_cases`

List all cases.

### Inputs

<ParamField path="cursor" type="string | null">
  Pagination cursor used to fetch a specific page when paginate=true.

  Default: `null`.
</ParamField>

<ParamField path="limit" type="integer">
  Maximum number of cases to return.

  Default: `100`.
</ParamField>

<ParamField path="order_by" type="string | null">
  The field to order the cases by.

  Default: `null`.
</ParamField>

<ParamField path="paginate" type="boolean">
  If true, return cursor pagination metadata along with items.

  Default: `false`.
</ParamField>

<ParamField path="reverse" type="boolean">
  Reverse pagination direction when paginate=true.

  Default: `false`.
</ParamField>

<ParamField path="sort" type="string | null">
  The direction to order the cases by.

  Default: `null`.
</ParamField>

### Examples

**List, search, and inspect case activity**

```yaml theme={null}
- ref: list_cases
  action: core.cases.list_cases
  args:
    limit: 25
    order_by: updated_at
    sort: desc
- ref: search_cases
  action: core.cases.search_cases
  args:
    search_term: phishing
    status:
      - new
      - in_progress
    limit: 25
- ref: case_events
  action: core.cases.list_case_events
  args:
    case_id: ${{ TRIGGER.case_id }}
```

## `core.cases.search_cases`

Search cases based on various criteria.

### Inputs

<ParamField path="assignee_id" type="string | array[string] | null">
  Filter by assignee ID or 'unassigned'.

  Default: `null`.
</ParamField>

<ParamField path="cursor" type="string | null">
  Pagination cursor used to fetch a specific page when paginate=true.

  Default: `null`.
</ParamField>

<ParamField path="dropdown" type="array[string] | null">
  Filter by dropdown values in definition\_ref:option\_ref format.

  Default: `null`.
</ParamField>

<ParamField path="end_time" type="string | null">
  Filter cases created before this time.

  Default: `null`.
</ParamField>

<ParamField path="limit" type="integer">
  Maximum number of cases to return.

  Default: `100`.
</ParamField>

<ParamField path="order_by" type="string | null">
  The field to order the cases by.

  Default: `null`.
</ParamField>

<ParamField path="paginate" type="boolean">
  If true, return cursor pagination metadata along with items.

  Default: `false`.
</ParamField>

<ParamField path="priority" type="string | array[string] | null">
  Filter by case priority.

  Default: `null`.
</ParamField>

<ParamField path="reverse" type="boolean">
  Reverse pagination direction when paginate=true.

  Default: `false`.
</ParamField>

<ParamField path="search_term" type="string | null">
  Text to search for in case summary and description.

  Default: `null`.
</ParamField>

<ParamField path="severity" type="string | array[string] | null">
  Filter by case severity.

  Default: `null`.
</ParamField>

<ParamField path="sort" type="string | null">
  The direction to order the cases by.

  Default: `null`.
</ParamField>

<ParamField path="start_time" type="string | null">
  Filter cases created after this time.

  Default: `null`.
</ParamField>

<ParamField path="status" type="string | array[string] | null">
  Filter by case status.

  Default: `null`.
</ParamField>

<ParamField path="tags" type="array[string] | null">
  Filter by tag IDs or refs (AND logic).

  Default: `null`.
</ParamField>

<ParamField path="updated_after" type="string | null">
  Filter cases updated after this time.

  Default: `null`.
</ParamField>

<ParamField path="updated_before" type="string | null">
  Filter cases updated before this time.

  Default: `null`.
</ParamField>

### Examples

**List, search, and inspect case activity**

```yaml theme={null}
- ref: list_cases
  action: core.cases.list_cases
  args:
    limit: 25
    order_by: updated_at
    sort: desc
- ref: search_cases
  action: core.cases.search_cases
  args:
    search_term: phishing
    status:
      - new
      - in_progress
    limit: 25
- ref: case_events
  action: core.cases.list_case_events
  args:
    case_id: ${{ TRIGGER.case_id }}
```

## `core.cases.list_case_events`

List all events for a case in chronological order.

### Inputs

<ParamField path="case_id" type="string" required>
  The ID of the case to get events for.
</ParamField>

### Examples

**List, search, and inspect case activity**

```yaml theme={null}
- ref: list_cases
  action: core.cases.list_cases
  args:
    limit: 25
    order_by: updated_at
    sort: desc
- ref: search_cases
  action: core.cases.search_cases
  args:
    search_term: phishing
    status:
      - new
      - in_progress
    limit: 25
- ref: case_events
  action: core.cases.list_case_events
  args:
    case_id: ${{ TRIGGER.case_id }}
```

## `core.cases.assign_user`

Assign a user to an existing case.

### Inputs

<ParamField path="assignee_id" type="string" required>
  The ID of the user to assign to the case.
</ParamField>

<ParamField path="case_id" type="string" required>
  The ID of the case to assign a user to.
</ParamField>

### Examples

**Assign a case**

```yaml theme={null}
- ref: assign_by_id
  action: core.cases.assign_user
  args:
    case_id: ${{ TRIGGER.case_id }}
    assignee_id: ${{ TRIGGER.assignee_id }}
- ref: assign_by_email
  action: core.cases.assign_user_by_email
  args:
    case_id: ${{ TRIGGER.case_id }}
    assignee_email: analyst@example.com
```

## `core.cases.assign_user_by_email`

Assign a user to an existing case by email.

### Inputs

<ParamField path="assignee_email" type="string" required>
  The email of the user to assign to the case.
</ParamField>

<ParamField path="case_id" type="string" required>
  The ID of the case to assign a user to.
</ParamField>

### Examples

**Assign a case**

```yaml theme={null}
- ref: assign_by_id
  action: core.cases.assign_user
  args:
    case_id: ${{ TRIGGER.case_id }}
    assignee_id: ${{ TRIGGER.assignee_id }}
- ref: assign_by_email
  action: core.cases.assign_user_by_email
  args:
    case_id: ${{ TRIGGER.case_id }}
    assignee_email: analyst@example.com
```

## `core.cases.add_case_tag`

Add a tag to a case by tag ID or ref.

### Inputs

<ParamField path="case_id" type="string" required>
  The ID of the case to add a tag to.
</ParamField>

<ParamField path="tag" type="string" required>
  The tag identifier (ID or ref) to add to the case.
</ParamField>

<ParamField path="create_if_missing" type="boolean">
  If true, create the tag if it does not exist.

  Default: `false`.
</ParamField>

### Examples

**Add and remove tags**

```yaml theme={null}
- ref: add_tag
  action: core.cases.add_case_tag
  args:
    case_id: ${{ TRIGGER.case_id }}
    tag: credential-theft
    create_if_missing: true
- ref: remove_tag
  action: core.cases.remove_case_tag
  args:
    case_id: ${{ TRIGGER.case_id }}
    tag: needs-triage
```

## `core.cases.remove_case_tag`

Remove a tag from a case by tag ID or ref.

### Inputs

<ParamField path="case_id" type="string" required>
  The ID of the case to remove a tag from.
</ParamField>

<ParamField path="tag" type="string" required>
  The tag identifier (ID or ref) to remove from the case.
</ParamField>

### Examples

**Add and remove tags**

```yaml theme={null}
- ref: add_tag
  action: core.cases.add_case_tag
  args:
    case_id: ${{ TRIGGER.case_id }}
    tag: credential-theft
    create_if_missing: true
- ref: remove_tag
  action: core.cases.remove_case_tag
  args:
    case_id: ${{ TRIGGER.case_id }}
    tag: needs-triage
```

## `core.cases.delete_case`

Delete a case.

### Inputs

<ParamField path="case_id" type="string" required>
  The ID of the case to delete.
</ParamField>

### Examples

**Delete a case**

```yaml theme={null}
- ref: close_case
  action: core.cases.update_case
  args:
    case_id: ${{ TRIGGER.case_id }}
    status: closed
- ref: delete_case
  action: core.cases.delete_case
  depends_on:
    - close_case
  args:
    case_id: ${{ TRIGGER.case_id }}
```