[Synthetics] Global params Public APIs

docs/api/synthetics/params/add-param.asciidoc

@@ -0,0 +1,123 @@
+[[add-parameters-api]]
+== Add Parameters API
+++++
+<titleabbrev>Add Parameters</titleabbrev>
+++++
+
+Adds one or more parameters to the synthetics app.
+
+=== {api-request-title}
+
+`POST <kibana host>:<port>/api/synthetics/params`
+
+`POST <kibana host>:<port>/s/<space_id>/api/synthetics/params`
+
+=== {api-prereq-title}
+
+You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+
+[[parameters-add-request-body]]
+==== Request body
+
+The request body can contain either a single parameter object or an array of parameter objects. The parameter object schema includes the following attributes:
+
+`key`::
+(Required, string) The key of the parameter.
+
+`value`::
+(Required, string) The value associated with the parameter.
+
+`description`::
+(Optional, string) A description of the parameter.
+
+`tags`::
+(Optional, array of strings) An array of tags to categorize the parameter.
+
+`share_across_spaces`::
+(Optional, boolean) Whether the parameter should be shared across spaces.
+
+When adding a single parameter, provide a single object. When adding multiple parameters, provide an array of parameter objects.
+
+[[parameters-add-example]]
+==== Example
+
+Here are examples of POST requests to add parameters, either as a single parameter or as an array of parameters:
+
+To add a single parameter:
+
+[source,json]
+--------------------------------------------------
+{
+  "key": "api_key",
+  "value": "your-api-key-value",
+  "description": "API Key for authentication",
+  "tags": ["authentication", "security"],
+  "share_across_spaces": true
+}
+--------------------------------------------------
+
+To add multiple parameters:
+
+[source,json]
+--------------------------------------------------
+[
+  {
+    "key": "param1",
+    "value": "value1"
+  },
+  {
+    "key": "param2",
+    "value": "value2"
+  }
+]
+--------------------------------------------------
+
+The API returns a response based on the request. If you added a single parameter, it will return a single parameter object. If you added multiple parameters, it will return an array of parameter objects.
+
+[[parameters-add-response-example]]
+==== Response Example
+
+The API response includes the created parameter(s) as JSON objects, where each parameter object has the following attributes:
+
+- `id` (string): The unique identifier of the parameter.
+- `key` (string): The key of the parameter.
+- `value` (string): The value associated with the parameter.
+- `description` (string, optional): The description of the parameter.
+- `tags` (array of strings, optional): An array of tags associated with the parameter.
+- `share_across_spaces` (boolean, optional): Indicates whether the parameter is shared across spaces.
+
+Here's an example response for a single added parameter:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "unique-parameter-id",
+  "key": "api_key",
+  "value": "your-api-key-value",
+  "description": "API Key for authentication",
+  "tags": ["authentication", "security"],
+  "share_across_spaces": true
+}
+--------------------------------------------------
+
+And here's an example response for adding multiple parameters:
+
+[source,json]
+--------------------------------------------------
+[
+  {
+    "id": "param1-id",
+    "key": "param1",
+    "value": "value1"
+  },
+  {
+    "id": "param2-id",
+    "key": "param2",
+    "value": "value2"
+  }
+]
+--------------------------------------------------
+
+This updated documentation provides information for adding parameters, whether as a single parameter or an array of parameters, and includes examples of the API request and response. You can replace `<your-api-host>` with the actual host where your API is available.

docs/api/synthetics/params/delete-param.asciidoc

@@ -0,0 +1,54 @@
+[[delete-parameters-api]]
+== Delete Parameters API
+++++
+<titleabbrev>Delete Parameters</titleabbrev>
+++++
+
+Deletes one or more parameters from the Synthetics app.
+
+=== {api-request-title}
+
+`DELETE <kibana host>:<port>/api/synthetics/params`
+
+`DELETE <kibana host>:<port>/s/<space_id>/api/synthetics/params`
+
+=== {api-prereq-title}
+
+You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+To use this API, you must have appropriate permissions for deleting parameters.
+
+[[parameters-delete-request-body]]
+==== Request Body
+
+The request body should contain an array of parameter IDs that you want to delete.
+
+`ids`::
+(Required, array of strings) An array of parameter IDs to delete.
+
+[[parameters-delete-response-example]]
+==== Response Example
+
+The API response includes information about the deleted parameters, where each entry in the response array contains the following attributes:
+
+- `id` (string): The unique identifier of the deleted parameter.
+- `deleted` (boolean): Indicates whether the parameter was successfully deleted (`true` if deleted, `false` if not).
+
+Here's an example response for deleting multiple parameters:
+
+[source,json]
+--------------------------------------------------
+[
+  {
+    "id": "param1-id",
+    "deleted": true
+  },
+  {
+    "id": "param2-id",
+    "deleted": true
+  }
+]
+--------------------------------------------------
+
+This API allows you to delete one or more parameters by specifying their IDs in the request body. The response array provides information about the success of the deletion process for each parameter. You can replace `<your-api-host>` with the actual host where your API is available.

docs/api/synthetics/params/edit-param.asciidoc

@@ -0,0 +1,70 @@
+[[edit-parameter-by-id-api]]
+== Edit Parameter by ID API
+++++
+<titleabbrev>Edit Parameter</titleabbrev>
+++++
+
+Edits a parameter with the specified ID.
+
+=== {api-request-title}
+
+`PUT <kibana host>:<port>/api/synthetics/params`
+
+`PUT <kibana host>:<port>/s/<space_id>/api/synthetics/params`
+
+=== {api-prereq-title}
+
+You must have `all` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+[[parameter-edit-path-params]]
+==== Path Parameters
+
+`paramId`::
+(Required, string) The unique identifier of the parameter to be edited.
+
+[[parameter-edit-request-body]]
+==== Request body
+
+The request body should contain the following attributes:
+
+`key`::
+(Optional, string) The key of the parameter.
+
+`value`::
+(Optional, string) The updated value associated with the parameter.
+
+`description`::
+(Optional, string) The updated description of the parameter.
+
+`tags`::
+(Optional, array of strings) An array of updated tags to categorize the parameter.
+
+[[parameter-edit-example]]
+==== Example
+
+Here is an example of a PUT request to edit a parameter by its ID:
+
+[source,sh]
+--------------------------------------------------
+PUT /api/synthetics/parameters/param_id1
+{
+  "key": "updated_api_key",
+  "value": "updated-api-key-value",
+  "description": "Updated API Key for authentication",
+  "tags": ["authentication", "security", "updated"]
+}
+--------------------------------------------------
+
+The API returns the updated parameter as follows:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "param_id1",
+  "key": "updated_api_key",
+  "value": "updated-api-key-value",
+  "description": "Updated API Key for authentication",
+  "tags": ["authentication", "security", "updated"]
+}
+--------------------------------------------------

docs/api/synthetics/params/get-params.asciidoc

@@ -0,0 +1,121 @@
+[[get-parameters-api]]
+== Get Parameters API
+++++
+<titleabbrev>Get Parameters</titleabbrev>
+++++
+
+Retrieves parameters based on the provided criteria.
+
+=== {api-request-title}
+
+`GET <kibana host>:<port>/api/synthetics/params/{id?}`
+
+`GET <kibana host>:<port>/s/<space_id>/api/synthetics/params/{id?}`
+
+=== {api-prereq-title}
+
+You must have `read` privileges for the *Synthetics* feature in the *{observability}* section of the
+<<kibana-feature-privileges,{kib} feature privileges>>.
+
+[[parameters-get-query-params]]
+==== Query Parameters
+
+`id`::
+(Optional, string) The unique identifier of the parameter. If provided, this API will retrieve a specific parameter by its ID. If not provided, it will retrieve a list of all parameters.
+
+[[parameters-get-response-example]]
+==== Response Example
+
+The API response includes parameter(s) as JSON objects, where each parameter object has the following attributes:
+
+- `id` (string): The unique identifier of the parameter.
+- `key` (string): The key of the parameter.
+
+If the user has read-only permissions to the Synthetics app, the following additional attributes will be included:
+
+- `description` (string, optional): The description of the parameter.
+- `tags` (array of strings, optional): An array of tags associated with the parameter.
+- `namespaces` (array of strings): Namespaces associated with the parameter.
+
+If the user has write permissions, the following additional attribute will be included:
+
+- `value` (string): The value associated with the parameter.
+
+Here's an example response for retrieving a single parameter by its ID:
+
+For users with read-only permissions:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "unique-parameter-id",
+  "key": "api_key",
+  "description": "API Key for authentication",
+  "tags": ["authentication", "security"],
+  "namespaces": ["namespace1", "namespace2"]
+}
+--------------------------------------------------
+
+For users with write permissions:
+
+[source,json]
+--------------------------------------------------
+{
+  "id": "unique-parameter-id",
+  "key": "api_key",
+  "description": "API Key for authentication",
+  "tags": ["authentication", "security"],
+  "namespaces": ["namespace1", "namespace2"],
+  "value": "your-api-key-value"
+}
+--------------------------------------------------
+
+And here's an example response for retrieving a list of parameters:
+
+For users with read-only permissions:
+
+[source,json]
+--------------------------------------------------
+[
+  {
+    "id": "param1-id",
+    "key": "param1",
+    "description": "Description for param1",
+    "tags": ["tag1", "tag2"],
+    "namespaces": ["namespace1"]
+  },
+  {
+    "id": "param2-id",
+    "key": "param2",
+    "description": "Description for param2",
+    "tags": ["tag3"],
+    "namespaces": ["namespace2"]
+  }
+]
+--------------------------------------------------
+
+For users with write permissions:
+
+[source,json]
+--------------------------------------------------
+[
+  {
+    "id": "param1-id",
+    "key": "param1",
+    "description": "Description for param1",
+    "tags": ["tag1", "tag2"],
+    "namespaces": ["namespace1"],
+    "value": "value1"
+  },
+  {
+    "id": "param2-id",
+    "key": "param2",
+    "description": "Description for param2",
+    "tags": ["tag3"],
+    "namespaces": ["namespace2"],
+    "value": "value2"
+  }
+]
+--------------------------------------------------
+
+This API allows you to retrieve parameters either by specifying a specific `id` or without an `id` to get a list of parameters. The attributes included in the response depend on the user's permissions.

docs/api/synthetics/synthetics-api.asciidoc

@@ -0,0 +1,18 @@
+[[synthetics-apis]]
+== Synthetics APIs
+
+The following APIs are available for Synthetics.
+
+* <<get-parameters-api, Get Parameters API>> to get a parameter(s).
+
+* <<add-parameters-api, Create Parameter API>> to create a parameter.
+
+* <<edit-parameter-by-id-api, Edit Parameter API>> to edit a parameter.
+
+* <<delete-parameters-api, Delete Parameter API>> to delete a parameter.
+
+
+include::params/add-param.asciidoc[leveloffset=+1]
+include::params/get-params.asciidoc[leveloffset=+1]
+include::params/edit-param.asciidoc[leveloffset=+1]
+include::params/delete-param.asciidoc[leveloffset=+1]

docs/user/api.asciidoc

@@ -109,4 +109,5 @@ include::{kib-repo-dir}/api/osquery-manager.asciidoc[]
 include::{kib-repo-dir}/api/short-urls.asciidoc[]
 include::{kib-repo-dir}/api/task-manager/health.asciidoc[]
 include::{kib-repo-dir}/api/upgrade-assistant.asciidoc[]
+include::{kib-repo-dir}/api/synthetics/synthetics-api.asciidoc[]
 include::{kib-repo-dir}/api/uptime-api.asciidoc[]