File/Image Uploads

Uploading a file or image via the Knack API is a two step process. The first step will perform an HTTP POST request with a multipart/form-data content type to one of the following URLs, depending on what you are uploading:

for files: https://api.knack.com/v1/applications/app_id/assets/file/upload
for images: https://api.knack.com/v1/applications/app_id/assets/image/upload

The second step is to then create a new record using the information from the response in the first step.

🚧
Asset uploads should only ever be connected to individual fields.
Knack does not support the same asset file (representing one file upload) to be connected to more than one field. It is okay to have the same file/image for different fields/records but these will be different copies of the same asset file. If you wish to upload the same file and connect it to multiple fields, you must re-upload the file for each field you wish to connect the file to.

1. Uploading the File

The following is a cURL request which uploads a file (replace “file” with “image” when uploading an image file):

curl -X POST "https://api.knack.com/v1/applications/YOUR-APP-ID/assets/file/upload" \
  -H 'content-type: multipart/form-data' \
  -H 'x-knack-rest-api-key: YOUR-API-KEY' \
  -H 'x-knack-application-ID: YOUR-APP-ID'\
  -F "files=@/path/to/your/file.txt"

File uploading can also be done via JavaScript/AJAX (replace “file” with “image” when uploading an image file):

var app_id = Knack.application_id;

    var form = new FormData();
    // change #myfileinput to select your <input type="file" /> element
    var file = $(`#myfileinput`)[0].files[0];
    form.append(`files`, file);

    var url = `https://api.knack.com/v1/applications/${app_id}/assets/file/upload`;
    var headers = {
      'X-Knack-Application-ID': app_id,
      'X-Knack-REST-API-Key': `knack`,
    };

    Knack.showSpinner();

    // Make the AJAX call
    $.ajax({
      url: url,
      type: `POST`,
      headers: headers,
      processData: false,
      contentType: false,
      mimeType: `multipart/form-data`,
      data: form,
    }).done(function(responseData) {
      console.log(responseData);
      Knack.hideSpinner();
    });

A successful POST will return the following JSON response representing details about the uploaded file:

{
    "id": "623b3878eff91f001ecef70a",
    "type": "file",
    "filename": "SOMEFILENAME.txt",
    "public_url": "https://api.knack.com/v1/applications/61606f1f1d50ef001f38678a/download/asset/623b3878eff91f001ecef70a/SOMEFILENAME.txt",
    "thumb_url": "",
    "size": 1365
}

That public_url property can be used to download the file.

2. Creating the Record

This response contains an id property that you will use in the next step. The public_url property will contain a direct link to the file itself, and the thumb_url property will contain a link to a thumbnail if an image was uploaded.

Use the file_id from the JSON response to make a second POST request to create a record referencing your file. Set that file_id to your image or file field.

The following is a cURL example, assuming field_1 is a file or image field:

curl -X POST "https://api.knack.com/v1/objects/object_xx/records" \
  -H "x-knack-rest-api-key: YOUR-API-KEY" \
	-H "x-knack-application-id: YOUR-APP-ID" \
	-H "content-type: application/json" \
	--data '{"field_1": "YOUR-FILE-ID"}'

Once the file is associated to a specific record, when you call API to retrieve records there is a value like this:

{
    ....
    "field_240": "<a class=\"kn-view-asset\" data-field-key=\"field_240\" data-asset-id=\"623b35c9eff91f001ecef6fc\" data-file-name=\"SOMEFILENAME.txt\" href=\"https://api.knack.com/v1/applications/61606f1f1d50ef001f38678a/download/asset/623b35c9eff91f001ecef6fc/SOMEFILENAME.txt\">SOMEFILENAME.txt</a>",
    "field_240_raw": {
        "id": "623b35c9eff91f001ecef6fc",
        "application_id": "61606f1f1d50ef001f38678a",
        "s3": true,
        "type": "file",
        "filename": "SOMEFILENAME.txt",
        "url": "https://api.knack.com/v1/applications/61606f1f1d50ef001f38678a/download/asset/623b35c9eff91f001ecef6fc/SOMEFILENAME.txt",
        "thumb_url": "",
        "size": 454,
        "field_key": "field_240"
    },
    ....
}

The field_xxx_raw.url property can be used to retrieve the file content.

🚧Asset uploads should only ever be connected to individual fields.

1. Uploading the File

2. Creating the Record

🚧
Asset uploads should only ever be connected to individual fields.