Filesystem endpoint (Deprecated)

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 page remains temporarily available for reference but is not actively maintained.

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.

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

ValueDescription
<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

MethodSyntax
PUTAPI_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

NameDescriptionValues
If-None-MatchOptional. 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.

StatusMeaning
201 CreatedThe 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 ContentThe request succeeded.
412 Precondition FailedThe 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.

NameDescriptionValues
LocationOptional. Present if the response status is 201 Created.Contains a URL leading to the created file.

Examples

Request

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

MethodSyntax
GETAPI_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.

NameDescription
expect-node-typeSpecifies 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

NameDescriptionValues
RangeOptional. 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-ConfigOptional. 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.

StatusMeaning
200 OKIndicates that the response contains the entire file contents.
206 Partial ContentIndicates 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.

NameDescriptionValues
Content-TypeThe content type of the response body.When reading a file, the content type is application/octet-stream.
Content-LengthThe length, in bytes, of the response body.An integer greater than or equal to 0.
Content-RangeOptional. 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

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

MethodSyntax
HEADAPI_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

NameDescriptionValues
IB-Retry-ConfigOptional. 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.

StatusMeaning
404 Not FoundNo file or folder was found at the target path.

Response headers

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

NameDescriptionValues
Content-TypeThe 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-LengthOptional. 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-ModifiedOptional. 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

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

MethodSyntax
DELETEAPI_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.

StatusMeaning
202 AcceptedIndicates that the deletion request has been accepted.

Response headers

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

NameDescriptionValues
LocationOptional. Present if the status is 202 Accepted.A URL where the status of the deletion job can be checked.

Examples

Request

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

Was this page helpful?