> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nami.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# List Objects

> List objects in a bucket

<Note>
  Make sure you have READ permission on the bucket.
</Note>

## List Objects

Returns some or all (up to 1,000) objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

### Base URL

```bash theme={null}
https://${bucketname}.storage.nami.cloud
```

### Query Parameters

<ParamField query="prefix" optional>
  Limits the response to keys that begin with the specified prefix
</ParamField>

<ParamField query="delimiter" optional>
  Character used to group keys (commonly used with '/')
</ParamField>

<ParamField query="max-keys" optional>
  Maximum number of keys to include in the response (default: 1000)
</ParamField>

<ParamField query="marker" optional>
  Specifies the key to start with when listing objects
</ParamField>

### Request Examples

<RequestExample>
  ```bash Bash theme={null}
  curl "https://mybucket.storage.nami.cloud/?max-keys=2&prefix=example" \
    -H "Authorization: AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20231028/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-date, Signature=fe5f80f77d5fa3beca038a248ff027d0445342fe2855ddc963176630326f1024"
  ```

  ```python Python theme={null}
  import boto3

  s3_client = boto3.client('s3',
      endpoint_url='https://storage.nami.cloud',
      aws_access_key_id='YOUR_ACCESS_KEY',
      aws_secret_access_key='YOUR_SECRET_KEY'
  )

  response = s3_client.list_objects_v2(
      Bucket='mybucket',
      Prefix='example',
      MaxKeys=2
  )

  for obj in response.get('Contents', []):
      print(obj['Key'], obj['Size'])
  ```

  ```javascript Node.js theme={null}
  import { S3Client, ListObjectsV2Command } from "@aws-sdk/client-s3";

  const client = new S3Client({
    endpoint: "https://storage.nami.cloud",
    credentials: {
      accessKeyId: "YOUR_ACCESS_KEY",
      secretAccessKey: "YOUR_SECRET_KEY",
    },
  });

  async function listObjects() {
    const command = new ListObjectsV2Command({
      Bucket: "mybucket",
      Prefix: "example",
      MaxKeys: 2
    });

    try {
      const response = await client.send(command);
      console.log("Objects:", response.Contents);
    } catch (err) {
      console.error("Error:", err);
    }
  }

  listObjects();
  ```

  ```go Golang theme={null}
  package main

  import (
      "fmt"
      "github.com/aws/aws-sdk-go/aws"
      "github.com/aws/aws-sdk-go/aws/credentials"
      "github.com/aws/aws-sdk-go/aws/session"
      "github.com/aws/aws-sdk-go/service/s3"
  )

  func main() {
      sess := session.Must(session.NewSession(&aws.Config{
          Endpoint:    aws.String("https://storage.nami.cloud"),
          Region:      aws.String("us-east-1"),
          Credentials: credentials.NewStaticCredentials("YOUR_ACCESS_KEY", "YOUR_SECRET_KEY", ""),
      }))

      s3Client := s3.New(sess)

      resp, err := s3Client.ListObjectsV2(&s3.ListObjectsV2Input{
          Bucket:  aws.String("mybucket"),
          Prefix:  aws.String("example"),
          MaxKeys: aws.Int64(2),
      })
      if err != nil {
          panic(err)
      }

      for _, item := range resp.Contents {
          fmt.Println("Name:", *item.Key)
          fmt.Println("Size:", *item.Size)
      }
  }
  ```

  ```rust Rust theme={null}
  use aws_sdk_s3::{Client, Config};
  use aws_config::credentials::StaticCredentialsProvider;
  use aws_types::region::Region;
  use tokio;

  #[tokio::main]
  async fn main() -> Result<(), Box<dyn std::error::Error>> {
      let credentials = StaticCredentialsProvider::new(
          "YOUR_ACCESS_KEY".to_string(),
          "YOUR_SECRET_KEY".to_string(),
          None,
      );

      let config = Config::builder()
          .endpoint_url("https://storage.nami.cloud")
          .region(Region::new("us-east-1"))
          .credentials_provider(credentials)
          .build();

      let client = Client::from_conf(config);

      let response = client
          .list_objects_v2()
          .bucket("mybucket")
          .prefix("example")
          .max_keys(2)
          .send()
          .await?;

      if let Some(contents) = response.contents() {
          for object in contents {
              println!("Key: {}", object.key().unwrap_or_default());
              println!("Size: {}", object.size());
          }
      }

      Ok(())
  }
  ```
</RequestExample>

### Response Example

```xml theme={null}
HTTP/1.1 200 OK
x-amz-id-2: LriYPLdmOdAiIfgSm/F1YsViT1LW94/xUQxMsF7xiEb1a0wiIOIxl+zbwZ163pt7
x-amz-request-id: 65BD8659F15793A1
Date: Wed, 28 Oct 2023 22:32:00 GMT
Content-Type: application/xml
Content-Length: 302
Server: Nami Cloud

<?xml version="1.0" encoding="UTF-8"?>
<ListBucketResult xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
    <Name>mybucket</Name>
    <Prefix>example</Prefix>
    <Marker></Marker>
    <MaxKeys>2</MaxKeys>
    <IsTruncated>true</IsTruncated>
    <Contents>
        <Key>example.jpg</Key>
        <LastModified>2023-10-28T22:32:00.000Z</LastModified>
        <ETag>"fba9dede5f27731c9771645a39863328"</ETag>
        <Size>434234</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
    <Contents>
        <Key>example2.jpg</Key>
        <LastModified>2023-10-28T22:33:00.000Z</LastModified>
        <ETag>"9b2cf535f27731c9771645a39863328"</ETag>
        <Size>233524</Size>
        <StorageClass>STANDARD</StorageClass>
    </Contents>
</ListBucketResult>
```


## OpenAPI

````yaml GET /
openapi: 3.0.1
info:
  title: Nami Cloud Storage API
  description: S3 compatible storage service API documentation
  version: 1.0.0
servers:
  - url: https://{bucketName}.storage.nami.cloud
    variables:
      bucketName:
        default: mybucket
        description: The name of the bucket
security:
  - awsV4: []
paths:
  /:
    get:
      tags:
        - Object Operations
      summary: List Objects
      description: Lists objects in a bucket
      parameters:
        - name: prefix
          in: query
          description: Limits the response to keys that begin with the specified prefix
          schema:
            type: string
        - name: max-keys
          in: query
          description: Sets the maximum number of keys returned in the response
          schema:
            type: integer
            default: 1000
      responses:
        '200':
          description: Success
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListBucketResult'
components:
  schemas:
    ListBucketResult:
      type: object
      properties:
        Name:
          type: string
        Prefix:
          type: string
        MaxKeys:
          type: integer
        IsTruncated:
          type: boolean
        Contents:
          type: array
          items:
            $ref: '#/components/schemas/Object'
    Object:
      type: object
      properties:
        Key:
          type: string
        LastModified:
          type: string
          format: date-time
        ETag:
          type: string
        Size:
          type: integer
        StorageClass:
          type: string
  securitySchemes:
    awsV4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4

````