Filesystem endpoint (Deprecated)
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
.
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>/
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
This request creates or replaces a file at the target path with a file containing the text “hello world”.
Response
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
This request uses the Range
header to read the first 5 bytes of the target file.
Response
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
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
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
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.
Examples
Request
Response
The deletion request has been accepted. You can check the status of the request at the URL provided in the Location
header.