Filesystem endpoint (Deprecated)

Warning

The Batches endpoint offers a simpler way to create and manage a set of input files. Filesystem operations are still supported, but batches are the preferred approach. This article remains available for reference but might not be actively maintained.

Table of Contents

The Filesystem API allows you to perform common file operations in Instabase and AI Hub, including reading, writing, and deleting files.

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

import json, requests

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

To make calls to AI Hub APIs, you must define your API token and send it with your requests. <API_TOKEN> in the following examples refers to your API token.

You can generate and manage API tokens from your AI Hub user settings. See the authorization documentation for details. See authorization for details about API tokens for AI Hub.

Note

File paths are formatted as follows:

For Community accounts:

Instabase Drive: /<USER-ID>/my-repo/fs/Instabase Drive/<INPUT_FOLDER>/
External drive: /<USER-ID>/my-repo/fs/<DRIVE-NAME>/<INPUT_FOLDER>/

You can find your user ID on the APIs settings page.

For Commercial accounts:

Instabase Drive: /<ORGANIZATION-ID>/<WORKSPACE>/fs/Instabase Drive/<INPUT_FOLDER>/
External drives: /<ORGANIZATION-ID>/<WORKSPACE>/fs/<DRIVE-NAME>/<INPUT_FOLDER>/

Supported external drives include:

Google Drive. For , provide the drive’s AI Hub display name, not the name defined in Google Drive. Enter the exact display name, including any spaces.
Commercial Amazon S3 bucket. For , provide the drive’s AI Hub display name, not the S3 bucket name. Enter the exact display name, including any spaces.
Commercial Azure Blob storage. For , provide the drive’s AI Hub display name, not the Azure Blob storage container name. Enter the exact display name, including any spaces.

You can find your organization ID on the APIs settings page. All workspaces that you can access and their connected drives are listed in the My Hub tab.

Create a non-empty file or overwrite a file

Method	Syntax
PUT	`API_ROOT/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/<DRIVE-NAME>/<PATH>`

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

Name	Description	Values
`If-None-Match`	Optional. Requires the request to fail if a file already exists at the target location.	If provided, its value must be `*`.

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.

Status	Meaning
201 Created	The request succeeded and a new file was created at the target location. This status code is only returned when `If-None-Match` is specified `*` in the header
204 No Content	The request succeeded.
412 Precondition Failed	The request failed because a file existed at the target location that matched the `If-None-Match` header.

Response headers

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

Name	Description	Values
`Location`	Optional. Present if the response status is 201 Created.	Contains a URL leading to the created file.

Examples

Request

import requests

url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/new_file.txt'

headers = {
  'Authorization': f'Bearer {API_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

Read a file

Method	Syntax
GET	`API_ROOT/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/<DRIVE-NAME>/<PATH>`

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.

Name	Description
`expect-node-type`	Specifies the type of the node at the target path. The target node must match the specified type. To read from a file, must be set to `file`.

Request headers

Name	Description	Values
`Range`	Optional. Allows specifying a portion of the file to be read.	If specified, must be an HTTP byte range (HTTP byte ranges have inclusive bounds). Must contain only a single range. Cannot contain a range with a negative start value. If this header is not provided, the entire file is returned.
`IB-Retry-Config`	Optional. If no file is found at the target path at first, the server waits and tries again based on the information in this header before sending a response.	Value takes the form `{retries:RETRIES,backoff-seconds:BACKOFF_SECONDS}`. Replace `RETRIES` with an integer greater than 0, and `BACKOFF_SECONDS` with an integer greater than 0. If this header is not provided, the operation is not retried. Uses a constant backoff algorithm using the specified `backoff-seconds` quantity.

Request body

This request contains no body.

Response status

A 2XX status code indicates the request was successful.

Status	Meaning
200 OK	Indicates that the response contains the entire file contents.
206 Partial Content	Indicates that only a portion of the file has been returned, as requested with the `Range` header.

Response headers

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

Name	Description	Values
`Content-Type`	The content type of the response body.	When reading a file, the content type is `application/octet-stream`.
`Content-Length`	The length, in bytes, of the response body.	An integer greater than or equal to 0.
`Content-Range`	Optional. Present only if the status is 206 Partial Content. An HTTP content range header.	Contains a range representing the returned portion of the file.

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 + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/hello_world.txt'
params = {'expect-node-type':'file'}
headers = {
  'Authorization': f'Bearer {API_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

Method	Syntax
HEAD	`API_ROOT/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/<DRIVE-NAME>/<PATH>`

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

Name	Description	Values
`IB-Retry-Config`	Optional. If no file or folder is found at first, the server waits and tries again based on the information in this header before sending a response.	Value takes the form `{retries:RETRIES,backoff-seconds:BACKOFF_SECONDS}`. Replace `RETRIES` with an integer greater than 0, and `BACKOFF_SECONDS` with an integer greater than 0. If this header is not provided, the operation is not retried. Uses a constant backoff algorithm using the specified `backoff-seconds` quantity.

Request body

The request does not have a body.

Response status

A 2XX status code indicates the request was successful.

Status	Meaning
404 Not Found	No file or folder was found at the target path.

Response headers

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

Name	Description	Values
`Content-Type`	The content type of the targeted path. Indicates whether it is a file or a folder.	`application/json` if it is a folder, `application/octet-stream` if it is a file.
`Content-Length`	Optional. Only present if the target path is a file. The length of the file, in bytes.	A decimal integer greater than or equal to 0.
`Last-Modified`	Optional. Only present if the target path is a file. The date and time the file was last modified.	An HTTP-formatted date.

Response schema

The response does not have a body.

Examples

Request

url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/file.txt'

headers = {
  'Authorization': f'Bearer {API_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.

Delete a file or folder

Method	Syntax
DELETE	`API_ROOT/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/<DRIVE-NAME>/<PATH>`

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.

Status	Meaning
202 Accepted	Indicates that the deletion request has been accepted.

Response headers

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

Name	Description	Values
`Location`	Optional. Present if the status is 202 Accepted.	A URL where the status of the deletion job can be checked.

Examples

Request

url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/file.txt'

headers = {
  'Authorization': f'Bearer {API_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. You can check the status of the request at the URL provided in the Location header.