NetBird Full API Reference + Read-Only MCP Prototype
POST/api/peers/{peerId}/jobs

Create a job for a peer

Creates a new job for a specific peer using the supplied workload. Provide workload with its required type and parameters to define the work to run. A 201 response returns the created job and its initial status.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

1 parameter · 1 body field
peerIdstringrequired
The unique identifier of the peer for which you want to create a job.

Job creation request containing the workload to run.

workloadobjectrequired
The work to run; include the required `type` and `parameters` values.

5 status codes
201Returns the created job object, including its identifier, creation time, status, triggering user, and workload.
completed_atstringoptional
created_atstringrequired
failed_reasonstringoptional
idstringrequired
statusstringrequired
Allowed:pendingsucceededfailed
triggered_bystringrequired
workloadobjectrequired
400Returned when the request is invalid.
401Returned when the request does not include valid authentication.
403Returned when access to create a job for the peer is forbidden.
500Returned when the server encounters an internal error.

Error handling

A 400 is returned when the request is invalid, a 401 when authentication is missing or invalid, a 403 when access is denied, and a 500 when the server encounters an internal error. The peerId path parameter must identify the peer for the job. The request body must include workload, with both type and parameters.