Filesystem API (V2)

The Filesystem API allows you to perform common file operations on Instabase platform, including reading files, writing files, copying, moving, deleting files and folders, and extracting ZIP archives.

Unless otherwise specified, all Filesystem API endpoints require an Authorization header with the value Bearer XYZ, where XYZ is your access token. See API authorization.

In this document, URL_BASE refers to the root URL of your Instabase instance, such as https://www.instabase.com. API_ROOT defines where to route API requests for file operations on your Instabase instance, and its value is URL_BASE appended by /api/v2/files.

import json, requests

url_base = "https://www.instabase.com"
api_root = url_base + '/api/v2/files'

In addition, it’s common to refer to a Instabase path as SUBSPACE_OWNER/SUBSPACE_NAME/fs/DRIVE_NAME/PATH in this document, where each component’s meaning can be found below.

SUBSPACE_OWNER is the name of the user or org the subspace belongs to.

SUBSPACE_NAME is the name of the subspace the file or folder is in.

DRIVE_NAME is the name of the drive the file or folder is in.

PATH is the relative path with respect to the drive.

Create an empty file or folder

Description

Create an empty file or folder by sending a POST request to the endpoint URL with the request body encoded as JSON. FOLDER_PATH in the endpoint refers to the parent folder of the targeted file or folder. If FOLDER_PATH is empty, then the new file or folder gets created at the top level of the drive.

The HTTP call returns either after the targeted file or folder is successfully created, or after an error is encountered.

If the path FOLDER_PATH doesn’t exist, then the HTTP call creates this parent folder before creating the targeted file or folder. Otherwise, FOLDER_PATH must be a valid folder path. If it corresponds to a file, then a Bad Request HTTP status code gets returned.

Request body

The request body is a JSON object containing details about the file or folder to be created.

Parameters are required unless marked as optional.

Note: You can create intermediate folders by passing a nested path in the name parameter. For example, if you specify name as foo/bar/file.txt, then the file system creates both foo and foo/bar folders under the specified drive, provided that these paths don’t correspond to files.

Response status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful, unless marked as optional.

Note: The URL returned from the Location header is URL-encoded.

Examples

Request

url = api_root + '/jaydoe/my-repo/fs/Instabase Drive'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}
data = json.dumps({'name': 'file.txt',
                   'node_type': 'file'})
resp = requests.post(url, headers=headers, data=data)

This creates a file named file.txt in the top level of jaydoe’s Instabase Drive drive.

Response

HTTP STATUS CODE 201

# headers
{
  'Location': 'API_ROOT/jaydoe/my-repo/fs/Instabase%20Drive/file.txt'
}

Create a non-empty file or overwrite a file

Description

Create a non-empty file or overwrite a file by sending a PUT request to the endpoint URL with the file payload as the request body.

If the parent folder of PATH doesn’t exist, the file system creates the parent folder first before creating the file. The parent folder must be a folder or an error is returned.

Request headers

Request body

The request body contains the contents of the file to be written.

Response status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful unless marked as optional.

Examples

Request

import requests

url = api_root + '/jaydoe/my-repo/fs/Instabase Drive/new_file.txt'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

data = bytes('hello world', 'utf-8')
resp = requests.put(url, headers=headers, data=data)

This request creates or replaces a file at the target path with a file containing the text “hello world”.

Response

HTTP STATUS CODE 204

Append content to a file

Description

Append content to a file by sending a PATCH to the endpoint URL shown above with appending file payload as the request body.

Request headers

Note: If the IB-Cursor header is specified and set to 0, the file is created if it doesn’t already exist. Otherwise, the file must already exist.

Request body

The request body contains the data to be appended to the file.

Response status

A 2XX status code indicates the request was successful.

Examples

Request

url = api_root + '/jaydoe/my-repo/fs/Instabase Drive/file.txt'

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'IB-Cursor': '-1'
}
data = bytes('data to append', 'utf-8')

r = requests.patch(url, headers=headers, data=data)

This request is appending to an existing file.

Response

HTTP STATUS CODE 204

Read a file

Description

Read contents from a file by sending a GET request to the URL endpoint shown above.

URL parameters

Parameters are required unless marked as optional.

Request headers

Request body

This request contains no body.

Response status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful unless marked as optional.

Response schema

The response body contains the contents of the read file, or the partial contents if a Range header was provided.

Examples

Request

url = api_root + '/jaydoe/my-repo/fs/Instabase Drive/hello_world.txt'
params = {'expect-node-type':'file'}
headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Range': 'bytes=0-4'
}

r = requests.get(url, headers=headers, params=params)

This request uses the Range header to read the first 5 bytes of the target file.

Response

HTTP STATUS CODE 206

#headers
{
  'Content-Type': 'application/octet-stream',
  'Content-Length': '5',
  'Content-Range': 'bytes 0-4/*'
}

#body
b'hello'

Read metadata from a file or folder

Description

Read metadata of a file or folder at the target path by sending a HEAD request to the endpoint shown above.

This API can be used to tell whether the object at the target path is a file or folder. If it is a file, it can also be used to find the size of the file and the time the file was last modified.

Request headers

Request body

The request does not have a body.

Response status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful unless marked as optional.

Response schema

The response does not have a body.

Examples

Request

url = api_root + '/jaydoe/my-repo/fs/Instabase Drive/file.txt'

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'IB-Retry-Config' : json.dumps({
    'retries' : 2,
    'backoff-seconds' : 1
  })
}

r = requests.head(url, headers=headers)

The IB-Retry-Config header provided here specifies that if the object at the path can’t be found immediately, the server retries twice, with an initial backoff of 1 second, before responding.

Response

HTTP STATUS CODE 200

#headers
{
  'Content-Type': 'application/octet-stream',
  'Content-Length': '4',
  'Last-Modified': 'Wed, 03 Aug 2022 17:25:51 GMT'
}

The Content-Type of application/octet-stream indicates that the object at this path contains a file. The Content-Length header indicates the file is 4 bytes long.

List Directory

Description

List the content of a directory by sending a GET to the endpoint URL shown above. Folders and files that are located directly under the target folder are returned. Results are paginated with a page size of 100.

URL parameters

Parameters are required unless marked as optional.

Request body

The request has no body.

Response status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful unless marked as optional.

Response schema

This body contains a JSON object with information about the directory.

All keys are returned in the response by default, unless marked as optional.

Examples

Request

url = api_root + '/jaydoe/my-repo/fs/Instabase Drive/folder'

params = {'expect-node-type':'folder'}
headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.get(url, headers=headers, params=params)

Response

HTTP STATUS CODE 200

#headers
{
  'Content-Type': 'application/json',
  'Content-Length': '497'
}

#body
{
  "nodes":
  [
    {
      "name": "subdir",
      "rel_path": "folder/subdir",
      "full_path": "jaydoe/my-repo/fs/Instabase Drive/folder/subdir",
      "metadata":
      {
        "node_type": "folder"
      },
      "perms":
      {
        "can_read": true,
        "can_write": true,
        "can_delete": true
      }
    },
    {
      "name": "test.txt",
      "rel_path": "folder/test.txt",
      "full_path": "adrianb/pubtest/fs/Instabase Drive/folder/test.txt",
      "metadata":
      {
        "node_type": "file",
        "size": 11,
        "modified_timestamp": 1659172583
      },
      "perms":
      {
        "can_read": true,
        "can_write": true,
        "can_delete": true
      }
  ],
  "next_page_token": "",
  "has_more": false
}

This response lists the children of a directory that contains two other folders. The has_more key is false, indicating that there are no more contents to list.

Delete a file or folder

Description

Delete a single file or folder by sending a DELETE to the endpoint URL shown above.

Request body

There is no request body.

Response status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful unless marked as optional.

You can poll the status of the deletion job by using the Location header. See Poll status of an async file operation for details.

Examples

Request

url = api_root + '/jaydoe/my-repo/fs/Instabase Drive/file.txt'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

r = requests.delete(url, headers=headers)

Response

HTTP STATUS CODE 202

#headers
# The value of the Location header has been modified to not show the URL base.
{
  'Location': '{API_ROOT}/delete/jobs/53275652-abc8-479e-89f2-ccb12af401a0'
}

The deletion request has been accepted. Whether it is still in progress, or if it has succeeded or failed, can be checked at the URL provided in the Location header.

Copy a file or folder

Description

Copy a file or folder to a new location by sending a POST to the URL endpoint shown above with the request body encoded as JSON. The source and destination paths are included in the request body.

The HTTP call returns immediately while the copy execution proceeds asynchronously in the background. If successful, the response header contains a URL endpoint that you can use to check the status of the copy operation.

Request body

The request body is a JSON object containing details about the source and destination path.

Parameters are required unless marked as optional.

As this API is capable of copying both file and folders, its semantics depends on the type of src_path and dst_path and is summarized below:

• If src_path doesn’t exist, the API returns an error.

• If src_path is a file and dst_path is a folder, or src_path is a folder and dst_path is a file, the API returns an error.

• If src_path is a file and dst_path is a file, then the source file gets copied to the destination path. If a file already exists at the destination path, it gets overwritten after the copy operation.

• If src_path is a folder and dst_path is a folder, then

  a) If src_path is a parent folder of dst_path, then the API returns an error.

  b) Otherwise, copy the content from src_path (recursively) to dst_path, overwriting files that already exist in the destination path.

If the destination path doesn’t exist, the file system creates it and its parent folders recursively.

Note: There is a corner case where when dst_path is a parent folder of src_path, copying contents from src_path could end up modifying the source folder itself. If this happens, the API backend detects this and returns an error.

The semantics of this copy API are slightly different from Linux’s cp command: if the destination path is an existing folder, the source folder would be copied into the destination folder. So if you aim to copy a folder named foo into a folder named bar—as opposed to just the content of foo—you can set src_path to foo and dst_path to bar/foo.

Response Status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful unless marked as optional.

You can poll the status of the copy job by using the Location header. See Poll status of an async file operation for details.

Examples

Request

url = api_root + '/copy'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

data = json.dumps({
  'src_path': 'jaydoe/my-repo/fs/Instabase Drive/foo.txt',
  'dst_path': 'jaydoe/my-repo/fs/Instabase Drive/bar.txt'
})

r = requests.post(url, headers=headers)

Response

HTTP STATUS CODE 202

#headers
# The value of the Location header has been modified to not show the URL base.
{
  'Location': '{API_ROOT}/copy/jobs/53275652-abc8-479e-89f2-ccb12af401a0'
}

The copy request has been accepted. Whether it is still in progress, or if it has succeeded or failed, can be checked at the URL provided in the Location header. See Poll status of an async file operation for details.

Move a file or folder

Description

Move a file or folder to a new location by sending a POST to the URL endpoint shown above with the request body encoded as JSON. The source and destination paths are included in the request body.

The HTTP call returns immediately while the move execution proceeds asynchronously in the background. If successful, the response header contains a URL endpoint that you can use to check the status of the move operation.

Request body

The request body is a JSON object containing details about the source and destination path.

Parameters are required unless marked as optional.

The semantics of src_path and dst_path is the same as the COPY API, except that src_path is expected to be removed if the move operation is successful.

Response Status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful unless marked as optional.

You can poll the status of the move job by using the Location header. See Poll status of an async file operation for details.

Examples

Request

url = api_root + '/move'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

data = json.dumps({
  'src_path': 'jaydoe/my-repo/fs/Instabase Drive/foo.txt',
  'dst_path': 'jaydoe/my-repo/fs/Instabase Drive/bar.txt'
})

r = requests.post(url, headers=headers, data=data)

Response

HTTP STATUS CODE 202

#headers
# The value of the Location header has been modified to not show the URL base.
{
  'Location': '{API_ROOT}/move/jobs/53275652-abc8-479e-89f2-ccb12af401a0'
}

The move request has been accepted. Whether it is still in progress, or if it has succeeded or failed, can be checked at the URL provided in the Location header. See Poll status of an async file operation for details.

Extract a ZIP file

Description

Extract a zip file to a new location by sending a POST to the URL endpoint shown above with the request body encoded as JSON. The source and destination paths are included in the request body.

If the destination path does not exist, the endpoint creates it and any necessary parent directories.

If the extracted path of a file conflicts with an existing file on disk, the endpoint overwrites the existing file.

The HTTP call returns immediately while the extract execution proceeds asynchronously in the background. If successful, the response header contains a URL endpoint that you can use to check the status of the extract operation.

Request body

The request body is a JSON object containing the source and destination paths.

Response Status

A 2XX status code indicates the request was successful.

Response headers

Headers are always present if the request was successful unless marked as optional.

You can poll the status of the copy job by using the Location header. See Poll status of an async file operation for details.

Examples

Request

url = api_root + '/extract'

headers = {
  'Authorization': 'Bearer {0}'.format(token)
}

data = json.dumps({
  'src_path': 'jaydoe/my-repo/fs/Instabase Drive/foo.zip',
  'dst_path': 'jaydoe/my-repo/fs/Instabase Drive/target'
})

r = requests.post(url, headers=headers)

Response

HTTP STATUS CODE 202

#headers
# The value of the Location header has been modified to not show the URL base.
{
  'Location': '{API_ROOT}/extract/jobs/53275652-abc8-479e-89f2-ccb12af401a0'
}

The extract request has been accepted. Whether it is still in progress, or if it has succeeded or failed, can be checked at the URL provided in the Location header. See Poll status of an async file operation for details.

Poll status of an async file operation

ACTION - The async operations, including copy, move, delete, and extract.

JOB_ID - A UUID string that is returned from the Location header from the response when creating an async operation.

Description

Poll the status of an asynchronous file operation (copy, move, delete and extract) by sending a GET to the URL endpoint shown above.

Request body

The request body contains the contents of the file to be written.

Response status

Any 2XX status code indicates the request was successful.

Examples

Request

url = api_root + '/delete/jobs/53275652-abc8-479e-89f2-ccb12af401a0'
headers = {
  'Authorization': 'Bearer {0}'.format(token),
}

r = requests.get(url, headers=headers)

Response

HTTP STATUS CODE 200

#body
{
  'state': 'PENDING' | 'COMPLETE' | 'FAILED' | 'RUNNING'
}