[DOCS] Add create case API

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]
@@ -26,3 +26,5 @@ these APIs:
 * {security-guide}/case-api-update-connector.html[Update case configurations]
 * {security-guide}/cases-api-update.html[Update case]
 * {security-guide}/cases-api-update-comment.html[Update comment]
+
+include::cases/cases-api-create.asciidoc[leveloffset=+1]

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

@@ -0,0 +1,213 @@
+[[cases-api-create]]
+== Create case API
+++++
+<titleabbrev>Create case</titleabbrev>
+++++
+
+Creates a case.
+
+=== Request
+
+`POST <kibana host>:<port>/api/cases`
+
+=== 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.
++
+--
+For {sn-itsm} connectors, refer to <<servicenow-action-configuration>>. For example:
+
+* `urgency` (string \| null): The extent to which the incident resolution can delay.
+* `severity` (string \| null): The severity of the incident.
+* `impact` (string \| null): The effect an incident had on business.
+* `category` (string \| null): The category of the incident.
+* `subcategory` (string \| null): 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` (string \| null): A comma separated list of destination IPs.
+* `malwareHash` (string \| null): A comma separated list of malware hashes.
+* `malwareUrl` (string \| null): A comma separated list of malware URLs.
+* `sourceIp` (string \| null): A comma separated list of source IPs.
+////
+* `priority` (string \| null): The priority of the incident.
+* `category` (string \| null): The category of the incident.
+* `subcategory` (string \| null): The subcategory of the incident.
+
+For {jira} connectors, refer to <<jira-action-configuration>>. For example:
+
+* `issueType` (string): The type of the issue.
+* `priority` (string \| null): The priority of the issue.
+* `parent` (string \| null): 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` (number[]): The type of the incident.
+* `severityCode` (number): The severity code of the incident.
+
+For {swimlane} connectors, refer to <<swimlane-action-configuration>>. For example:
+
+* `caseId` (string \| null): The case ID.
+//TBD: Is this correct or should it be comments and severity?
+--
+
+`id`::
+(Required, string) The identifier for the connector.
+//To retrieve connector IDs, use <<cases-api-find-connectors>>).
+
+`name`::
+(Required, string) The name of the connector.
+
+`type`::
+(Required, string) The type of the connector. Valid values are: `.jira`, `.none`,
+`.resilient`,`.servicenow`, `.servicenow-sir`, and `.swimlane`.
+====
+
+`description`::
+(Required, string) The case's description.
+
+`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",
+    }
+  },
+  "settings": {
+    "syncAlerts": true
+  },
+  "owner": "securitySolution"
+}
+--------------------------------------------------
+// KIBANA
+
+Creates a case with no connector:
+
+[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": "none",
+    "name": "none",
+    "type": ".none",
+    "fields": null
+  },
+  "settings": {
+    "syncAlerts": true
+  },
+  "owner": "securitySolution"
+}
+--------------------------------------------------
+// KIBANA
+
+The API returns an JSON object that includes the user who created the case and
+the case's ID, version, and creation time. The case's ID is also its saved
+object ID (`savedObjectId`), used when pushing cases to external systems. For
+example:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "66b9aa00-94fa-11ea-9f74-e7e108796192",
+  "version": "WzUzMiwxXQ==",
+  "comments": [],
+  "totalComment": 0,
+  "title": "This case will self-destruct in 5 seconds",
+  "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",
+  "tags": [
+    "phishing",
+    "social engineering",
+    "bubblegum"
+  ],
+  "closed_at": null,
+  "closed_by": null,
+  "created_at": "2020-05-13T09:16:17.416Z",
+  "created_by": {
+    "email": "[email protected]",
+    "full_name": "Alan Hunley",
+    "username": "ahunley"
+  },
+  "external_service": null, <1>
+  "status": "open",
+  "updated_at": null,
+  "updated_by": null,
+  "connector": {
+    "id": "131d4448-abe0-4789-939d-8ef60680b498", <2>
+    "name": "My connector",
+    "type": ".jira",
+    "fields": {
+      "issueType": "10006",
+      "priority": "High",
+    }
+  },
+  "settings": {
+    "syncAlerts": true
+  },
+  "owner": "securitySolution",
+}
+--------------------------------------------------
+
+<1> The `external_service` object stores information when the case is pushed to
+external systems.
+<2> The default connector used to push cases to external services.