Filesystem API (deprecated)

Table of Contents

Use the Filesystem API to perform file management operations, including creating, deleting, and moving files and folders.

See Instabase API authorization and response conventions for authorization and response convention details.

For this API, api_root defines where to route API requests for your Instabase instance:

import json, requests

api_root = 'https://www.instabase.com/api/v1/drives'
root = '/<username>/<workspace_name>/fs/Instabase Drive/<path>'

Create a folder API

Use this API to create a folder in the Instabase file system.

Request

Create a folder by sending a POST request to api_root/ROOT/FOLDER_PATH with the post body encoded as JSON. where:

ROOT is the directory to invoke the Filesystem API
FOLDER_PATH is the path of the folder to create relative to ROOT

POST api_root/ROOT/FOLDER_PATH

# headers
Instabase-API-Args: {
  "type": "folder"
}

# body
N/A

The request must have an Instabase-API-Args header that is a JSON object with this field:

type: "folder"

Example (Python):

url = api_root + root + '/folder-name'

api_args=dict(
  type='folder',
)

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Instabase-API-Args': json.dumps(api_args)
}
resp = requests.post(url, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "status": "OK"
}

Write content to a file API

Use this API to write content to the specified file.

Request

Write contents to a file by sending a POST request to api_root/ROOT/FILE_PATH with the file content as the request body. where:

ROOT is the directory to invoke the Filesystem API
FILE_PATH is the path of the file relative to ROOT

POST api_root/ROOT/FILE_PATH

# headers
Instabase-API-Args: {
  "type": "file",
  "cursor": <integer>,
  "if_exists": <string>,
  "mime_type": <string>
}

# body
<file data>

The request must have an Instabase-API-Args header that is a JSON object with these fields:

type: "file"
cursor: (Optional) The index into the file to start writing data from. To write to the end of the file, set cursor=-1. If a cursor argument is provided, the file must already exist in the filesystem or the request will fail.
if_exists: "overwrite" | "modify" | "fail" This flag specifies what happens to the write request if file already exists.
- overwrite - the existing file is overwritten with the new content
- modify - the content is written starting at the index of the cursor, content is appended if the cursor is set to -1
- fail - the request fails and nothing is written
mime_type: The mime type of the file being written, or the mime type of any metadata to store with the file.

Example (Python):

url = api_root + root + '/a/b/file.txt'

api_args=dict(
  type='file',
  cursor=10,
  if_exists='overwrite',
  mime_type='pdf'
)

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Instabase-API-Args': json.dumps(api_args)
}

data = 'File 1 content'
resp = requests.post(url, data=data, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "status": "OK",
  "cursor": <integer>
}

The response body is a JSON object with the following field:

cursor: The index where the file write ended. -1 means the end of the file.

Read contents from a file API

Use this API to read contents from the specified file.

Request

Read contents from a file by sending a GET request to api_root/ROOT/FILE_PATH. where:

ROOT is the directory to invoke the Filesystem API
FILE_PATH is the path of the folder relative to ROOT

GET api_root/ROOT/FILE_PATH

# headers
Instabase-API-Args: {
  "type": "file",
  "get_content": true,
  "range": "bytes=<integer>-<integer>",
  "retry_config": {"num_retries"=<integer>, "backoff_interval_sec"=<integer>}
}

# body
N/A

The request must have an Instabase-API-Args header that is a JSON object with these fields:

type: "file"
get_content: true
range: "bytes-<start>-<end>" The range of content to read from the file, from the start to the end index. For example, specify an end index of -1 to read to the end of the file and specify "bytes=0--1" to read the whole file.
retry_config: (Optional) A dict that specifies the number of retries and backoff interval for retrying failed requests.

Example (Python):

url = base_url + root + '/file.txt'

api_args = dict(
  type='file',
  get_content=True,
  range='bytes=10-20'
)

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Instabase-API-Args': json.dumps(api_args)
}
r = requests.get(url, headers=headers)
resp = json.loads(r.headers['Instabase-API-Resp'])
data = r.content

Response

If successful:

HTTP STATUS CODE 200

# headers
Instabase-API-Resp: {
  "status": "OK",
  "metadata": {
    "modified_timestamp": <integer: unix timestamp of last modified time>,
    "size": <integer: number of bytes>,
    "type": "file"
  }
}
Content-Type: application/octet-stream

# body
<file data>

If execution error:

HTTP STATUS CODE 200

# headers
Instabase-API-Resp: {
  "status": "ERROR",
  "msg": <string: an error message>
}

# body
N/A

List directory API

Use this API to list the contents of a directory.

Request

List contents of a directory by sending a GET request to api_root/ROOT/PATH. `where:

ROOT is the directory to invoke the Filesystem API
FOLDER_PATH is the path of the folder to list directories from relative to ROOT

GET api_root/ROOT/PATH

# headers
Instabase-API-Args: {
  "type": "folder",
  "get_content": True,
  "get_metadata": False,
  "start_page_token": <string>,
}

# body
N/A

The request must have an Instabase-API-Args header that is a JSON object with these fields:

type: "folder"
get_content: true
get_metadata: <boolean> Whether or not to also retrieve metadata for each node. Defaults to False.
start_page_token: <string> Only 100 files are returned in each request. To paginate through all the files, specify a start-token to start from. Use the next-page-token returned from the previous list-dir response.

Example (Python):

url = api_root + root + '/dir'

api_args = dict(
  type='folder',
  get_content=True,
  get_metadata=False,
  start_page_token='foldername'
)

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Instabase-API-Args': json.dumps(api_args)
}

resp = requests.get(url, headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

# body
{
  "has_more": <boolean>,
  "next_page_token": <string>,
  "nodes": [
    {
      "full_path": <string>,
      "name": <string>,
      "path": <string>,
      "type": <string>
    }
  ],
  "start_page_token": <string>,
  "status": "OK"
}

The response body is a JSON object with the following fields:

has_more: true | false. Whether there are additional pages of results. At most 100 files are returned in each request.
next_page_token: <string>. Only 100 files are returned in each request. To paginate through all the files, specify a start_page_token to start from. Use this next_page_token returned from the previous list-dir response. Note that for the initial API call start_page_token should be set as an empty string.
nodes: a list of JSON objects, each representing one child node. Each node has these fields:
full_path: the full path of the node
name: the file or folder name
path: the node path within the repository and mount
type: file | folder.
start_page_token: <string>,
status: “OK”

Example response:

HTTP STATUS CODE 200

# body
{
  "has_more": true,
  "next_page_token": "files/api/file.txt",
  "nodes": [
    {
      "full_path": "anantb/workspace/fs/Instabase Drive/files/api/file.txt",
      "name": "file.txt",
      "path": "files/api/file.txt",
      "type": "file"
    }
    ...
  ],
  "start_page_token": "",
  "status": "OK"
}

Read metadata from a file or folder API

Use this API to read metadata from a specified file or folder.

Request

To read metadata from a file or folder, send a GET request to api_root/ROOT/FILE_OR_FOLDER_PATH. where:

ROOT is the directory to invoke the Filesystem API
FILE_OR_FOLDER_PATH is the path for the file or folder to get metadata for, relative to ROOT

GET api_root/ROOT/FILE_PATH

# headers
N/A

# body
N/A

Example (Python):

url = base_url + root + '/file.txt'  # could also be a folder, such as '/dir'

api_args = dict(
  type='file',
  get_content=False,
)

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Instabase-API-Args': json.dumps(api_args)
}
r = requests.get(url, headers=headers)

Response

If successful:

HTTP STATUS CODE 200

# body
## for file
{
  "status": "OK",
  "metadata": {
    "modified_timestamp": <integer: unix timestamp of last modified time>,
    "size": <integer: number of bytes>,
    "type": "file"
  }
}

## for folder
{
  "status": "OK",
  "metadata": {
    "modified_timestamp": <integer: unix timestamp of last modified time>,
    "size": null,
    "type": "folder"
  }
}

Copy a file or folder API

Use this API to asynchronously schedule to copy a file or folder.

Request

Initiate the operation to copy a file or a folder and its contents by sending a POST request to api_root/ROOT/SOURCE_FILE_OR_FOLDER_PATH/COPY with the request body encoded as JSON. where:

ROOT is the directory to invoke the Filesystem API
SOURCE_FILE_OR_FOLDER_PATH is the source file or folder path relative to ROOT

POST api_root/ROOT/SOURCE_FILE_OR_FOLDER_PATH/COPY

# body
{
  "new_full_path": <string>
}

The request body must be a JSON object with the following fields:

new_full_path:
- For a folder: the target folder path relative to ROOT
- For a file: the target file path relative to ROOT

Copy folder example (Python):

url = api_root + root + '/samples/folder-name-1' + '/copy'

data=dict(
  new_full_path=root + '/data/folder-name-1'
)

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Instabase-API-Args': json.dumps(api_args)
}

resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Copy file example (Python):

url = api_root + root + '/samples/file-name-1.pdf' + '/copy'

data=dict(
  new_full_path=root + '/data/file-name-1.pdf'
)

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

resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

If successfully scheduled:

HTTP STATUS CODE 200

{
  "status": "OK",
  "job_id": "identifier-representing-this-copy-execution"
}

The response body is a JSON object with the following fields:

status: "OK"
job_id: A unique identifier for the job executing the copy operation. To ensure that the operation is complete, use the Job Status API.

Move a file or folder API

Use this API to asynchronously schedule to move a file or folder.

Request

Initiate the operation to move a file or a folder and its contents by sending a POST request to api_root/ROOT/SOURCE_FILE_OR_FOLDER_PATH/MOVE with the request body encoded as JSON. where:

ROOT is the directory to invoke the Filesystem API
SOURCE_FILE_OR_FOLDER_PATH is the source file or folder path relative to ROOT

POST api_root/ROOT/SOURCE_FILE_OR_FOLDER_PATH/MOVE

# body
{
  "new_full_path": <string>
}

The request body must be a JSON object with the following fields:

new_full_path:
- For a folder: the target folder path relative to ROOT to move the folder.
- For a file: the target file path relative to ROOT to move the file.

Move folder example (Python):

url = api_root + root + '/samples/folder-name-1' + '/move'

data=dict(
  new_full_path=root + '/data/folder-name-1'
)

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

resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Move file example (Python):

url = api_root + root + '/samples/file-name-1.pdf' + '/move'

data=dict(
  new_full_path=root + '/data/file-name-1.pdf'
)

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

resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

If successfully scheduled:

HTTP STATUS CODE 200

{
  "status": "OK",
  "job_id": "identifier-representing-this-move-execution"
}

The response body is a JSON object with the following fields:

status: "OK"
job_id: A unique identifier for the job executing the copy operation. To ensure that the operation is complete, use the Job Status API.

Delete a folder API

Use this API to delete the specified folder.

Request

Delete a folder by sending a DELETE request to api_root/ROOT/FOLDER_PATH with the request body encoded as JSON. where:

ROOT is the directory to invoke the Filesystem API
FOLDER_PATH is the path of the folder to delete relative to ROOT

FILE_PATH refers to the path of the file to delete relative to ROOT

DELETE api_root/ROOT/FOLDER_PATH

# body
{
  "force": <boolean>
}

The request body must be a JSON object with the following fields:

force: (Optional) Whether to force delete the folder. Defaults to false.
false - Nonexistent folder will result in an error.
true - Nonexistent folder will not result in an error.
retry_config: (Optional) A dict that specifies the number of retries and backoff interval for retrying failed requests.

Example (Python):

url = api_root + root + '/a/b/c'

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

data=dict(
  force=True,
  retry_config=dict(num_retries=3, backoff_interval_sec=3),
)

resp = requests.delete(url, data=json.dumps(data), headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

{
  "status": "OK"
}

Delete a file API

Use this API to delete the specified file.

Request

Delete a file by sending a DELETE request to api_root/ROOT/FILE_PATH. where:

ROOT is the directory to invoke the Filesystem API
FILE_PATH is the path of the file to delete relative to ROOT

DELETE api_root/ROOT/FILE_PATH

# body
N/A

The request body must be a JSON object with the following fields:

force: (Optional) Whether to force delete the file. Defaults to false.
false - Nonexistent file will result in an error.
true - Nonexistent file will not result in an error.
retry_config: (Optional) A dict that specifies the number of retries and backoff interval for retrying failed requests.

Example (Python):

url = api_root + root + '/a/b/file.txt'
headers = {
  'Authorization': 'Bearer {0}'.format(token)
}
data=dict(
  force=True,
  retry_config=dict(num_retries=3, backoff_interval_sec=3),
)
resp = requests.delete(url, data=json.dumps(data), headers=headers).json()

Response

If successful:

HTTP STATUS CODE 200

{
  "status": "OK"
}

Extract a ZIP file API

Use this API to asynchronously schedule to extract a compressed file.

Request

Initiate the operation to extract the contents of a compressed file into a destination folder by sending a POST request to api_root/ROOT/FILE_PATH. where:

FILE_PATH is the path to the folder that contains the compressed (.zip) file

POST api_root/ROOT/FILE_PATH/UNZIP

# body
{
  "destination": <string>,
  "zip_file": <string>,
}

The request body must be a JSON object with the following fields:

destination: the full path to a directory to extract the contents of the ZIP file
zip_file: the filename of the zip file within the given file path

Example (Python):

url = api_root + root + '/path/to/zip/directory' + '/unzip'

data=dict(
  zip_file='my_archive.zip',
  destination=root + '/files/my_archive/'
)

api_args=dict(
  type='folder',
)

headers = {
  'Authorization': 'Bearer {0}'.format(token),
  'Instabase-API-Args': json.dumps(api_args)
}

resp = requests.post(url, headers=headers, data=json.dumps(data)).json()

Response

If successfully scheduled:

HTTP STATUS CODE 200

{
  "status": "OK",
  "job_id": "identifier-representing-this-move-execution"
}

The response body is a JSON object with the following fields:

status: "OK"
job_id: A unique identifier for the job executing the unzip operation. To ensure that the operation is complete, use the Job Status API.