Skip to main content
POST
/
sites
/
{siteId}
/
jobs
Create a Job for a Site
curl --request POST \
  --url https://api.altostrat.io/sites/{siteId}/jobs \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: text/plain' \
  --header 'X-Description: <x-description>' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '/ip address add address=192.168.99.1/24 interface=ether2'
{
  "id": "8b8b2e5e-1a19-4a19-8b19-1e1919191919",
  "token": "2jP5kLqWnZ",
  "site_id": "9a9a3e6f-1b1a-4b1a-8c1a-1e1a1a1a1a1a",
  "idempotency_key": "7c7c1e4e-1918-4918-8a18-1e1818181818",
  "description": "Add new firewall rule for guest network",
  "express_execute": false,
  "needs_acknowledgement": true,
  "should_backup": true,
  "associated_backup": "9a9a3e6f-1b1a-4b1a-8c1a-1e1a1a1a1a1a/1667888400.rsc",
  "started_at": "2025-10-29T12:05:10Z",
  "completed_at": null,
  "failed_at": null,
  "created_at": "2025-10-29T12:00:00Z",
  "log_url": "logs?group=sites&streams=9a9a...&start=...&end=...&filter={$.message=*2jP5kLqWnZ*}",
  "script": "/ip firewall filter add chain=forward action=accept src-address-list=guests"
}

Authorizations

โ€‹
Authorization
string
header
required

Authenticate requests by providing a JSON Web Token (JWT) in the Authorization header. Example: Authorization: Bearer <YOUR_JWT>

Headers

โ€‹
X-Idempotency-Key
string<uuid>
required

A unique UUID provided by the client to ensure that the request is processed only once.

โ€‹
X-Description
string
required

A human-readable description of the job's purpose.

Required string length: 3 - 100
โ€‹
X-Needs-Ack
boolean

(Default: true) Set to false if the job should be considered complete as soon as it's sent to the device, without waiting for a success/fail response.

โ€‹
X-Backup
boolean

(Default: false) Set to true to automatically create a configuration backup of the site before executing this job.

โ€‹
X-Express-Execute
boolean

(Default: false) Set to true to attempt to trigger an immediate device check-in for faster job execution.

Path Parameters

โ€‹
siteId
string<uuid>
required

The UUID of the site to target.

Body

text/plain ยท string

The raw RouterOS script to be executed on the device.

The body is of type string.

Example:

"/ip address add address=192.168.99.1/24 interface=ether2"

Response

The job was successfully created.

An asynchronous command or script to be executed on a Site.

โ€‹
id
string<uuid>

The unique identifier (UUID) for the job.

Example:

"8b8b2e5e-1a19-4a19-8b19-1e1919191919"

โ€‹
token
string

A short, unique, human-readable token for the job, often used in log filtering.

Example:

"2jP5kLqWnZ"

โ€‹
site_id
string<uuid>

The ID of the site this job is targeted for.

Example:

"9a9a3e6f-1b1a-4b1a-8c1a-1e1a1a1a1a1a"

โ€‹
idempotency_key
string<uuid>

A unique key provided by the client to prevent duplicate job creation.

Example:

"7c7c1e4e-1918-4918-8a18-1e1818181818"

โ€‹
description
string

A human-readable description of the job's purpose.

Example:

"Add new firewall rule for guest network"

โ€‹
express_execute
boolean

If true, the platform will attempt to trigger an immediate check-in from the device to execute this job sooner.

Example:

false

โ€‹
needs_acknowledgement
boolean

If true, the job requires an explicit success/fail notification from the device to be marked as complete.

Example:

true

โ€‹
should_backup
boolean

If true, a configuration backup was automatically created before this job was queued.

Example:

true

โ€‹
associated_backup
string | null

The path to the configuration backup file associated with this job, if one was created.

Example:

"9a9a3e6f-1b1a-4b1a-8c1a-1e1a1a1a1a1a/1667888400.rsc"

โ€‹
started_at
string<date-time> | null

The timestamp when the device started executing the job.

Example:

"2025-10-29T12:05:10Z"

โ€‹
completed_at
string<date-time> | null

The timestamp when the device reported successful completion of the job.

Example:

null

โ€‹
failed_at
string<date-time> | null

The timestamp when the device reported a failure during job execution.

Example:

null

โ€‹
created_at
string<date-time>

The timestamp when the job was created.

Example:

"2025-10-29T12:00:00Z"

โ€‹
log_url
string

A relative URL to the Altostrat SDX UI to view logs related to this job's execution.

Example:

"logs?group=sites&streams=9a9a...&start=...&end=...&filter={$.message=*2jP5kLqWnZ*}"

โ€‹
script
string

The raw RouterOS script payload of the job.

Example:

"/ip firewall filter add chain=forward action=accept src-address-list=guests"