---
title: "Create a scheduled task on an app"
method: POST
path: "/tasks"
tags: ["Platform"]
---

# Create a scheduled task on an app

`POST /tasks`

## Request

- Base URL: `https://api.imprezahost.com/v1`
- URL: `https://api.imprezahost.com/v1/tasks`
- Auth: API key in header `X-API-Key` and API key in header `X-API-Secret`

Two kinds.

`http` requests a **path on the app itself** — `/cron.php` for
Nextcloud, `/wp-cron.php` for WordPress — and treats 2xx/3xx as a
successful run. The request is made from inside the server, to the
app's own container address, so it works for an app with no public
hostname at all. `http_path` must be a path, not a URL: a task that
could name any host would make every customer's box a scheduled
request source.

`command` runs a single-line shell command in an image you name, on
the app's network. It grants nothing new — the same account can
already deploy any container — it just saves dressing a maintenance
job up as a deployment.

Nothing runs *inside* the app's own container. That needs a shell on
the host with docker, which would turn panel input into root on the
box; the permission model comes first.

`schedule` is a fixed set rather than a cron expression, because the
tick is the platform cron pass (about every five minutes) and
promising minute precision we cannot honour would be a lie in the
API.

## Request body

- object
  - `deployment_id` string, required
  - `name` string, required
  - `kind` 'http' | 'command'
  - `http_path` string
  - `http_method` 'GET' | 'POST'
  - `image` string
  - `command` string
  - `schedule` 'every_5m' | 'every_15m' | 'every_30m' | 'hourly' | 'daily' | 'weekly'
  - `at_hour` integer
  - `at_weekday` integer
  - `enabled` boolean
  - `keep_runs` integer

## Response `201`

Task created

## Other responses

- `400`: Invalid spec
- `404`: Resource not found
- `409`: This app already has the maximum number of tasks

---

[API](https://skmtc.dev/imprezahost/apis/impreza-host-public-api.md) · [All operations](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/imprezahost/apis/impreza-host-public-api/revisions/db86511f604f?raw)