Filesystem — Instabase Documentation

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.

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.

1 import json, requests
2 
3 url_base = "https://aihub.instabase.com"
4 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.

File paths

The format of the file path varies if you have a community or organization account.

Community accounts: /<USER-ID>/my-repo/fs/<DRIVE-NAME>/<INPUT-FOLDER>/
Organization accounts: /<ORGANIZATION-ID>/<WORKSPACE>/fs/<DRIVE-NAME>/<INPUT-FOLDER>/

Value	Description
`<USER-ID>`	Enter your user ID. You can find this on the Settings > APIs page, under User ID.
`<ORGANIZATION-ID>`	Enter your organization ID. You can find this on the Settings > APIs page, under Organization ID.
`<WORKSPACE>`	This value reflects the workspace name (shared workspaces) or your user ID (personal workspaces). You can find this value by selecting the workspace in Workspaces, then looking at the `workspace` query string in the URL. For example: - `https://aihub.instabase.com/workspaces/create?workspace=New_Workspace` - `https://aihub.instabase.com/workspaces/create?workspace=john.doe_gmail.com`
`<DRIVE-NAME>`	Use the drive’s display name. You can see a drive’s display name by opening the Data Sources panel in a workspace where the drive is connected. For example, the Instabase Drive’s display name is `Instabase Drive`.
`<INPUT-FOLDER>`	Use the exact name of the folder, as displayed in the filesystem.

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

1 import requests
2 
3 url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/new_file.txt'
4 
5 headers = {
6   'Authorization': f'Bearer {API_TOKEN}'
7 }
8 
9 data = bytes('hello world', 'utf-8')
10 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

1 url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/hello_world.txt'
2 params = {'expect-node-type':'file'}
3 headers = {
4   'Authorization': f'Bearer {API_TOKEN}',
5   'Range': 'bytes=0-4'
6 }
7 
8 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

1 url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/file.txt'
2 
3 headers = {
4   'Authorization': f'Bearer {API_TOKEN}',
5   'IB-Retry-Config' : json.dumps({
6     'retries' : 2,
7     'backoff-seconds' : 1
8   })
9 }
10 
11 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

1 url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/file.txt'
2 
3 headers = {
4   'Authorization': f'Bearer {API_TOKEN}'
5 }
6 
7 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.

1	import json, requests
2
3	url_base = "https://aihub.instabase.com"
4	api_root = url_base + '/api/v2/files'

1	import requests
2
3	url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/new_file.txt'
4
5	headers = {
6	'Authorization': f'Bearer {API_TOKEN}'
7	}
8
9	data = bytes('hello world', 'utf-8')
10	resp = requests.put(url, headers=headers, data=data)

1	url = api_root + '/<ORGANIZATION-ID>/<USER-ID> or <WORKSPACE>/fs/Instabase Drive/hello_world.txt'
2	params = {'expect-node-type':'file'}
3	headers = {
4	'Authorization': f'Bearer {API_TOKEN}',
5	'Range': 'bytes=0-4'
6	}
7
8	r = requests.get(url, headers=headers, params=params)