[DOCS] Add create case and update case APIs

docs/api/cases.asciidoc

@@ -5,7 +5,7 @@ You can create, manage, configure, and send cases to external systems with
 these APIs:
 
 * {security-guide}/cases-api-add-comment.html[Add comment]
-* {security-guide}/cases-api-create.html[Create case]
+* <<cases-api-create>>
 * {security-guide}/cases-api-delete-case.html[Delete case]
 * {security-guide}/cases-api-delete-all-comments.html[Delete all comments]
 * {security-guide}/cases-api-delete-comment.html[Delete comment]
@@ -24,5 +24,8 @@ these APIs:
 * {security-guide}/cases-api-push.html[Push case]
 * {security-guide}/assign-connector.html[Set default Elastic Security UI connector]
 * {security-guide}/case-api-update-connector.html[Update case configurations]
-* {security-guide}/cases-api-update.html[Update case]
+* <<cases-api-update>>
 * {security-guide}/cases-api-update-comment.html[Update comment]
+
+include::cases/cases-api-create.asciidoc[leveloffset=+1]
+include::cases/cases-api-update.asciidoc[leveloffset=+1]

docs/api/cases/cases-api-create.asciidoc

@@ -0,0 +1,203 @@
+[[cases-api-create]]
+== Create case API
+++++
+<titleabbrev>Create case</titleabbrev>
+++++
+
+Creates a case.
+
+=== Request
+
+`POST <kibana host>:<port>/api/cases`
+
+=== Prerequisite
+
+You must have `all` privileges for the *Cases* feature in the *Management*,
+*{observability}*, or *Security* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+=== Request body
+
+`connector`::
+(Required, object) An object that contains the connector configuration.
++
+.Properties of `connector`
+[%collapsible%open]
+====
+`fields`::
+(Required, object) An object containing the connector fields.
++
+--
+To create a case without a connector, specify `null`. If you want to omit any
+individual field, specify `null` as its value.
+
+For {sn-itsm} connectors, refer to <<servicenow-action-configuration>>. For
+example:
+
+* `urgency`: The extent to which the incident resolution can delay.
+* `severity`: The severity of the incident.
+* `impact`: The effect an incident had on business.
+* `category`: The category of the incident.
+* `subcategory`: The subcategory of the incident.
+
+For {sn-sir} connectors, refer to <<servicenow-sir-action-configuration>>. For example:
+
+////
+//TBD: Are these valid? They don't appear in the action docs
+* `destIp`: A comma separated list of destination IPs.
+* `malwareHash`: A comma separated list of malware hashes.
+* `malwareUrl`: A comma separated list of malware URLs.
+* `sourceIp`: A comma separated list of source IPs.
+////
+* `priority`: The priority of the incident.
+* `category`: The category of the incident.
+* `subcategory`: The subcategory of the incident.
+
+For {jira} connectors, refer to <<jira-action-configuration>>. For example:
+
+* `issueType`: The type of the issue.
+* `priority`: The priority of the issue.
+* `parent`: The key of the parent issue (Valid when the issue type is `Sub-task`).
+
+For {ibm-r} connectors, refer to <<resilient-action-configuration>>. For example:
+
+* `issueTypes`: The type of the incident.
+* `severityCode`: The severity code of the incident.
+
+For {swimlane} connectors, refer to <<swimlane-action-configuration>>. For
+example:
+
+* `caseId`: The case ID.
+//TBD: Is this correct or should it be comments and severity?
+--
+
+`id`::
+(Required, string) The identifier for the connector. To create a case without a
+connector, use `none`.
+//To retrieve connector IDs, use <<cases-api-find-connectors>>).
+
+`name`::
+(Required, string) The name of the connector. To create a case without a
+connector, use `none`.
+
+`type`::
+(Required, string) The type of the connector. Valid values are: `.jira`, `.none`,
+`.resilient`,`.servicenow`, `.servicenow-sir`, and `.swimlane`. To create a case
+without a connector, use `.none`.
+====
+
+`description`::
+(Required, string) The description for the case.
+
+`owner`::
+(Required, string) The application that owns the case. Valid values are:
+`cases`, `observability`, or `securitySolution`. This value affects
+whether the case is visible in the {stack-manage-app}, {observability}, or
+{security-app}.
+
+`settings`::
+(Required, object)
+An object that contains the case settings.
++
+.Properties of `settings`
+[%collapsible%open]
+====
+`syncAlerts`:: 
+(Required, boolean) Turns alert syncing on or off.
+====
+
+`tags`::
+(Required, string array) The words and phrases that help
+categorize cases. It can be an empty array.
+
+`title`::
+(Required, string) A title for the case.
+
+=== Response code
+
+`200`::
+   Indicates a successful call.
+
+=== Example
+
+[source,sh]
+--------------------------------------------------
+POST api/cases
+{
+  "description": "James Bond clicked on a highly suspicious email
+  banner advertising cheap holidays for underpaid civil servants.",
+  "title": "This case will self-destruct in 5 seconds",
+  "tags": [
+    "phishing",
+    "social engineering"
+  ],
+  "connector": {
+    "id": "131d4448-abe0-4789-939d-8ef60680b498",
+    "name": "My connector",
+    "type": ".jira",
+    "fields": {
+      "issueType": "10006",
+      "priority": "High",
+      "parent": null
+    }
+  },
+  "settings": {
+    "syncAlerts": true
+  },
+  "owner": "securitySolution"
+}
+--------------------------------------------------
+// KIBANA
+
+The API returns a JSON object that includes the user who created the case and
+the case identifier, version, and creation time. The case ID is also its saved
+object ID (`savedObjectId`), which is used when pushing cases to external
+systems. For example:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "66b9aa00-94fa-11ea-9f74-e7e108796192",
+  "version": "WzUzMiwxXQ==",
+  "comments": [],
+  "totalComment": 0,
+  "totalAlerts": 0,
+  "title": "This case will self-destruct in 5 seconds",
+  "tags": [
+    "phishing",
+    "social engineering",
+    "bubblegum"
+  ],
+  "settings": {
+    "syncAlerts": true
+  },
+  "owner": "securitySolution",
+  "description": "James Bond clicked on a highly suspicious email banner advertising cheap holidays for underpaid civil servants. Operation bubblegum is active. Repeat - operation bubblegum is now active",
+  "closed_at": null,
+  "closed_by": null,
+  "created_at": "2022-05-13T09:16:17.416Z",
+  "created_by": {
+    "email": "[email protected]",
+    "full_name": "Alan Hunley",
+    "username": "ahunley"
+  },
+  "status": "open",
+  "updated_at": null,
+  "updated_by": null,
+  "connector": {
+    "id": "131d4448-abe0-4789-939d-8ef60680b498", <1>
+    "name": "My connector",
+    "type": ".jira",
+    "fields": {
+      "issueType": "10006",
+      "parent": null,
+      "priority": "High"
+    }
+  },
+  "external_service": null <2>
+}
+--------------------------------------------------
+
+<1> The default connector used to push cases to external services.
+<2> The `external_service` object stores information when the case is pushed to
+external systems.