Item File API

An Item File API call lets you move attached files between KaiNexus and another system. This is useful when your organization needs to keep supporting documents, images, presentations, or other approved file types in sync with work managed in KaiNexus.

Note: This endpoint is separate from the JSON Item APIs and is used to upload and download file content.

The JSON Item APIs cannot upload or download files. However, if you only need information about files attached to an Item, you can include file metadata in the JSON Item Export API.

Authentication

Calls to the KaiNexus API can be authenticated using either an API Key or OAuth 2.0. Both authentication methods use Credentials associated with a Service Account, which determines the data and actions those Credentials can access.

Before making API calls, you must create a Service Account and securely save its Credentials, as they cannot be viewed again after creation.

To authenticate with API Keys:

Set authentication type to Basic Auth.
Username: api
Password: Your API Key

To authenticate with OAuth 2.0, reference Authenticating with OAuth 2.0 for details on how to use the Client ID and Client Secret to generate a token.

Important: Make sure your service account has been granted the necessary permission to view any Item you want to download a file from and edit any Item you want to upload a file to.

Uploading a file

To upload a file to an existing Item, send a POST request to this URL:

https://api.kainexus.com/api/public/v1/itemFile?itemId=XXXXX

Replace "XXXXX" with the ID of the Item you're attaching the file to.
This endpoint uploads one file per request to an existing Item.
The request must use multipart/form-data

The request supports the following fields:

Field	Required?	Description
file	Required	The file being uploaded.
name	Optional	A display name for the file. If omitted, the uploaded file's name is used.
description	Optional	A description for the file.
showInImageArea	Optional	Only applies to recognized image files. Controls whether the uploaded image also appears in the Item's Images panel and/or Images tab. Defaults to `true`. Set to `false` to attach the image to the Item without displaying it in the Images panel/tab. Non-image files are never displayed in the Images panel/tab, regardless of this value.

Note: File uploads use the POST /api/public/v1/itemFile endpoint, which is separate from the JSON Item APIs. The PUT /api/public/v1/json/item and PUT /api/public/v1/json/itemList endpoints support Item data only and cannot be used to upload file content.

Exporting a file

To export a file already attached to an Item, send a GET request to this URL:

https://api.kainexus.com/api/public/v1/itemFile?itemId=XXXXX&fileId=YYYYY

Replace "XXXXX" with the ID of the Item the file is attached to.
Replace "YYYYY" with the ID of the specific file you want to download.
Both itemId and fileId are required. The response returns the file's actual content, not a JSON description of it.

Pro Tip: You can find a file's ID in the files list returned by a JSON Item export when includeFiles=true is used.

Response data for uploads

A successful upload returns metadata about the file, including:

ID
Name
File name
File type
Size
Description
Created date

Constraints and expectations

One file per request.
Maximum file size is 50 MB.
The file must use an approved file type. See supported files in Attach a File to an Item.
Only files attached to an Item can be downloaded.

Troubleshooting

Status Code	Meaning
200	The request succeeded.
400	The request is invalid, or references data your Credentials can't access.
401	Authentication failed.
413	The file exceeds the maximum allowed size.
429	Too many file requests were sent too quickly.

Pro Tip: File upload and download calls can return 429 Too Many Requests if too many requests are sent in a short period of time. If this occurs, reduce the frequency of your calls and retry after the number of seconds shown in the X-Rate-Limit-Retry-After-Seconds response header.