Skip to main content
POST
/
site
/
{site}
/
job
Create Site Job
curl --request POST \
  --url https://{appDomain}/site/{site}/job \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: text/plain' \
  --header 'X-Idempotency-Key: <x-idempotency-key>' \
  --data '/ip firewall filter add action=accept chain=input comment="Allow Winbox" disabled=no dst-port=8291 protocol=tcp
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "token": "jobTokenExample",
  "site_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "idempotency_key": "some-idempotency-key-uuid-or-id",
  "description": "<string>",
  "express_execute": true,
  "needs_acknowledgement": true,
  "should_backup": true,
  "associated_backup": "site-uuid-here/1678886400.rsc",
  "started_at": "2023-11-07T05:31:56Z",
  "completed_at": "2023-11-07T05:31:56Z",
  "failed_at": "2023-11-07T05:31:56Z",
  "created_at": "2023-11-07T05:31:56Z",
  "log_url": "logs?group=sites&streams=site-uuid&start=2023-01-01T00:00:00&end=2023-01-01T00:30:00&filter={$.message=*jobTokenExample*}&limit=10",
  "script": "<string>"
}

Authorizations

​
Authorization
string
header
required

Standard JWT token obtained via a separate authentication process. Required for most user-facing API endpoints.

Headers

​
X-Idempotency-Key
string<uuid>
required

A UUID to ensure the request is processed only once.

​
X-Description
string

A brief description of the job. Defaults if not provided.

Required string length: 3 - 100
​
X-Needs-Ack
boolean
default:true

Whether the job requires explicit 'done' status from the device (true) or is completed upon download (false).

​
X-Backup
boolean
default:false

Whether to create an SFTP backup before running the script.

​
X-Express-Execute
boolean
default:false

Whether to attempt to trigger an immediate poll from the device after job creation.

Path Parameters

​
site
string<uuid>
required

The UUID of the Site to create the job for.

Body

text/plain · string

The RouterOS script payload to be executed.

The body is of type string.

Required string length: 3 - 10000
Example:

"/ip firewall filter add action=accept chain=input comment=\"Allow Winbox\" disabled=no dst-port=8291 protocol=tcp\n"

Response

Job created successfully. Returns the created job resource.

​
id
string<uuid>
​
token
string

Base62 encoded job UUID, used in log messages/urls.

Example:

"jobTokenExample"

​
site_id
string<uuid>
​
idempotency_key
string
Example:

"some-idempotency-key-uuid-or-id"

​
description
string
​
express_execute
boolean
​
needs_acknowledgement
boolean
​
should_backup
boolean
​
associated_backup
string | null
Example:

"site-uuid-here/1678886400.rsc"

​
started_at
string<date-time> | null
​
completed_at
string<date-time> | null
​
failed_at
string<date-time> | null
​
created_at
string<date-time> | null
​
log_url
string<uri>

Relative URL to view logs related to this job in the UI.

Example:

"logs?group=sites&streams=site-uuid&start=2023-01-01T00:00:00&end=2023-01-01T00:30:00&filter={$.message=*jobTokenExample*}&limit=10"

​
script
string

The actual script payload associated with the job. Included in GET specific job details.

⌘I