API

Base API

This is a documentation page for PatchKit API (Version 1). This API allows users with API access (enabled on your plan) to manage applications on their PatchKit account.

The examples provided here are basic but will help you to understand how to work with these entities. If you need any assistance, don’t hesitate to contact support.

If you’re looking for the full API specification, you can find it here.

Response Status Codes

PatchKit API uses HTTP status codes to indicate the operation result. Here is a list of the most common return codes:

Authentication

You can authenticate with the PatchKit API using the API Key found on your account page. Do not share your API Key with anyone you don’t trust. It gives full access to your account. You can always invalidate your API Key by generating a new one on the same page. Note that not every endpoint requires authentication. Some endpoints are public (e.g., application info). Passing your API Key to these endpoints won’t cause harm.

You can authenticate a request in one of two ways:

By Query Parameters

Simply add the api_key parameter to your query:

https://api2.patchkit.net/resource?api_key=52293bd82f5cbd049cf398c3f52547aa

By Header

A more elegant way to authenticate is to use the X-Api-Key header:

GET /resource HTTP/1.1
X-Api-Key: 52293bd82f5cbd049cf398c3f52547aa

Examples

Creating and Publishing a New Application

If you’re integrating the PatchKit upload system on your webpage, this is the first thing you might be trying to integrate.

Creating an Application

curl -d "name=my_new_app&platform=windows_x86_64" -H "X-Api-Key: APIKEY" -X POST https://api2.patchkit.net/1/apps

This creates a new application entity with a given internal name:

{
  "id": 1,
  "secret": "secret_string",
  "platform": "windows_x86_64",
  "name": "my_new_app",
  ...
}

Use the application secret to identify the entity.

Creating a Version

Before you can upload new application content, you need to create a new version. This is a straightforward process:

curl -d "label=1.0" -H "X-Api-Key: APIKEY" -X POST https://api2.patchkit.net/1/apps/APP_SECRET/versions

On success, the following JSON will be returned:

{
  "id": 1,
  "label": "1.0",
  "publish_date": 0,
  "draft": true,
  ...
}

Uploading a Version

To upload a version, we first need to create a new Upload object. This object enables us to upload large payloads in chunks and even resume the upload in case of network failure or if the upload has been intentionally paused.

It is important to note that you need to upload the application as one file. It must be a ZIP file using STORE or DEFLATE algorithms. DEFLATE64 is not supported. Additionally, you need to know the ZIP file size before starting the upload.

Here is the command to create a new upload object:

curl -d "total_size_bytes=1234567" -H "X-Api-Key: APIKEY" -X POST https://api2.patchkit.net/1/uploads

After executing the command, you will receive a JSON response containing the created upload id:

{
  "id": 1
}

Uploading Chunks

We recommend splitting the uploaded content into 10-megabyte chunks. To upload your chunks, use the following command:

curl -F "chunk=@/tmp/chunk.data" -F "md5=ff15aae3a7a1f9701ec4c7ade37d7bf9" -H "X-Api-Key: APIKEY" -H "Content-Range: bytes 0-10485759" -X POST https://api.patchkit.net/1/uploads/UPLOAD_ID/chunk

You can pass an optional md5 parameter. If you do, the uploaded chunk’s MD5 sum will be validated against the value of the md5 parameter. If the validation fails, the API will return HTTP 412, and you should try re-uploading that chunk.

On a successful chunk upload, you will receive a 201 status code.

Processing the upload

Once all the chunks are uploaded, the application files need to be converted to the format required for the distribution process. This includes creating an encrypted content file and delta (diff) file. The processing time is dependent on the application size and can be queried through the API.

curl -F "upload_id=UPLOAD_ID" -H "X-Api-Key: APIKEY" -X PUT "https://api2.patchkit.net/1/apps/APP_SECRET/versions/VERSION_ID/content_file"

This returns a JSON with a job_guid field:

{
  "job_guid": "5776de94-56dc-4e8a-8992-1c1d9da1410c"
}

Job Monitoring

Once you have the job_guid (UUID), you can monitor the progress of the process by sending a GET request:

curl "https://api2.patchkit.net/1/background_jobs/JOB_GUID"

You will receive a response similar to this:

{
  "time_started": "2021-10-19T11:14:50.176Z",
  "time_finished": null,
  "progress": 0.1,
  "pending": true,
  "finished": false,
  "status": 0,
  "status_message": "waiting for free worker..."
}

The progress field is the most important, as it represents the percentage of the process that has been completed. You can use this field to show progress to the user. The status_message field provides additional information about the process. The job is considered finished when the finished field returns true.

Looking for Errors

After the application is processed, you need to check for processing messages or errors. Any error is critical, so the application cannot be published if it has at least one of those.

To get version processing information, you should fetch the version info:

https://api2.patchkit.net/1/apps/APP_SECRET/versions/VERSION_ID

In the response, you will receive a JSON object with many fields, but you should focus on two of them:

{
  ...,
  "has_processing_error": true,
  "processing_messages": [
    {
      "severity": "info",
      "message": "string"
    }
  ]
}

The has_processing_error field is the most critical. If it’s set to true, it means that PatchKit couldn’t finish the processing stage due to a critical error. You won’t get the error message, but it’s safe to assume that something went wrong with the upload process. Usually, re-uploading should help.

If there are any elements in processing_messages, you should check if there are any errors ("severity": "error"). Errors will prevent the version from being published, so this is important information to the user to know what needs to be fixed. Warnings ("severity": "warning") and info messages ("severity": "info") can be ignored, but it’s highly recommended to at least present warnings to the user.

Publishing it

If there are no errors, you can now publish the application version:

curl -H "X-Api-Key: APIKEY" -X POST https://api2.patchkit.net/1/apps/APP_SECRET/versions/VERSION_ID/publish

This time to get the publishing process, you need to query the version itself. Publishing is not a job (currently) because even if all files have been published, the entity itself can still be in an unpublished state (scheduled publishing).

https://api2.patchkit.net/1/apps/APP_SECRET/versions/VERSION_ID

Look for these fields:

  "pending_publish": true,
  "published": false,
  "publish_progress": 0,
  "publish_time": 0

• pending_publish field tells if the version is currently in the publishing stage.
• published set to true indicates that the version is now publicly available.
• publish_process can be used to display % progress to the user.
• publish_time if set anything but 0 and published is false at the same time, it means that the publish date & time has been scheduled for the future. The progress can be at 1 most of the time here, but the published will stay false until the publish_time is reached.

API Specification (OpenAPI)

You can read the full specification here.

App Catalog API

This is a documentation page for PatchKit App Catalog API (Version 1). You can learn more about App Catalog here.

Requests

All requests should be made to the https://app-catalog.patchkit.net/v1/ endpoint.

Requests can be passed as application/form-data, application/json, or application/multipart. REST libraries should handle the formats automatically based on the parameters being passed.

Responses

The App Catalog API uses JSON format for all responses. Entity IDs are UUID strings.

Response Status Codes

Authentication

To access the full functionality of the App Catalog API, you will need to provide the Owner API Key for your catalog. This key can be obtained by contacting support.

To use the Owner API Key, include it in the X-Api-Key header of your API request, like this:

GET /resource HTTP/1.1
X-Api-Key: 52293bd82f5cbd049cf398c3f52547aa

Examples

Creating a New Catalog

To create a new catalog, follow these steps:

1. Log in to the PatchKit web interface.
2. Navigate to the “Catalogs” section.
3. Click on the “Create Catalog” button.
4. Fill in the necessary information for the new catalog.
5. Click on the “Create” button.

Creating a New Application

To create a new application, use the following API request:

curl -d "name=my_new_app" -H "X-Api-Key: APIKEY" -X POST https://app-catalog.patchkit.net/v1/catalogs/CATALOG_ID/apps/

In the API request, replace APIKEY with your API key and CATALOG_ID with the UUID of the catalog you want to add the application to.

The API will return a JSON response, which will include the id of the newly created application:

Assigning a PatchKit Application

Assigning a PatchKit application to an App Catalog entity allows users to download the application for a specific platform. This operation will reveal the application’s secret to the requester.

To assign a PatchKit application to an App Catalog entity, use the following API request:

curl -d "platform=windows_x86_64&secret=APP_SECRET" -H "X-Api-Key: APIKEY" -X POST https://app-catalog.patchkit.net/v1/catalogs/CATALOG_ID/apps/APP_ID/patchkit_apps

In the API request, replace APIKEY with your API key, CATALOG_ID with the UUID of the catalog, APP_ID with the UUID of the App Catalog entity, and APP_SECRET with the secret of the PatchKit application.

API Specification (OpenAPI)

The full API specification for the App Catalog API is available in OpenAPI format. You can access it by visiting the following link:

App Catalog API Specification (OpenAPI)