File/Image Uploads

Suggest Edits

Uploading a file or image via the Knack API is a two step process. The first will perform an HTTP POST request with a multipart/form-data content type to the following URL: https://api.knack.com/v1/applications/app_id/assets/file/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 one record.

Knack does not support one asset ID (representing one file upload) to be connected to more than one record. If you wish to upload the same file and connect it to multiple records, you must re-upload the file for each record 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.

Updated about 19 hours ago

What’s Next