Merge branch 'docs-pipelines-trigger-api' into 'master'

Update pipeline triggers API endpoint

See merge request gitlab-org/gitlab!84030

doc/api/pipeline_triggers.md

@@ -4,13 +4,13 @@ group: Pipeline Execution
 info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
 ---
-# Pipeline triggers API **(FREE)**
+# Pipeline trigger tokens API **(FREE)**
 You can read more about [triggering pipelines through the API](../ci/triggers/index.md).
-## List project triggers
-Get a list of project's build triggers.
+## List project trigger tokens
+Get a list of a project's pipeline trigger tokens.
 ```plaintext
 GET /projects/:id/triggers
@@ -41,9 +41,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
 The trigger token is displayed in full if the trigger token was created by the authenticated
 user. Trigger tokens created by other users are shortened to four characters.
-## Get trigger details
-Get details of project's build trigger.
+## Get trigger token details
+Get details of a project's pipeline trigger.
 ```plaintext
 GET /projects/:id/triggers/:trigger_id
@@ -70,9 +70,9 @@ curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/a
 }
 ```
-## Create a project trigger
-Create a trigger for a project.
+## Create a trigger token
+Create a pipeline trigger for a project.
 ```plaintext
 POST /projects/:id/triggers
@@ -100,9 +100,9 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
 }
 ```
-## Update a project trigger
-Update a trigger for a project.
+## Update a project trigger token
+Update a pipeline trigger token for a project.
 ```plaintext
 PUT /projects/:id/triggers/:trigger_id
@@ -131,9 +131,9 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" \
 }
 ```
-## Remove a project trigger
-Remove a project's build trigger.
+## Remove a project trigger token
+Remove a project's pipeline trigger token.
 ```plaintext
 DELETE /projects/:id/triggers/:trigger_id
@@ -147,3 +147,78 @@ DELETE /projects/:id/triggers/:trigger_id
 ```shell
 curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/triggers/5"
 ```
+
+## Trigger a pipeline with a token
+
+Trigger a pipeline by using a pipeline [trigger token](../ci/triggers/index.md#create-a-trigger-token)
+or a [CI/CD job token](../ci/jobs/ci_job_token.md) for authentication.
+
+With a CI/CD job token, the [triggered pipeline is a multi-project pipeline](../ci/jobs/ci_job_token.md#trigger-a-multi-project-pipeline-by-using-a-cicd-job-token).
+The job that authenticates the request becomes associated with the upstream pipeline,
+which is visible on the [pipeline graph](../ci/pipelines/multi_project_pipelines.md#multi-project-pipeline-visualization).
+
+If you use a trigger token in a job, the job is not associated with the upstream pipeline.
+
+```plaintext
+POST /projects/:id/trigger/pipeline
+```
+
+Supported attributes:
+
+| Attribute   | Type           | Required               | Description |
+|:------------|:---------------|:-----------------------|:---------------------|
+| `id`        | integer/string | **{check-circle}** Yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user. |
+| `ref`       | string         | **{check-circle}** Yes | The branch or tag to run the pipeline on. |
+| `token`     | string         | **{check-circle}** Yes | The trigger token or CI/CD job token. |
+| `variables` | array          | **{dotted-circle}** No | An array containing the variables available in the pipeline, matching the structure `[{ 'key': 'UPLOAD_TO_S3', 'variable_type': 'file', 'value': 'true' }, {'key': 'TEST', 'value': 'test variable'}]`. If `variable_type` is excluded, it defaults to `env_var`. |
+
+Example request:
+
+```shell
+curl --request POST "https://gitlab.example.com/api/v4/projects/123/trigger/pipeline?token=2cb1840fb9dfc9fb0b7b1609cd29cb&ref=main"
+```
+
+Example response:
+
+```json
+{
+  "id": 257,
+  "iid": 118,
+  "project_id": 21,
+  "sha": "91e2711a93e5d9e8dddfeb6d003b636b25bf6fc9",
+  "ref": "main",
+  "status": "created",
+  "source": "trigger",
+  "created_at": "2022-03-31T01:12:49.068Z",
+  "updated_at": "2022-03-31T01:12:49.068Z",
+  "web_url": "http://127.0.0.1:3000/test-group/test-project/-/pipelines/257",
+  "before_sha": "0000000000000000000000000000000000000000",
+  "tag": false,
+  "yaml_errors": null,
+  "user": {
+    "id": 1,
+    "username": "root",
+    "name": "Administrator",
+    "state": "active",
+    "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+    "web_url": "http://127.0.0.1:3000/root"
+  },
+  "started_at": null,
+  "finished_at": null,
+  "committed_at": null,
+  "duration": null,
+  "queued_duration": null,
+  "coverage": null,
+  "detailed_status": {
+    "icon": "status_created",
+    "text": "created",
+    "label": "created",
+    "group": "created",
+    "tooltip": "created",
+    "has_details": true,
+    "details_path": "/test-group/test-project/-/pipelines/257",
+    "illustration": null,
+    "favicon": "/assets/ci_favicons/favicon_status_created-4b975aa976d24e5a3ea7cd9a5713e6ce2cd9afd08b910415e96675de35f64955.png"
+  }
+}
+```

doc/ci/jobs/ci_job_token.md

@@ -104,13 +104,12 @@ The job token scope is only for controlling access to private projects.
 There is [a proposal](https://gitlab.com/groups/gitlab-org/-/epics/3559) to improve
 the feature with more strategic control of the access permissions.
-## Trigger a multi-project pipeline by using a CI job token
+## Trigger a multi-project pipeline by using a CI/CD job token
 > `CI_JOB_TOKEN` for multi-project pipelines was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/31573) from GitLab Premium to GitLab Free in 12.4.
-You can use the `CI_JOB_TOKEN` to trigger [multi-project pipelines](../pipelines/multi_project_pipelines.md)
-from a CI/CD job. A pipeline triggered this way creates a dependent pipeline relation
-that is visible on the [pipeline graph](../pipelines/multi_project_pipelines.md#multi-project-pipeline-visualization).
+You can use the `CI_JOB_TOKEN` to [trigger multi-project pipelines](../../api/pipeline_triggers.md#trigger-a-pipeline-with-a-token)
+from a CI/CD job.
 For example: