Skip to main content

API File Upload

Learn how to search folders, retrieve items, upload files, and download files through the Farseer API using authenticated requests with service users and API keys.

Updated over a week ago

Prerequisites

You need to create a Service user and an API key to use for interaction with the API.

The API key is placed in the header X-API-KEY of each request (just a plain string, no prefix, and no encoding).

Requests are made to the address https://instance-name.farseer.io (the endpoint is added to this address).

Searching for a Specific Item (folder, file, ...)

Endpoint: POST /api/v3/folders/search

Request body:

application/json

interface SearchFolderRequest { 
    name: string; 
    types: Array<FolderItemType>; 
    limit: number; 
}

The search is performed by name, and all results that have the requested name and one of the types listed in the types array are returned.

FolderItemType is an enum string with possible values:

'DOCUMENT' | 'DIMENSION_TABLE' | 'VARIABLE' | 'SHEET' | 'FOLDER' | 'FARSEER_FILE';

The limit parameter must be at least 1 and at most 20.

Response:

application/json

interface FolderItemRepresentation {
    id: number;
    path: Array<number>;
    name: string;
    type: FolderItemType;
    allowedTypes: Array<FolderItemType>;
    reference: string;
    order: number;
    canEdit: boolean;
}

  • id is a unique numeric identifier of that item.

  • path contains the id values of all ancestors of the item.

  • name is the name of the item.

  • type is the type of the item and corresponds to one of the values mentioned above for FolderItemType.

  • allowedTypes contains the types of items that are allowed as children of this item.

  • reference contains the id of the object for which there is an item and is always a string.

  • order is the number of the item in the order relative to items with the same parent.

  • canEdit is a flag that indicates whether the item can be edited.

Example of an item related to a folder:

{
    id: 15,
    path: [13],
    name: "Balance XML Upload",
    type: "FOLDER",
    allowedTypes: ["FARSEER_FILE", "FOLDER"],
    reference: "15",
    order: 0,
    canEdit: true,
}

Folders in the reference field contain their own id in string format. Retrieving folders is important because it is easier to retrieve a folder and then search for all items (e.g., files) within it than to search for each file individually.

Example of an item related to a file:

{
    id: 20,
    path: [13, 15, 17],
    name: "BIL31102022.xml",
    type: "FARSEER_FILE",
    allowedTypes: [],
    reference: "cc82219f-1129-43e6-991c-9757d024c9ad",
    order: 0,
    canEdit: true,
}

Items related to files in the reference field contain a unique file identifier, further farseerFileId, which is used to retrieve the file's content or delete it.

Searching for Items in a Folder

To search for items located in a folder, you only need to know its id. If it's not known, find it by searching by name as described above.

Endpoint: POST /api/v3/folders/items

Request body:

application/json

type GetItemsFolderRequest = Array<{ id: number | null }>;

It is possible to search for multiple folders in the same request. Always send an array, even when searching for only one folder.
In the array, each element is an object with the id property, which contains the folder's id. If id is set to null, the root is searched, i.e., all items with no parent are returned.

Response:

application/json

type GetItemsFolderResult = Array<{
    folder?: FolderItemRepresentation;
    items: Array<FolderItemRepresentation>;
}>;

According to the request, where an array is always sent (and it is possible to search for multiple folders at once), the result is always an array of the same size, and each element in the result array corresponds to a folder in the request at the same index.

The folder field contains the item for the folder that was searched for, i.e., it is empty if id was set to null. The items field contains an array of all items that are direct children of the searched folder. If some of the children are also folders and you want to get their children as well, you need to make a new request to search for items in that folder.

Objects representing the searched folder and all its children are of type FolderItemRepresentation, which is described above.

Uploading a File to Farseer

To create a new file in a folder, you only need the id of the folder.

Endpoint: POST /api/v3/farseerFiles

Request body:

multipart/form-data

file: binary data
category: string
folderId: string (optional)

Most of the API works with JSON objects, but here, for uploading a file, you need to use multipart/form-data. The file's content is written to the file field. The category field contains an arbitrary category that is saved with the file. The folderId field (optional) contains the folder's id (it needs to be converted to a string) that is used as the parent for the newly created file.

Example (in TypeScript, with the additional packages axios and form-data installed):

import * as fs from 'fs';
import * as axios from 'axios';
import * as formData from 'form-data';

async function uploadFile() {
    const fileBuffer = fs.readFileSync('/path/to/file.xlsx');
    const fileFormData = new formData.default();
    fileFormData.append('file', fileBuffer, {
        filename: 'my-file.xlsx',
        contentType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
    });
    fileFormData.append('category', 'BALANCE_UPLOAD');
    fileFormData.append('folderId', '15');
    await axios.default.post('https://koncar-dev.farseer.io/api/v3/farseerFiles', fileFormData, {
        headers: { 'X-API-KEY': '01234apikey' },
    });
}

Response:

application/json

interface FarseerFileRepresentation {
    id: string;
    name: string;
    type: string;
    category: string;
    size: number;
    uploadTime?: Date | null;
    uploader?: {
        id: number;
        email: string | null;
        firstName: string | null;
        lastName: string | null;
    } | null;
    importJobCount?: number | null;
}

Downloading a File from Farseer

To retrieve the content of a file, you need the farseerFileId (a string in the reference field of the item representing the file).

Endpoint: GET /api/v3/farseerFiles/${farseerFileId} (replace farseerFileId with the actual id)

Example (in TypeScript, with the axios package installed):

import * as axios from 'axios';

async function downloadFile(): Promise<Buffer> {
    const res = await axios.default.get<Buffer>(
        'https://koncar-dev.farseer.io/api/v3/farseerFiles/cc82219f-1129-43e6-991c-9757d024c9ad',
        {
            headers: { 'X-API-KEY': '01234apikey' },
            responseType: 'arraybuffer',
        }
    );
    const fileBuffer = res.data;
    return fileBuffer;
}

Response:

multipart/form-data binary string

Did this answer your question?