---
title: "Execute a task against a resource"
method: POST
path: "/tasks"
tags: ["tasks"]
---

# Execute a task against a resource

`POST /tasks`

This API will create a task that may be long running and may execute against a resource.  If the task is long running a 200 code is returned otherwise a 201 code with be returned. The task can be fetched throughout its lifecycle and used to track the progress and completion of the task.<br><br>The following tasks can be executed against an application resource and do not return a result:<br><ul><li>Initiate validation for an application.  The validate task will verify each of the application's unverified challenges.</li><li>Start a stopped application.</li><li>Stop a running application.</li><li>Enter an application into maintenance mode.<br><b>parameters</b>:<pre>{"maximum_duration": integer}</pre></li><li>Exit an application from maintenance mode.</li><li>Check a hostname for availability.<br><b>parameters</b>:<pre>{"hostname": string}</pre><b>result</b>:<pre>{"available": boolean}</pre></li></ul>

## Request body

- union — Configuration for a task to be created
  - TaskEnterMaintenance — Starts application maintenance
    - `type` 'enter_maintenance', required
    - `target` union, required — Reference to the application for which maintenance is to be started
      - ResourceReference
        - `href` string, required — The endpoint for the resource.
      - string — An application href
    - `parameters` object — Optional parameters
      - `maximum_duration` integer
  - TaskExitMaintenance — Exits application from maintenance
    - `type` 'exit_maintenance', required
    - `target` union, required — Reference to the application for which maintenance is to be stopped
      - ResourceReference
        - `href` string, required — The endpoint for the resource.
      - string — A resource reference
    - `parameters` object
  - TaskGenerateOriginCertificate — Generate certificate for application servers
    - `type` 'generate-origin-certificate', required
    - `target` string, required — The endpoint for the application resource.
    - `parameters` object, required — Required parameters
      - `key` string, required — A PEM encoded RSA key
      - `hostnames` string[] — A list of hostnames those needs to be included in the certificate
      - `expiry` string — An iso8601 formatted timestamp
  - TaskInvalidateCache — Invalidate Cache for given application
    - `type` 'invalidate-cache', required
    - `target` union, required — Endpoint for the target of the task. Only required for tasks targeting resources.
      - ResourceReference
        - `href` string, required — The endpoint for the resource.
      - string — A resource reference
    - `parameters` object, required — Additional parameters specific to the task type.
      - `urls` InvalidateCacheUrl[], required — A list of URLs to be invalidated
      - `tags` TagName[] — A list of tags to be invalidated
  - TaskOauth2Authorize — Complete an Oauth2 authorization
    - `type` 'oauth2-authorize', required
    - `parameters` object, required — Required parameters
      - `code` string
      - `realm_id` string
  - TaskRunAction — Runs the target application
    - `type` 'run-action', required
    - `target` union, required — A reference to an application for which the action is run
      - ResourceReference
        - `href` string, required — The endpoint for the resource.
      - string — A resource reference
    - `parameters` object, required — Required parameters
      - `id` string — The identifier of the action to run
  - TaskStart — Starts a target application
    - `type` 'start', required
    - `target` union, required — A reference to the application to start
      - ResourceReference
        - `href` string, required — The endpoint for the resource.
      - string — A resource reference
  - TaskStop — Stops a target application
    - `type` 'stop', required
    - `target` union, required — A reference to the application to stop
      - ResourceReference
        - `href` string, required — The endpoint for the resource.
      - string — A resource reference
  - TaskValidateTLS — Validates TLS for target application
    - `type` 'validate_tls', required
    - `parameters` object, required — Required parameters
      - `tls_configuration` object
  - SearchParameters — Parameter object for the search task
    - `type` 'search'
    - `parameters` object — Required parameters
      - `pattern` string, required — A wildcard pattern to search for
      - `limit` integer — The maximum number of results to be returned. If omitted, then all results are returned
  - PrepareForDownload — Create Prepare archives for download task
    - `type` 'prepare-for-download'
    - `parameters` object — Required parameters
      - `reference` string, required — The archived-logs reference.
      - `from` string, required — An iso8601 formatted timestamp
      - `to` string, required — An iso8601 formatted timestamp
      - `retention` integer — The number of days the retrieved logs will be available for download.
      - `restore_type` 'bulk' | 'standard' | 'expedited' — The Method used to retrieve files from long term storage.

## Response `200`

The task has been created and is complete.

- Task
  - `href` string — A reference to the task
  - `type` string — The type of task
  - `target` string — An object on which a referencing task operates
  - `parameters` object — The parameters used as input to a task
  - `created` string, date-time — Time that the task was created.
  - `started` string, date-time — Time that the task was started. This field will be null if the task has not started.
  - `completed` string, date-time — Time at which processing for a task completed, or null if not yet completed.
  - `updated` string, date-time — Time at which the task was last updated.
  - `state` 'pending' | 'running' | 'success' | 'failed' — The current state of the task. success and failed are final states.
  - `description` string — A description of the task
  - `message` string — This field may contain a message regarding the current state of the task or it may be null.
  - `result` union — The result of a task. Type is an object dependent on the task. Will not be set for tasks that do not compute results.
    - object
    - SearchResult — Results of a search task
      - `matches` object[]
        - `account` Account
          - `billing_service` union
            - unknown
            - object
              - …
          - `stratus_id` string, nullable — Identification for stratus accounts
          - `name` string — The name associated with an account.
          - `log_retention` AccountLogRetention[] — An array of account log retention configuration.
            - `type` 'events', required — Type of log retention
            - `online_days` integer — Number of online days
            - `archive_days` integer — Number of archive days
            - `online_space_allowance` integer — Allowance for online space
            - `archive_space_allowance` integer — Allowance for archive space
          - `href` string, required — A reference to an account
          - `id` string, required — Deprecated. A unique identifier for the account.
        - `subject` object — A matched object containing at a minimum an "href" attribute and any attributes that were searched

## Other responses

- `201` — The task has been created and has not yet completed.

---

[API](https://skmtc.dev/webscale/apis/webscale-apis.md) · [All operations](https://skmtc.dev/webscale/apis/webscale-apis/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/webscale/webscale-apis/revisions/c98d872b50cb/schema)