> ## Documentation Index > Fetch the complete documentation index at: https://altostrat.io/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create a Job for a Site > Creates and queues a new job to be executed on the specified site. The job's payload is a raw RouterOS script, and metadata is provided via headers. ## OpenAPI ````yaml /api/en/mikrotik-api.yaml post /site/{siteId}/job openapi: 3.0.3 info: title: Altostrat MikroTik Devices API version: 1.0.0 description: >- The Altostrat MikroTik Devices API is the microservice responsible for managing the lifecycle, configuration, and real-time state of MikroTik devices within the SDX platform. It acts as the command and control plane for individual network endpoints, receiving heartbeats, dispatching jobs, and providing observability into device health. This service is the bridge between the Altostrat SDX automation layer and the physical network hardware. This API allows you to programmatically manage: - **Sites:** The digital twin of a physical MikroTik router, representing its identity, configuration, and current online status. - **Jobs:** Asynchronous commands or scripts sent to a Site for execution, enabling remote configuration changes, troubleshooting, and automation. - **Device Stats:** Time-series performance data, including CPU load, memory usage, and uptime, collected from each Site. Developers use this API to programmatically list, monitor, and interact with their fleet of MikroTik devices, forming the basis for building custom network automation and management tools. servers: - url: https://v1.api.altostrat.io description: Production API Server security: - BearerAuth: [] tags: - name: Sites description: Manage and monitor MikroTik devices, referred to as "Sites". - name: Jobs description: Create and manage asynchronous commands to be executed on Sites. - name: Device Stats description: Retrieve time-series performance metrics from Sites. - name: Runbooks description: Access device onboarding configurations. - name: Developer API description: >- Run synchronous RouterOS commands or queue asynchronous RouterOS scripts through SDX. - name: Developer Routers description: Read router-level summaries exposed by the SDX developer API. paths: /site/{siteId}/job: post: tags: - Jobs summary: Create a Job for a Site description: >- Creates and queues a new job to be executed on the specified site. The job's payload is a raw RouterOS script, and metadata is provided via headers. parameters: - name: siteId in: path required: true description: The UUID of the site to target. schema: type: string format: uuid - name: X-Idempotency-Key in: header required: true description: >- A unique UUID provided by the client to ensure that the request is processed only once. schema: type: string format: uuid - name: X-Description in: header required: true description: A human-readable description of the job's purpose. schema: type: string minLength: 3 maxLength: 100 - name: X-Needs-Ack in: header description: >- (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. schema: type: boolean - name: X-Backup in: header description: >- (Default: false) Set to `true` to automatically create a configuration backup of the site before executing this job. schema: type: boolean - name: X-Express-Execute in: header description: >- (Default: false) Set to `true` to attempt to trigger an immediate device check-in for faster job execution. schema: type: boolean requestBody: required: true description: The raw RouterOS script to be executed on the device. content: text/plain: schema: type: string example: /ip address add address=192.168.99.1/24 interface=ether2 responses: '201': description: The job was successfully created. content: application/json: schema: $ref: '#/components/schemas/Job' '400': $ref: '#/components/responses/BadRequest' '404': description: Not Found - The requested site does not exist. '500': $ref: '#/components/responses/ServerError' components: schemas: Job: type: object description: An asynchronous command or script to be executed on a Site. properties: id: type: string format: uuid description: The unique identifier (UUID) for the job. example: 8b8b2e5e-1a19-4a19-8b19-1e1919191919 token: type: string description: >- A short, unique, human-readable token for the job, often used in log filtering. example: 2jP5kLqWnZ site_id: type: string format: uuid description: The ID of the site this job is targeted for. example: 9a9a3e6f-1b1a-4b1a-8c1a-1e1a1a1a1a1a idempotency_key: type: string format: uuid description: >- A unique key provided by the client to prevent duplicate job creation. example: 7c7c1e4e-1918-4918-8a18-1e1818181818 description: type: string description: A human-readable description of the job's purpose. example: Add new firewall rule for guest network express_execute: type: boolean description: >- If `true`, the platform will attempt to trigger an immediate check-in from the device to execute this job sooner. example: false needs_acknowledgement: type: boolean description: >- If `true`, the job requires an explicit success/fail notification from the device to be marked as complete. example: true should_backup: type: boolean description: >- If `true`, a configuration backup was automatically created before this job was queued. example: true associated_backup: type: string nullable: true description: >- 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: type: string format: date-time nullable: true description: The timestamp when the device started executing the job. example: '2025-10-29T12:05:10Z' completed_at: type: string format: date-time nullable: true description: >- The timestamp when the device reported successful completion of the job. example: null failed_at: type: string format: date-time nullable: true description: >- The timestamp when the device reported a failure during job execution. example: null created_at: type: string format: date-time description: The timestamp when the job was created. example: '2025-10-29T12:00:00Z' log_url: type: string description: >- 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: type: string description: The raw RouterOS script payload of the job. example: >- /ip firewall filter add chain=forward action=accept src-address-list=guests ErrorResponse: type: object properties: type: type: string description: A broad category for the error (e.g., 'invalid_request_error'). example: invalid_request_error code: type: string description: A short, unique string identifying the specific error. example: parameter_invalid message: type: string description: A human-readable description of what went wrong. example: The 'lat' parameter must be between -90 and 90. doc_url: type: string description: >- A direct link to the documentation page for this specific error code. example: https://docs.altostrat.io/errors/parameter_invalid responses: BadRequest: description: >- Bad Request - The request was malformed or invalid. Check the response body for details. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ServerError: description: Internal Server Error - An unexpected error occurred on the server. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: api_error code: internal_server_error message: An internal server error occurred. Please try again later. doc_url: https://docs.altostrat.io/errors/api_error securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- Authenticate requests by providing a JSON Web Token (JWT) in the `Authorization` header. Example: `Authorization: Bearer ` ````