Instabase Files API
The Files API from Instabase — 1 operation(s) for files.
OpenAPI Specification
openapi: 3.0.0
info:
title: AI Hub Audit Files API
version: '0.1'
description: The AI Hub REST API. See https://docs.instabase.com/api-sdk/ for more details.
termsOfService: https://www.instabase.com/terms-of-service/
contact:
name: Instabase Support
url: https://help.instabase.com/
license:
name: MIT
url: https://github.com/instabase/aihub-python/blob/master/LICENSE
servers:
- url: https://aihub.instabase.com/api
security:
- bearerAuth: []
tags:
- name: Files
paths:
/v2/files/{path}:
get:
operationId: readFile
x-fern-audiences:
- public
tags:
- Files
summary: Read file
description: 'Read contents from a file.
<Info>This acts on files in the AI Hub filesystem, not your local filesystem.</Info>
<Note>Ensure the path is accessible within the context defined by the `IB-Context` header.</Note>
'
parameters:
- in: path
name: path
required: true
schema:
type: string
description: Full path to the file.
- in: query
name: expect-node-type
required: true
schema:
type: string
enum:
- file
- folder
description: Type of node at the target path.
- $ref: '#/components/parameters/ib_context'
- in: header
name: Range
schema:
type: string
required: false
description: 'The portion of the file to read. A single HTTP byte range, with inclusive bounds and a non-negative start value. If not provided, return the entire file. Example: `bytes=0-4`
'
- in: header
name: IB-Retry-Config
schema:
type: string
required: false
description: 'Configures retry logic if no file is found at the target path. Uses a constant backoff algorithm. Don''t retry if this header isn''t provided. Example: `{retries:3,backoff-seconds:5}`
'
responses:
'200':
description: Indicates that the response contains the entire file contents.
content:
application/octet-stream:
schema:
type: string
format: binary
headers:
Content-Type:
schema:
type: string
default: application/octet-stream
Content-Length:
schema:
type: integer
format: int64
'206':
description: Indicates that only a portion of the file has been returned, as requested with the Range header.
content:
application/octet-stream:
schema:
type: string
format: binary
headers:
Content-Type:
schema:
type: string
default: application/octet-stream
Content-Length:
schema:
type: integer
format: int64
Content-Range:
schema:
type: string
description: An HTTP content range header. Contains a range representing the returned portion of the file.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
x-fern-examples:
- code-samples:
- sdk: curl
code: "curl \"${API_ROOT}/v2/files/<FILE-PATH>?expect-node-type=file\" \\\n -H \"Authorization: Bearer ${API_TOKEN}\" \\\n -H \"IB-Context: ${IB_CONTEXT}\"\n"
- sdk: python
name: Simple request with SDK
code: "from aihub import AIHub\n\nclient = AIHub(\n api_root=\"https://aihub.instabase.com/api\",\n api_key=\"abcdefghijklmnopqrst1234567890\",\n ib_context=\"john.doe_acme.com\"\n)\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"My Google Drive\"\nfolder = \"My Drive/AI Hub files\"\nfile_name = \"hello.txt\"\nfile_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\n\n# returns a byte literal, such as `b\"foo\"`\nfile_contents = client.files.read(path=file_path, expect_node_type=\"file\")\nprint(f\"Contents: {file_contents.decode('utf-8')}\")\n"
- sdk: python
name: Simple request without SDK
code: "import requests\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"My Google Drive\"\nfolder = \"My Drive/AI Hub files\"\nfile_name = \"hello.txt\"\nfile_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\n\nurl = f\"https://aihub.instabase.com/api/v2/files/{file_path}\"\n\nheaders = {\n \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# create query parameters\nparams = {\"expect-node-type\": \"file\"}\n\n# make the GET request\nresponse = requests.get(url, headers=headers, params=params)\n\n# handle the response\nif response.status_code == 200:\n print(f\"Contents: {response.content.decode('utf-8')}\")\nelse:\n print(f\"Error: {response.status_code} - {response.text}\")\n"
- sdk: python
name: Complex request with SDK
code: "from aihub import AIHub\n\nclient = AIHub(\n api_root=\"https://aihub.instabase.com/api\",\n api_key=\"abcdefghijklmnopqrst1234567890\",\n ib_context=\"john.doe_acme.com\"\n)\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"My Google Drive\"\nfolder = \"My Drive/AI Hub files\"\nfile_name = \"hello.txt\"\nfile_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\n\nretry_config = '{\"retries\": 3, \"backoff-seconds\": 5}'\n\n# returns a byte literal, such as `b\"foo\"`\nfile_contents = client.files.read(\n path=file_path,\n expect_node_type=\"file\",\n range=\"bytes=10-20\",\n ib_retry_config=retry_config\n)\nprint(f\"Contents: {file_contents.decode('utf-8')}\")\n"
- sdk: python
name: Complex request without SDK
code: "import requests\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"My Google Drive\"\nfolder = \"My Drive/AI Hub files\"\nfile_name = \"hello.txt\"\nfile_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\n\nbyte_range = \"bytes=10-20\"\nretry_config = '{\"retries\": 3, \"backoff-seconds\": 5}'\n\n# create query parameters\nparams = {\"expect-node-type\": \"file\"}\n\nurl = f\"https://aihub.instabase.com/api/v2/files/{file_path}\"\n\nheaders = {\n \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n \"IB-Context\": \"john.doe_acme.com\",\n \"Range\": byte_range,\n \"IB-Retry-Config\": retry_config\n}\n\n# make the GET request\nresponse = requests.get(url, headers=headers, params=params)\n\n# handle the response\n# 200 means whole content is returned\n# 206 means partial content is returned, due to \"Range\" parameter\nif response.status_code in [200, 206]:\n print(f\"Contents: {response.content.decode('utf-8')}\")\nelse:\n print(f\"Error: {response.status_code} - {response.text}\")\n"
put:
operationId: writeFile
x-fern-audiences:
- public
tags:
- Files
summary: Create or overwrite file
description: 'Create a non-empty file or overwrite an existing file.
If the parent folder of the `path` parameter doesn''t exist, the file system creates it before creating the file.
<Info>This acts on files in the AI Hub filesystem, not your local filesystem.</Info>
<Note>Ensure the path is accessible within the context defined by the `IB-Context` header.</Note>
Not all filesystem types support this operation.
| Filesystem | Supported |
|----------------------|-----------|
| Instabase | ✓ |
| Amazon S3 | ✓ |
| Azure Blob Storage | ✓ |
| Google Cloud Storage | ✓ |
| Google Drive | - |
'
parameters:
- in: path
name: path
required: true
schema:
type: string
description: Full path to the file.
- $ref: '#/components/parameters/ib_context'
requestBody:
required: true
content:
application/octet-stream:
schema:
description: The raw contents of the file to write.
type: string
format: binary
responses:
'201':
description: The request succeeded and a new file was created at the target location. AI Hub returns this status code only when the request includes an `If-None-Match` header with a value of `*`.
headers:
Location:
schema:
type: string
description: Contains a URL leading to the created file.
'204':
description: The request succeeded.
'412':
description: The request failed because a file exists at the target location that matches the `If-None-Match` header.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
x-fern-examples:
- code-samples:
- sdk: curl
code: "curl -X PUT \"${API_ROOT}/v2/files/<FILE-PATH>\" \\\n -H \"Authorization: Bearer ${API_TOKEN}\" \\\n -H \"IB-Context: ${IB_CONTEXT}\" \\\n -H \"Content-Type: application/octet-stream\" \\\n --data-binary \"@<LOCAL_FILEPATH>\"\n"
- sdk: python
name: with SDK
code: "from aihub import AIHub\n\nclient = AIHub(\n api_root=\"https://aihub.instabase.com/api\",\n api_key=\"abcdefghijklmnopqrst1234567890\",\n ib_context=\"john.doe_acme.com\"\n)\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"MyDrive\"\nfolder = \"MyFolder\"\nfile_name = \"hello.txt\"\nfile_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\nfile_contents = bytes(\"Hello world\", \"utf-8\")\n\n# returns None\nclient.files.write(path=file_path, data=file_contents)\n"
- sdk: python
name: without SDK
code: "import requests\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"MyDrive\"\nfolder = \"MyFolder\"\nfile_name = \"hello.txt\"\nfile_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\nfile_contents = bytes(\"Hello world\", \"utf-8\")\n\nurl = f\"https://aihub.instabase.com/api/v2/files/{file_path}\"\n\nheaders = {\n \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n \"IB-Context\": \"john.doe_acme.com\",\n \"Content-Type\": \"application/octet-stream\"\n}\n\n# make the PUT request\nresponse = requests.put(url, headers=headers, data=file_contents)\n\n# handle the response\nif response.status_code in [201, 204]:\n print(\"File written successfully\")\nelse:\n print(f\"Error: {response.status_code} - {response.text}\")\n"
head:
operationId: getFileMetadata
x-fern-audiences:
- public
tags:
- Files
summary: Read file or folder metadata
description: 'Read metadata of a file or folder at the target path.
This API operation reports whether the object at the target path is a file or folder. If a file, it also reports the file size and last modification time.
<Info>This acts on files and folders in the AI Hub filesystem, not your local filesystem.</Info>
<Note>Ensure the path is accessible within the context defined by the `IB-Context` header.</Note>
'
parameters:
- in: path
name: path
required: true
schema:
type: string
description: Full path to the file or folder.
- $ref: '#/components/parameters/ib_context'
- in: header
name: IB-Retry-Config
schema:
type: string
required: false
description: 'Configures retry logic if no file or folder is found at the target path. Uses a constant backoff algorithm. Don''t retry if this header isn''t provided. Example: `{''retries'': 3, ''backoff-seconds'': 5}`
'
responses:
'200':
description: Successfully retrieved metadata.
headers:
Content-Type:
schema:
type: string
description: Returns `application/json` if it is a folder and `application/octet-stream` if it is a file.
Content-Length:
schema:
type: integer
format: int64
description: Optional. Only present if the target path is a file. The length of the file, in bytes.
last-modified:
schema:
type: string
format: date-time
description: Optional. Only present if the target path is a file. The date and time the file was last modified.
'404':
description: No file or folder was found at the target path.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
x-fern-examples:
- code-samples:
- sdk: curl
code: "curl -I \"${API_ROOT}/v2/files/<FILE-PATH>\" \\\n -H \"Authorization: Bearer ${API_TOKEN}\" \\\n -H \"IB-Context: ${IB_CONTEXT}\"\n"
- sdk: python
name: with SDK
code: "from aihub import AIHub\n\nclient = AIHub(\n api_root=\"https://aihub.instabase.com/api\",\n api_key=\"abcdefghijklmnopqrst1234567890\",\n ib_context=\"john.doe_acme.com\"\n)\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"Instabase Drive\"\nfolder = \"MyFolder\"\nnode = \"hello.txt\"\nnode_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{node}\"\n\n# returns an object with status code and headers\nresponse = client.files.get_file_metadata(path=node_path)\n\nis_file = (response.headers[\"Content-Type\"] == \"application/octet-stream\")\nis_folder = (response.headers[\"Content-Type\"] == \"application/json\")\n\nif is_file:\n file_length = response.headers[\"Content-Length\"]\n last_modified = response.headers[\"last-modified\"]\n print(f\"Node is a file with length {file_length} and modification date {last_modified}\")\nelse:\n print(\"Node is a folder\")\n"
- sdk: python
name: without SDK
code: "import requests\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"Instabase Drive\"\nfolder = \"MyFolder\"\nfile_name = \"hello.txt\"\nnode_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\n\nurl = f\"https://aihub.instabase.com/api/v2/files/{node_path}\"\n\nheaders = {\n \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# make the HEAD request\nresponse = requests.head(url, headers=headers)\n\n# handle the response\nif response.status_code == 200:\n is_file = (response.headers[\"Content-Type\"] == \"application/octet-stream\")\n is_folder = (response.headers[\"Content-Type\"] == \"application/json\")\n\n if is_file:\n file_length = response.headers[\"Content-Length\"]\n last_modified = response.headers[\"last-modified\"]\n print(f\"Node is a file with length {file_length} and modification date {last_modified}\")\n else:\n print(\"Node is a folder\")\nelse:\n print(f\"Error: {response.status_code} - {response.text}\")\n"
delete:
operationId: deleteFileOrFolder
x-fern-audiences:
- public
tags:
- Files
summary: Delete file or folder
description: 'Delete a single file or folder.
This operation is also available via the SDK method `client.files.delete()`.
<Info>This acts on files in the AI Hub filesystem, not your local filesystem.</Info>
<Note>Ensure the path is accessible within the context defined by the `IB-Context` header.</Note>
Not all filesystem types support this operation.
| Filesystem | Supported |
|----------------------|-----------|
| Instabase | ✓ |
| Amazon S3 | ✓ |
| Azure Blob Storage | ✓ |
| Google Cloud Storage | ✓ |
| Google Drive | - |
'
parameters:
- in: path
name: path
required: true
schema:
type: string
description: Full path to the file or folder.
- $ref: '#/components/parameters/ib_context'
responses:
'202':
description: Indicates that the deletion request has been accepted. <br/> <Note>The operation returns this status code regardless of whether the file or folder exists.</Note>
headers:
Location:
schema:
type: string
description: A URL where the status of the deletion job can be checked.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
x-fern-examples:
- code-samples:
- sdk: curl
code: "curl -X DELETE \"${API_ROOT}/v2/files/<FILE-PATH>\" \\\n -H \"Authorization: Bearer ${API_TOKEN}\" \\\n -H \"IB-Context: ${IB_CONTEXT}\"\n"
- sdk: python
name: Delete file with SDK
code: "from aihub import AIHub\n\nclient = AIHub(\n api_root=\"https://aihub.instabase.com/api\",\n api_key=\"abcdefghijklmnopqrst1234567890\",\n ib_context=\"john.doe_acme.com\"\n)\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"Instabase Drive\"\nfolder = \"my-folder\"\nfile_name = \"hello.txt\"\nfile_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\n\n# returns None\nclient.files.delete(path=file_path)\n"
- sdk: python
name: Delete file without SDK
code: "import requests\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"Instabase Drive\"\nfolder = \"my-folder\"\nfile_name = \"hello.txt\"\nfile_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}/{file_name}\"\n\nurl = f\"https://aihub.instabase.com/api/v2/files/{file_path}\"\n\nheaders = {\n \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# make the DELETE request\nresponse = requests.delete(url, headers=headers)\n\n# handle the response\nif response.status_code == 202:\n print(\"File deletion request accepted\")\nelse:\n print(f\"Error: {response.status_code} - {response.text}\")\n"
- sdk: python
name: Delete folder with SDK
code: "from aihub import AIHub\n\nclient = AIHub(\n api_root=\"https://aihub.instabase.com/api\",\n api_key=\"abcdefghijklmnopqrst1234567890\",\n ib_context=\"john.doe_acme.com\"\n)\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"Instabase Drive\"\nfolder = \"MyFolder\"\nfolder_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}\"\n\n# returns None\nclient.files.delete(path=folder_path)\n"
- sdk: python
name: Delete folder without SDK
code: "import requests\n\norganization_id = \"acme_org\"\nworkspace = \"MyWorkspace\"\ndrive = \"Instabase Drive\"\nfolder = \"MyFolder\"\nfolder_path = f\"{organization_id}/{workspace}/fs/{drive}/{folder}\"\n\nurl = f\"https://aihub.instabase.com/api/v2/files/{folder_path}\"\n\nheaders = {\n \"Authorization\": \"Bearer abcdefghijklmnopqrst1234567890\",\n \"IB-Context\": \"john.doe_acme.com\"\n}\n\n# make the DELETE request\nresponse = requests.delete(url, headers=headers)\n\n# handle the response\nif response.status_code == 202:\n print(\"Folder deletion request accepted\")\nelse:\n print(f\"Error: {response.status_code} - {response.text}\")\n"
components:
parameters:
ib_context:
in: header
name: IB-Context
schema:
type: string
required: false
description: Specify whether to use your community account or organization account to complete the request. To use your community account, define as your user ID. To use your organization account, define as your organization ID. If unspecified, defaults to community account context. See [Authorization and context identification](/api-sdk/authorization#ib-context-header) for details.
schemas:
error:
type: object
properties:
message:
type: string
securitySchemes:
bearerAuth:
bearerFormat: auth-scheme
description: Bearer HTTP authentication.
scheme: bearer
type: http