Object Storage

The object storage endpoints handle operations on objects stored in buckets, providing core functionality for managing files and data in SmartBuckets. This service enables direct interaction with stored objects through simple CRUD operations.

POST /v1/put_object

Upload a file to a SmartBucket or regular bucket. The bucket parameter (ID) is used to identify the bucket to upload to. The key is the path to the object in the bucket.

Schema Reference

Request

Request Body

key (string) Required

Details

Description

Object key/path in the bucket

Example

my-key

content (string) Required

Details

Description

Binary content of the object

contentType (string) Required

Details

Description

MIME type of the object

Example

application/pdf

bucketLocation (object) Required

Details

Description

The buckets to search. If provided, the search will only return results from these buckets

Example

{
  "bucket": {
    "name": "my-smartbucket",
    "version": "01jxanr45haeswhay4n0q8340y",
    "application_name": "my-app"
  }
}

Response

bucket (object)

Details

Description

Information about the bucket where the object was uploaded

Example

{
  "moduleId": "01jt3vs2nyt2xwk2f54x2bkn84"
}

key (string)

Details

Description

Key/path of the uploaded object

Example

test-object.txt

code (string)

Details

Description

Status codes and their meanings:

Code	Number	Description
OK	0	No error occurred.
CANCELLED	1	The operation was cancelled, typically by the caller.
UNKNOWN	2	Unknown error. Usually means a server error not mapped to a known code.
INVALID_ARGUMENT	3	Client specified an invalid argument.
DEADLINE_EXCEEDED	4	Deadline expired before operation could complete.
NOT_FOUND	5	Requested entity was not found.
ALREADY_EXISTS	6	Entity that a client attempted to create already exists.
PERMISSION_DENIED	7	Caller doesn’t have permission.
RESOURCE_EXHAUSTED	8	Some resource has been exhausted (e.g., quota, memory).
FAILED_PRECONDITION	9	Operation rejected because system not in required state.
ABORTED	10	Operation aborted, usually due to concurrency issues.
OUT_OF_RANGE	11	Argument out of acceptable range.
UNIMPLEMENTED	12	Operation not implemented or supported.
INTERNAL	13	Internal error.
UNAVAILABLE	14	Service is currently unavailable.
DATA_LOSS	15	Unrecoverable data loss or corruption.
UNAUTHENTICATED	16	Request does not have valid authentication credentials.

JavaScript

import Raindrop from '@liquidmetal-ai/lm-raindrop';

const client = new Raindrop();

const response = await client.bucket.put({
  bucketLocation: { bucket: { name: 'my-smartbucket' } },
  content: 'U3RhaW5sZXNzIHJvY2tz',
  contentType: 'application/pdf',
  key: 'my-key',
});

console.log(response.bucket);

Python

from raindrop import Raindrop

client = Raindrop()
response = client.bucket.put(
    bucket_location={
        "bucket": {
            "name": "my-smartbucket"
        }
    },
    content="U3RhaW5sZXNzIHJvY2tz",
    content_type="application/pdf",
    key="my-key",
)
print(response.bucket)

Go

package main

import (
  "context"
  "fmt"

  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk"
  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk/option"
)

func main() {
  client := raindrop.NewClient(
    option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("RAINDROP_API_KEY")
  )
  response, err := client.Bucket.Put(context.TODO(), raindrop.BucketPutParams{
    BucketLocation: raindrop.BucketLocatorUnionParam{
      OfBucket: &raindrop.BucketLocatorBucketParam{
        Bucket: raindrop.BucketLocatorBucketBucketParam{
          Name: "my-smartbucket",
        },
      },
    },
    Content: "U3RhaW5sZXNzIHJvY2tz",
    ContentType: "application/pdf",
    Key: "my-key",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Bucket)
}

Java

package com.raindrop.api.example;

import com.raindrop.api.client.RaindropClient;
import com.raindrop.api.client.okhttp.RaindropOkHttpClient;
import com.raindrop.api.models.bucket.BucketPutParams;
import com.raindrop.api.models.bucket.BucketPutResponse;
import com.raindrop.api.models.query.BucketLocator;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        // Configures using the `RAINDROP_API_KEY` and `RAINDROP_BASE_URL` environment variables
        RaindropClient client = RaindropOkHttpClient.fromEnv();

        BucketPutParams params = BucketPutParams.builder()
            .bucketLocation(BucketLocator.Bucket.builder()
                .bucket(BucketLocator.Bucket.InnerBucket.builder()
                    .name("my-bucket")
                    .build())
                .build())
            .content("U3RhaW5sZXNzIHJvY2tz")
            .contentType("application/pdf")
            .key("my-key")
            .build();
        BucketPutResponse response = client.bucket().put(params);
    }
}

CLI

# Upload a file to a bucket
npx raindrop object put ./myfile.txt my-key -b my-bucket

# Upload with specific content type
npx raindrop object put ./myfile.json my-key -b my-bucket --content-type application/json

curl

curl -X POST "https://api.raindrop.run/v1/put_object" \
  -H "Authorization: Bearer lm_apikey_..." \
  -H "Content-Type: application/json" \
  -d '{
  "key": "my-key",
  "content": "example",
  "content_type": "application/pdf",
  "bucket_location": {
    "bucket": {
      "name": "my-smartbucket",
      "version": "01jxanr45haeswhay4n0q8340y",
      "application_name": "my-app"
    }
  }
}'

Response Examples

200

{
  "bucket": {
    "moduleId": "01jt3vs2nyt2xwk2f54x2bkn84"
  },
  "key": "test-object.txt"
}

---

POST /v1/get_object

Download a file from a SmartBucket or regular bucket. The bucket parameter (ID) is used to identify the bucket to download from. The key is the path to the object in the bucket.

Schema Reference

Request

Request Body

key (string) Required

Details

Description

Object key/path to download

Example

my-key

bucketLocation (object) Required

Details

Description

The buckets to search. If provided, the search will only return results from these buckets

Example

{
  "bucket": {
    "name": "my-smartbucket",
    "version": "01jxanr45haeswhay4n0q8340y",
    "application_name": "my-app"
  }
}

Response

content (string)

Details

Description

No specific comments in original for these fields directly, but they were part of the original GetObjectResponse.

contentType (string)

Details

code (string)

Details

Description

Status codes and their meanings:

Code	Number	Description
OK	0	No error occurred.
CANCELLED	1	The operation was cancelled, typically by the caller.
UNKNOWN	2	Unknown error. Usually means a server error not mapped to a known code.
INVALID_ARGUMENT	3	Client specified an invalid argument.
DEADLINE_EXCEEDED	4	Deadline expired before operation could complete.
NOT_FOUND	5	Requested entity was not found.
ALREADY_EXISTS	6	Entity that a client attempted to create already exists.
PERMISSION_DENIED	7	Caller doesn’t have permission.
RESOURCE_EXHAUSTED	8	Some resource has been exhausted (e.g., quota, memory).
FAILED_PRECONDITION	9	Operation rejected because system not in required state.
ABORTED	10	Operation aborted, usually due to concurrency issues.
OUT_OF_RANGE	11	Argument out of acceptable range.
UNIMPLEMENTED	12	Operation not implemented or supported.
INTERNAL	13	Internal error.
UNAVAILABLE	14	Service is currently unavailable.
DATA_LOSS	15	Unrecoverable data loss or corruption.
UNAUTHENTICATED	16	Request does not have valid authentication credentials.

JavaScript

import Raindrop from '@liquidmetal-ai/lm-raindrop';

const client = new Raindrop();

const bucket = await client.bucket.get({
  bucketLocation: { bucket: { name: 'my-smartbucket' } },
  key: 'my-key',
});

console.log(bucket.content);

Python

from raindrop import Raindrop

client = Raindrop()
bucket = client.bucket.get(
    bucket_location={
        "bucket": {
            "name": "my-smartbucket"
        }
    },
    key="my-key",
)
print(bucket.content)

Go

package main

import (
  "context"
  "fmt"

  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk"
  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk/option"
)

func main() {
  client := raindrop.NewClient(
    option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("RAINDROP_API_KEY")
  )
  bucket, err := client.Bucket.Get(context.TODO(), raindrop.BucketGetParams{
    BucketLocation: raindrop.BucketLocatorUnionParam{
      OfBucket: &raindrop.BucketLocatorBucketParam{
        Bucket: raindrop.BucketLocatorBucketBucketParam{
          Name: "my-smartbucket",
        },
      },
    },
    Key: "my-key",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", bucket.Content)
}

Java

package com.raindrop.api.example;

import com.raindrop.api.client.RaindropClient;
import com.raindrop.api.client.okhttp.RaindropOkHttpClient;
import com.raindrop.api.models.bucket.BucketGetParams;
import com.raindrop.api.models.bucket.BucketGetResponse;
import com.raindrop.api.models.query.BucketLocator;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        // Configures using the `RAINDROP_API_KEY` and `RAINDROP_BASE_URL` environment variables
        RaindropClient client = RaindropOkHttpClient.fromEnv();

        BucketGetParams params = BucketGetParams.builder()
            .bucketLocation(BucketLocator.Bucket.builder()
                .bucket(BucketLocator.Bucket.InnerBucket.builder()
                    .name("my-bucket")
                    .build())
                .build())
            .key("my-key")
            .build();
        BucketGetResponse bucket = client.bucket().get(params);
    }
}

CLI

# Download a file from a bucket
npx raindrop object get my-key -b my-bucket

# Download to specific output file
npx raindrop object get my-key output.txt -b my-bucket

# Output to stdout
npx raindrop object get my-key -b my-bucket --format stdout

curl

curl -X POST "https://api.raindrop.run/v1/get_object" \
  -H "Authorization: Bearer lm_apikey_..." \
  -H "Content-Type: application/json" \
  -d '{
  "key": "my-key",
  "bucket_location": {
    "bucket": {
      "name": "my-smartbucket",
      "version": "01jxanr45haeswhay4n0q8340y",
      "application_name": "my-app"
    }
  }
}'

Response Examples

200

{
  "content": "example",
  "contentType": "example"
}

---

POST /v1/delete_object

Delete a file from a SmartBucket or regular bucket. The bucket parameter (ID) is used to identify the bucket to delete from. The key is the path to the object in the bucket.

Schema Reference

Request

Request Body

key (string) Required

Details

Description

Object key/path to delete

Example

my-key

bucketLocation (object) Required

Details

Description

The buckets to search. If provided, the search will only return results from these buckets

Example

{
  "bucket": {
    "name": "my-smartbucket",
    "version": "01jxanr45haeswhay4n0q8340y",
    "application_name": "my-app"
  }
}

Response

code (string)

Details

Description

Status codes and their meanings:

Code	Number	Description
OK	0	No error occurred.
CANCELLED	1	The operation was cancelled, typically by the caller.
UNKNOWN	2	Unknown error. Usually means a server error not mapped to a known code.
INVALID_ARGUMENT	3	Client specified an invalid argument.
DEADLINE_EXCEEDED	4	Deadline expired before operation could complete.
NOT_FOUND	5	Requested entity was not found.
ALREADY_EXISTS	6	Entity that a client attempted to create already exists.
PERMISSION_DENIED	7	Caller doesn’t have permission.
RESOURCE_EXHAUSTED	8	Some resource has been exhausted (e.g., quota, memory).
FAILED_PRECONDITION	9	Operation rejected because system not in required state.
ABORTED	10	Operation aborted, usually due to concurrency issues.
OUT_OF_RANGE	11	Argument out of acceptable range.
UNIMPLEMENTED	12	Operation not implemented or supported.
INTERNAL	13	Internal error.
UNAVAILABLE	14	Service is currently unavailable.
DATA_LOSS	15	Unrecoverable data loss or corruption.
UNAUTHENTICATED	16	Request does not have valid authentication credentials.

JavaScript

import Raindrop from '@liquidmetal-ai/lm-raindrop';

const client = new Raindrop();

const bucket = await client.bucket.delete({
  bucketLocation: { bucket: { name: 'my-smartbucket' } },
  key: 'my-key',
});

console.log(bucket);

Python

from raindrop import Raindrop

client = Raindrop()
bucket = client.bucket.delete(
    bucket_location={
        "bucket": {
            "name": "my-smartbucket"
        }
    },
    key="my-key",
)
print(bucket)

Go

package main

import (
  "context"
  "fmt"

  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk"
  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk/option"
)

func main() {
  client := raindrop.NewClient(
    option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("RAINDROP_API_KEY")
  )
  bucket, err := client.Bucket.Delete(context.TODO(), raindrop.BucketDeleteParams{
    BucketLocation: raindrop.BucketLocatorUnionParam{
      OfBucket: &raindrop.BucketLocatorBucketParam{
        Bucket: raindrop.BucketLocatorBucketBucketParam{
          Name: "my-smartbucket",
        },
      },
    },
    Key: "my-key",
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", bucket)
}

Java

package com.raindrop.api.example;

import com.raindrop.api.client.RaindropClient;
import com.raindrop.api.client.okhttp.RaindropOkHttpClient;
import com.raindrop.api.models.bucket.BucketDeleteParams;
import com.raindrop.api.models.bucket.BucketDeleteResponse;
import com.raindrop.api.models.query.BucketLocator;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        // Configures using the `RAINDROP_API_KEY` and `RAINDROP_BASE_URL` environment variables
        RaindropClient client = RaindropOkHttpClient.fromEnv();

        BucketDeleteParams params = BucketDeleteParams.builder()
            .bucketLocation(BucketLocator.Bucket.builder()
                .bucket(BucketLocator.Bucket.InnerBucket.builder()
                    .name("my-bucket")
                    .build())
                .build())
            .key("my-key")
            .build();
        BucketDeleteResponse bucket = client.bucket().delete(params);
    }
}

CLI

raindrop object delete dog1.pdf --bucket video-demos

curl

curl -X POST "https://api.raindrop.run/v1/delete_object" \
  -H "Authorization: Bearer lm_apikey_..." \
  -H "Content-Type: application/json" \
  -d '{
  "key": "my-key",
  "bucket_location": {
    "bucket": {
      "name": "my-smartbucket",
      "version": "01jxanr45haeswhay4n0q8340y",
      "application_name": "my-app"
    }
  }
}'

Response Examples

200

{}

---

POST /v1/list_objects

List all objects in a SmartBucket or regular bucket. The bucket parameter (ID) is used to identify the bucket to list objects from.

Schema Reference

Request

Request Body

bucketLocation (object) Required

Details

Description

The buckets to search. If provided, the search will only return results from these buckets

Example

{
  "bucket": {
    "name": "my-smartbucket",
    "version": "01jxanr45haeswhay4n0q8340y",
    "application_name": "my-app"
  }
}

Response

objects (array) Required

Details

Description

List of objects in the bucket with their metadata.

Example

[
  {
    "key": "08036c5a50a93da84c5c45ba468c58159d75281e.pdf",
    "size": "401107",
    "contentType": "application/pdf",
    "lastModified": "2025-05-05T18:36:43.029Z"
  },
  {
    "key": "0a29925ccc5e6299e132a73325956a3abef6dd26.pdf",
    "size": "57173",
    "contentType": "application/pdf",
    "lastModified": "2025-05-05T18:36:43.985Z"
  },
  {
    "key": "0e21835a42a6df2405496f62647058ff855743c1.pdf",
    "size": "1223197",
    "contentType": "application/pdf",
    "lastModified": "2025-05-05T18:36:45.362Z"
  }
]

code (string)

Details

Description

Status codes and their meanings:

Code	Number	Description
OK	0	No error occurred.
CANCELLED	1	The operation was cancelled, typically by the caller.
UNKNOWN	2	Unknown error. Usually means a server error not mapped to a known code.
INVALID_ARGUMENT	3	Client specified an invalid argument.
DEADLINE_EXCEEDED	4	Deadline expired before operation could complete.
NOT_FOUND	5	Requested entity was not found.
ALREADY_EXISTS	6	Entity that a client attempted to create already exists.
PERMISSION_DENIED	7	Caller doesn’t have permission.
RESOURCE_EXHAUSTED	8	Some resource has been exhausted (e.g., quota, memory).
FAILED_PRECONDITION	9	Operation rejected because system not in required state.
ABORTED	10	Operation aborted, usually due to concurrency issues.
OUT_OF_RANGE	11	Argument out of acceptable range.
UNIMPLEMENTED	12	Operation not implemented or supported.
INTERNAL	13	Internal error.
UNAVAILABLE	14	Service is currently unavailable.
DATA_LOSS	15	Unrecoverable data loss or corruption.
UNAUTHENTICATED	16	Request does not have valid authentication credentials.

JavaScript

import Raindrop from '@liquidmetal-ai/lm-raindrop';

const client = new Raindrop();

const buckets = await client.bucket.list({ bucketLocation: { bucket: { name: 'my-smartbucket' } } });

console.log(buckets.objects);

Python

from raindrop import Raindrop

client = Raindrop()
buckets = client.bucket.list(
    bucket_location={
        "bucket": {
            "name": "my-smartbucket"
        }
    },
)
print(buckets.objects)

Go

package main

import (
  "context"
  "fmt"

  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk"
  "github.com/LiquidMetal-AI/lm-raindrop-go-sdk/option"
)

func main() {
  client := raindrop.NewClient(
    option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("RAINDROP_API_KEY")
  )
  buckets, err := client.Bucket.List(context.TODO(), raindrop.BucketListParams{
    BucketLocation: raindrop.BucketLocatorUnionParam{
      OfBucket: &raindrop.BucketLocatorBucketParam{
        Bucket: raindrop.BucketLocatorBucketBucketParam{
          Name: "my-smartbucket",
        },
      },
    },
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", buckets.Objects)
}

Java

package com.raindrop.api.example;

import com.raindrop.api.client.RaindropClient;
import com.raindrop.api.client.okhttp.RaindropOkHttpClient;
import com.raindrop.api.models.bucket.BucketListParams;
import com.raindrop.api.models.bucket.BucketListResponse;
import com.raindrop.api.models.query.BucketLocator;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        // Configures using the `RAINDROP_API_KEY` and `RAINDROP_BASE_URL` environment variables
        RaindropClient client = RaindropOkHttpClient.fromEnv();

        BucketListParams params = BucketListParams.builder()
            .bucketLocation(BucketLocator.Bucket.builder()
                .bucket(BucketLocator.Bucket.InnerBucket.builder()
                    .name("my-bucket")
                    .build())
                .build())
            .build();
        BucketListResponse buckets = client.bucket().list(params);
    }
}

CLI

# List all objects in a bucket
npx raindrop object list -b my-bucket

# List objects in JSON format
npx raindrop object list -b my-bucket --output json

# List objects in table format
npx raindrop object list -b my-bucket --output table

curl

curl -X POST "https://api.raindrop.run/v1/list_objects" \
  -H "Authorization: Bearer lm_apikey_..." \
  -H "Content-Type: application/json" \
  -d '{
  "bucket_location": {
    "bucket": {
      "name": "my-smartbucket",
      "version": "01jxanr45haeswhay4n0q8340y",
      "application_name": "my-app"
    }
  }
}'

Response Examples

200

{
  "objects": [
    {
      "key": "08036c5a50a93da84c5c45ba468c58159d75281e.pdf",
      "size": "401107",
      "contentType": "application/pdf",
      "lastModified": "2025-05-05T18:36:43.029Z"
    },
    {
      "key": "0a29925ccc5e6299e132a73325956a3abef6dd26.pdf",
      "size": "57173",
      "contentType": "application/pdf",
      "lastModified": "2025-05-05T18:36:43.985Z"
    },
    {
      "key": "0e21835a42a6df2405496f62647058ff855743c1.pdf",
      "size": "1223197",
      "contentType": "application/pdf",
      "lastModified": "2025-05-05T18:36:45.362Z"
    }
  ]
}

---