Mount endpoint

Use the Mount endpoint to connect external drives to a workspace on AI Hub, such as an Amazon S3 bucket or Azure Blob Storage container. This endpoint doesn’t support mounting organization drives. To mount organization drives, use the AI Hub UI.

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/v1/drives.

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

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.

Mount paths

Use the mount path to specify the workspace in which to mount the drive. The format of the mount path varies if you have a community or organization account.

  • Community accounts: /<USER-ID>/my-repo/fs

  • Organization accounts: /<ORGANIZATION-ID>/<WORKSPACE>/fs

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

Mount drive

MethodSyntax
POSTAPI_ROOT/<MOUNT-PATH>

Description

Mount a drive by sending a POST request to API_ROOT/<MOUNT-PATH>, specifying the workspace in which to connect the drive using MOUNT-PATH in the request URL.

Request headers

NameTypeDescriptionValues
actionstringString describing the action to be taken.Valid values are : [mount].
mount_point_namestringThe name of the mounted drive.A valid name of a drive in the specified workspace.
mount_detailsJSONDetails of drive to mount that varies according to drive type.See section below for valid values for each drive type.

Amazon S3 bucket mount details

Mounting Amazon S3 buckets is supported for organization accounts. For an S3 bucket, provide mount details in the following structure:

1'mount_details': {
2 'client_type': 'S3',
3 'prefix': '<Path to mount (ex: files/data)>' ,
4 's3_server_url': '<S3 Server URL>',
5 's3_server_port': '<S3 Server Port>',
6 's3_server_is_secure': 'True' | 'False',
7 's3_server_validate_certs': 'True' | 'False',
8 'use_aws_access_creds': True | False,
9 'aws_access_key_id': '<AWS access key>', # Optional, use if 'use_aws_access_creds' is set to True
10 'aws_secret_access_key': '<AWS secret access key>', # Optional, use if 'use_aws_access_creds' is set to True
11 'bucket_name': '<AWS S3 Bucket Name>',
12 'aws_region': 'AWS Region (ex: us-east-1)',
13 'encryption_type': 'none' | 'kms_encryption',
14 's3_sse_encryption_type': 'none' | 'aws_sse_s3' | 'aws_sse_kms',
15 's3_sse_kms_key_id': '<S3 SSE KMS key ID>', # Optional, use if 's3_sse_encryption_type' is set to 'aws_sse_kms'
16 's3_use_virtual_style_url': True | False,
17 'use_hcp_s3_storage': True | False,
18 'mount_permissions': '{"access_level":"writer"}' | '{"access_level":"reader"}'
19}
If s3_sse_encryption_type is set to aws_sse_kms, define the Amazon resource name (ARN) for the KMS key in s3_sse_kms_key_id. For example, 'arn:aws:kms:us-west-2:123456789012:key/abcd1234-5678-90ab-cdef-EXAMPLE11111'. See the AWS Finding the key ID and key ARN documentation for additional information.

Azure Blob Storage mount details

Mounting Amazon S3 buckets is supported for organization accounts. Azure Blob Storage drives can be mounted with a connection string or a service principal as the authentication type.

If mounting an Azure Blob Storage container with a connection string, provide mount details in the following structure:

1'mount_details': {
2 'client_type': 'AzureBlob',
3 'az_blob_store_auth_type': 'connection_string', # Defaults to 'connection_string' if left empty
4 'azure_container_name': '<Azure Blob Storage container name>',
5 'azure_connect_str': '<Azure storage account connection string>'
6 'mount_permissions': '{"access_level":"reader"}' | '{"access_level":"writer"}'
7}

See the following sample connection string structure for an Azure storage account with default configurations. Connection strings can embed a different subset of fields:

1'DefaultEndpointsProtocol=[http|https];AccountName=myAccountName;AccountKey=myAccountKey;EndpointSuffix=[core.windows.net]'

If mounting an Azure Blob Storage container with a service principal, provide mount details in the following structure:

1'mount_details': {
2 'client_type': 'AzureBlob',
3 'az_blob_store_auth_type': 'service_principal', # Defaults to 'connection_string' if left empty
4 'azure_container_name': '<Azure Blob Storage container name>',
5 'az_blob_store_client_id': '<Azure storage account client ID>',
6 'az_blob_store_tenant_id': '<Azure storage account tenant ID>',
7 'az_blob_store_client_secret': '<Azure storage account client secret'>,
8 'az_blob_store_service_url': '<Azure storage account service URL'>,
9 'mount_permissions': '{"access_level":"reader"}' | '{"access_level":"writer"}'
10}

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.

Response headers

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

NameDescriptionValues
Content-TypeThe content type of the response body.application/json
Content-LengthThe length, in bytes, of the response body.An integer greater than or equal to 0.

Response schema

All keys are returned in the response by default, unless marked as optional.

KeyDescriptionValue
statusStatus of request.OK, ERROR
msgOptional. Job status message if status is ERROR.

Examples

Request

1import json, requests
2
3headers = {
4 'Authorization': f'Bearer {API_TOKEN}',
5}
6args = {
7 'action':'mount',
8 'mount_point_name': 'azure-blob-mount-point',
9 'mount_details': {
10 'client_type': 'AzureBlob',
11 'az_blob_store_auth_type': 'connection_string',
12 'azure_container_name': '<Azure Blob Storage container name>',
13 'azure_connect_str': '<Azure storage account connection string>'
14 'mount_permissions': '{"access_level":"reader"}' | '{"access_level":"writer"}'
15 }
16}
17data = json.dumps(args)
18resp = requests.post(api_root + '<MOUNT-PATH>',
19 headers=headers, data=data).json()

This request creates an Azure Blob Storage drive with the name azure-blob-mount-point.

Response

$HTTP STATUS CODE 200
>
>{
> "status": "OK"
>}

Update drive credentials

MethodSyntax
PUTAPI_ROOT/<MOUNT-PATH>

Description

Update a drive’s credentials by sending a PUT request to API_ROOT/<MOUNT-PATH>, specifying the workspace in which the drive is connected using MOUNT-PATH in the request URL.

Request headers

NameTypeDescriptionValues
mount_point_namestringThe name of the mounted driveA valid name of a mounted drive in the specified workspace.
mount_detailsJSONNew credentials of the mounted driveSee section below for valid values for each drive type.
This endpoint can’t be used to update non-credential fields in the mount_details object. See the following examples for supported fields.

For an S3 bucket, you can update the following drive credentials fields:

1'mount_details': {
2 'aws_access_key_id': '<AWS access key>', # If 'use_aws_access_creds' is set to True
3 'aws_secret_access_key': '<AWS secret access key>', # If 'use_aws_access_creds' is set to True
4}

For Azure Blob Storage drives mounted with a connection string, you can update the following drive credentials fields:

1'mount_details': {
2 'azure_connect_str': '<Azure storage account connection string>',
3}

For Azure Blob Storage drives mounted with a service principal, you can update the following drive credentials fields:

1'mount_details': {
2 'az_blob_store_client_id': '<Azure storage account client ID>',
3 'az_blob_store_tenant_id': '<Azure storage account tenant ID>',
4 'az_blob_store_client_secret': '<Azure storage account client secret>',
5 'az_blob_store_service_url': '<Azure storage account service URL>',
6}

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.

Response headers

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

NameDescriptionValues
Content-TypeThe content type of the response body.application/json
Content-LengthThe length, in bytes, of the response body.An integer greater than or equal to 0.

Response schema

All keys are returned in the response by default, unless marked as optional.

KeyDescriptionValue
statusStatus of request.OK, ERROR
msgOptional. Job status message if status is ERROR.

Examples

Request

1import json, requests
2
3headers = {
4 'Authorization': f'Bearer {API_TOKEN}',
5}
6args = {
7 {
8 "mount_point_name": "azure-blob-mount-point",
9 "mount_details": {
10 'azure_connect_str': '<Azure storage account connection string>',
11 }
12 }
13}
14data = json.dumps(args)
15resp = requests.put(api_root + '<MOUNT-PATH>', headers=headers, data=data).json()

This request updates the connection string of the existing Azure Blob Storage drive “azure-blob-mount-point”.

Response

If the drive credentials were successfully updated:

$HTTP STATUS CODE 200
>
>{
> "status": "OK"
>}

Unmount drive

MethodSyntax
DELETEAPI_ROOT/<MOUNT-PATH>

Description

Remove a mounted drive by sending a DELETE request to API_ROOT/<MOUNT-PATH>, specifying the workspace in which the drive is connected using MOUNT-PATH in the request URL.

Request headers

NameTypeDescriptionValues
namestringThe name of the mounted driveA valid name of a mounted drive in the specified workspace.

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.

Response headers

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

NameDescriptionValues
Content-TypeThe content type of the response body.application/json
Content-LengthThe length, in bytes, of the response body.An integer greater than or equal to 0.

Response schema

All keys are returned in the response by default, unless marked as optional.

KeyDescriptionValue
statusStatus of request.OK, ERROR
msgOptional. Job status message if status is ERROR.

Examples

Request

1import json, requests
2
3headers = {
4 'Authorization': f'Bearer {API_TOKEN}',
5}
6args = {
7 'name': '<drive name>'
8}
9data = json.dumps(args)
10resp = requests.delete(api_root + '<MOUNT-PATH>', headers=headers, data=data).json()

Response

If the credentials to the drive was successfully unmounted:

$HTTP STATUS CODE 200
>
>{
> "status": "OK"
>}
Was this page helpful?