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.
Make sure to authenticate all requests using the API key you can obtain in your account’s settings.
Note that changes made via the API may have immediate effects on your account and data. Make sure to perform API operations with caution.
Response Status Codes
PatchKit API uses HTTP status codes to indicate the operation result. Here is a list of the most common return codes:
Code | Status | Description |
---|---|---|
200 | OK | Generic success response. Usually renders resource in the response body. |
201 | Created | Indicates that the resource has been created successfully. Usually renders that resource in the response body. |
204 | No Content | Indicates success but states that nothing will be rendered in the response body. |
400 | Bad Request | Returned when there is an issue with the parameters. Inspect the response body to find a human-readable error message. |
401 | Unauthorized | Indicates that this resource requires authentication, but the request lacks valid authentication credentials. |
403 | Forbidden | Returned when the current user does not have the required access to this resource. |
404 | Not Found | Indicates that the resource does not exist or is not known in the given context. |
500 | Internal Server Error | If you receive this code, try making the request again. Repeated failures should be reported to the PatchKit Support team. |
Please note that unexpected errors may occur. For other errors, make sure to read the response body carefully to obtain a human-readable error message.
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:
Note that for chunks upload, you should use a different API host. Instead of api2.patchkit.net, use api.patchkit.net. This is the only place where you need to use the api.patchkit.net host.
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
Code | Status | Description |
---|---|---|
200 | OK | Generic success response. Usually renders resource in the response body. |
201 | Created | Indicates that the resource has been created successfully. Usually renders that resource in the response body. |
204 | No Content | Indicates success but states that nothing will be rendered in the response body. |
400 | Bad Request | Returned when something is not right with the parameters. Check the response body for an error message. |
401 | Unauthorized | Indicates that the request requires authentication, but the credentials are invalid. |
403 | Forbidden | Returned when the current user does not have the required access to the resource. |
404 | Not Found | Indicates that the resource does not exist or is not known in the given context. |
500 | Internal Server Error | If received, try the request again. Report repeated failures to PatchKit Support. |
Authentication
The App Catalog API can be accessed without authentication, but some entities may not be visible to non-authenticated users.
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
The Owner API Key must be kept secret and treated with care, as it provides full access to your catalog.
Examples
Creating a New Catalog
Currently, you can only create a new catalog through the web browser.
To create a new catalog, follow these steps:
- Log in to the PatchKit web interface.
- Navigate to the “Catalogs” section.
- Click on the “Create Catalog” button.
- Fill in the necessary information for the new catalog.
- Click on the “Create” button.
Make sure to write down the Catalog ID (UUID) after creating the catalog. You will need it for all API requests related to the App Catalog.
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.
The available platforms are:
- windows_x86
- windows_x86_64
- linux_x86
- linux_x86_64
- osx_x86_64
Assigning an application has an immediate effect and will make the application’s secret visible to requesters.
In most cases, the application secret is the only required thing to download the application. However, this default behavior can be changed. Contact support to learn about the possibilities on your account.
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: