Merge pull request #33430 from backstage/freben/sched-cancel-doc

add docs for the scheduler cancel endpoint
2026-03-19 09:45:53 +01:00
parent 1844a62209 13be681f39
commit 5ea9806f17
1 changed files with 33 additions and 0 deletions
@@ -156,6 +156,39 @@ Responds with
 - `404 Not Found` if there was no such registered task for this plugin
 - `409 Conflict` if the task was already in a running state

+### `POST <pluginBaseURL>/.backstage/scheduler/v1/tasks/<taskId>/cancel`
+
+Cancels the running task with the given task ID.
+
+Note that `<taskId>` must be URL-encoded so that it remains a single path segment
+in the URL (for example by using `encodeURIComponent` in JavaScript or standard
+percent-encoding).
+
+For example, to cancel a specific Catalog task:
+
+```bash
+curl -X POST "https://<instance-name>/api/catalog/.backstage/scheduler/v1/tasks/InternalOpenApiDocumentationProvider%3Arefresh/cancel"
+```
+
+A working example would be:
+
+```bash
+curl -X POST "https://demo.backstage.io/api/catalog/.backstage/scheduler/v1/tasks/InternalOpenApiDocumentationProvider%3Arefresh/cancel"
+```
+
+Note that there can still be an additional small delay before a worker discovers
+that the task is cancelled. This can take up to a few seconds. Note also that it
+is up to the task implementation to properly react to the abort signal that was
+passed into it.
+
+The request has no body.
+
+Responds with
+
+- `200 OK` if successful
+- `404 Not Found` if there was no such registered task for this plugin
+- `409 Conflict` if the task was not in a running state
+
 ## Testing

 The `@backstage/backend-test-utils` package provides `mockServices.scheduler`, which provides a mocked implementation of the scheduler service that can be used in tests. This mocked implementation is used by default in `startTestBackend`, and it will immediately run any registered tasks on startup as long as they're not configured to run manually or with an initial delay.