> ## 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.

# Head Object

> Retrieve object metadata

<Note>
  You need READ permission on the object to retrieve its metadata.
</Note>

## Head Object

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata or want to check if an object exists.

### Base URL

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

### Parameters

<ParamField path="objectKey" required>
  The key of the object to retrieve metadata for
</ParamField>

### Headers

<ParamField header="If-Match" optional>
  Return the metadata only if the ETag matches
</ParamField>

<ParamField header="If-Modified-Since" optional>
  Return the metadata only if the object has been modified since the specified time
</ParamField>

### Request Examples

<RequestExample>
  ```bash Bash theme={null}
  curl -I "https://mybucket.storage.nami.cloud/example.jpg" \
    -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.head_object(
      Bucket='mybucket',
      Key='example.jpg'
  )

  print(f"Content Length: {response['ContentLength']}")
  print(f"Last Modified: {response['LastModified']}")
  print(f"ETag: {response['ETag']}")
  ```

  ```javascript Node.js theme={null}
  import { S3Client, HeadObjectCommand } 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 getObjectMetadata() {
    const command = new HeadObjectCommand({
      Bucket: "mybucket",
      Key: "example.jpg",
    });

    try {
      const response = await client.send(command);
      console.log("Content Length:", response.ContentLength);
      console.log("Last Modified:", response.LastModified);
      console.log("ETag:", response.ETag);
    } catch (err) {
      console.error("Error:", err);
    }
  }

  getObjectMetadata();
  ```

  ```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)

      result, err := s3Client.HeadObject(&s3.HeadObjectInput{
          Bucket: aws.String("mybucket"),
          Key:    aws.String("example.jpg"),
      })
      if err != nil {
          panic(err)
      }

      fmt.Printf("Content Length: %d\n", *result.ContentLength)
      fmt.Printf("Last Modified: %v\n", *result.LastModified)
      fmt.Printf("ETag: %s\n", *result.ETag)
  }
  ```

  ```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
          .head_object()
          .bucket("mybucket")
          .key("example.jpg")
          .send()
          .await?;

      println!("Content Length: {}", response.content_length().unwrap());
      println!("Last Modified: {:?}", response.last_modified().unwrap());
      println!("ETag: {}", response.e_tag().unwrap());

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

### Response Example

```json theme={null}
HTTP/1.1 200 OK
x-amz-id-2: ef8yU9AS1ed4OpIszj7UDNEHGran
x-amz-request-id: 318BC8BC143432E5
Date: Wed, 28 Oct 2023 22:32:00 GMT
Last-Modified: Wed, 28 Oct 2023 19:27:20 GMT
ETag: "b9875f283e5571ae9ac762fba126cf8d"
Content-Length: 434234
Content-Type: image/jpeg
Server: Nami Cloud
```


## OpenAPI

````yaml HEAD /{objectKey}
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:
  /{objectKey}:
    head:
      tags:
        - Object Operations
      summary: Head Object
      description: Retrieves metadata from an object without returning the object itself
      parameters:
        - name: objectKey
          in: path
          required: true
          description: Key of the object
          schema:
            type: string
      responses:
        '200':
          description: Object metadata retrieved successfully
          headers:
            Content-Length:
              schema:
                type: integer
            ETag:
              schema:
                type: string
components:
  securitySchemes:
    awsV4:
      type: apiKey
      name: Authorization
      in: header
      description: AWS Signature Version 4

````