Patch Server API

Note

To retrieve the JSON of a patch definition on the server, refer to the Jamf Pro Patch API documentation.

Endpoints

Resource Operation Description
Backup GET /api/v1/backup Downloadable archive of all software titles.
Software Title POST /api/v1/title Create a patch definition.
  POST /api/v1/title/(name_id)/version Create a patch version.
  DELETE /api/v1/title/(name_id) Delete a patch definition.
Token POST /api/v1/token Create the API token.
Webhooks DELETE /api/v1/webhooks/(webhook_id) Delete a webhook.

Reference

GET /api/v1/backup

Download a zipped archive of all patch definitions.

Example Request:

GET /api/v1/backup HTTP/1.1

Example Response:

A successful response will return a 200 status and a zipped archive containing the patch definitions.

HTTP/1.1 200 OK
Content-Type: application/zip

<patch_archive.zip>
POST /api/v1/token

Create an API token for the server.

Example Request:

POST /api/v1/token HTTP/1.1

Example Response:

A successful response will return a 201 status with the API token.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "token_created": "94631ec5c65e4dd19fb81479abdd2929"
}

Error Responses

A 403 status is returned if an API token already exists.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
    "forbidden": "A token already exists for this server"
}
Return:
POST /api/v1/title

Create a new patch definition on the server.

Example Request:

POST /api/v1/title HTTP/1.1
Content-Type: application/json

{
    "id": "Composer",
    "name": "Composer",
    "publisher": "Jamf",
    "appName": "Composer.app",
    "bundleId": "com.jamfsoftware.Composer",
    "requirements": ["requirementObjects"],
    "patches": ["versionObjects"],
    "extensionAttributes": ["extensionAttributeObjects"]
}

Note

The JSON schema for a patch definition can be found in the project repository at: patchserver/routes/validator/schema_full_definition.json

Example Response:

A successful response will return a 201 status with the numerical database ID as well as the definition’s ID.

HTTP/1.1 201 Created
Content-Type: application/json

{
    "database_id": 1,
    "id": "Composer"
}

Error Responses

A 409 status is returned if you attempt to create a patch definition using an ID that already exists in the database.

HTTP/1.1 409 Conflict
Content-Type: application/json

{
    "database_conflict": "A software title of the provided name already exists."
}

A 400 status can be returned if your patch definition fails a validation check against the JSON schema. If this occurs, a reason will be provided in the JSON response.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "invalid_json": "Validation error encountered with submitted JSON for item: /u'true' is not of type u'boolean'"
}

A 400 status can be returned if your patch definition fails a validation check against the JSON schema. If this occurs, a reason will be provided in the JSON response.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "invalid_json": "Validation error encountered with submitted JSON: u'true' is not of type u'boolean' for item: /patches/0/components/0/criteria/0/and"
}
POST /api/v1/title/(name_id)/version

Create a new patch version for an existing patch definition.

Example Request:

POST /api/v1/title/Composer/version HTTP/1.1
Content-Type: application/json

    {
        "version": "10.1.1",
        "releaseDate": "2017-12-20T10:08:38.270Z",
        "standalone": true,
        "minimumOperatingSystem": "10.9",
        "reboot": false,
        "killApps": [
            {
                "bundleId": "com.jamfsoftware.Composer",
                "appName": "Composer.app"
            }
        ],
        "components": [
            {
                "name": "Composer",
                "version": "10.1.1",
                "criteria": ["requirementsObjects"]
            }
        ],
        "capabilities": ["requirementsObjects"],
        "dependencies": []
    }

Note

The JSON schema for a patch definition can be found in the project repository at: patchserver/routes/validator/schema_version.json

Example Response:

A successful response will return a 201 status.

HTTP/1.1 201 Created
Content-Type: application/json

{}

Error Responses

A 400 status can be returned if your patch version fails a validation check against the JSON schema. If this occurs, a reason will be provided in the JSON response.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "invalid_json": "Validation error encountered with submitted JSON: u'true' is not of type u'boolean' for item: /patches/0/components/0/criteria/0/and"
}
DELETE /api/v1/webhooks/(webhook_id)

Delete a configured webhook from the server by ID.

Example Request:

DELETE /api/v1/webhooks/1 HTTP/1.1

Example Response:

A successful response will return a 204 status.

HTTP/1.1 204 No Content

Error Responses

A 404 status is returned if the specified webhook does not exist.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "webhook_id_not_found": 1
}
DELETE /api/v1/title/(name_id)

Delete a patch definition on the server.

Example Request:

DELETE /api/v1/title/Composer HTTP/1.1

Example Response:

A successful response will return a 204 status.

HTTP/1.1 204 No Content

Error Responses

A 404 status is returned if the specified patch definition does not exist.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "title_not_found": "Composer"
}