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.

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

{
    "items": [
        {
            "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

Warning

You may pass multiple version objects in the items array to this endpoint. You must arrange these objects in descending order of the version to be written to the patch definition correctly!

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/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"
}