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

# S3 protocol (GET)

> Dispatched to ListBuckets / ListObjectsV2 / GetObject / HeadObject / ListParts / GetBucketLocation / GetBucketVersioning based on path shape and query.



## OpenAPI

````yaml https://raw.githubusercontent.com/InsForge/InsForge/main/openapi/storage.yaml get /storage/v1/s3/{path}
openapi: 3.0.3
info:
  title: Insforge Storage API
  version: 2.0.0
  description: Bucket-based storage system similar to S3
servers: []
security: []
paths:
  /storage/v1/s3/{path}:
    description: >
      **AWS S3-compatible protocol gateway.** Speak the S3 protocol directly

      from any SigV4 client (AWS SDKs, `aws` CLI, `rclone`, Terraform, etc.)

      against this endpoint. Only path-style URLs are supported; SDKs must

      be configured with `forcePathStyle: true` and the signing region

      `us-east-2` (or the value of `S3_REGION`, fallback `AWS_REGION`, on

      this backend — see `GET /api/storage/s3/config`).


      Supported operations: ListBuckets, CreateBucket, DeleteBucket,

      HeadBucket, ListObjectsV2, PutObject (streaming + UNSIGNED +

      pre-hashed), GetObject (incl. Range), HeadObject, DeleteObject,

      DeleteObjects (batch), CopyObject, CreateMultipartUpload,

      UploadPart, CompleteMultipartUpload, AbortMultipartUpload,

      ListParts, plus `GetBucketLocation` / `GetBucketVersioning` stubs.


      Buckets and objects are shared with the REST API — an object uploaded

      via S3 protocol appears immediately in `GET
      /api/storage/buckets/{bucket}/objects`

      and vice versa.


      Example (AWS SDK v3):


      ```

      new S3Client({
        endpoint: 'https://<host>/storage/v1/s3',
        region: 'us-east-2',
        forcePathStyle: true,
        credentials: { accessKeyId, secretAccessKey },
      });

      ```


      Errors use S3-style XML (`<Error><Code>...</Code>...</Error>`).
    parameters:
      - name: path
        in: path
        required: true
        description: |
          Standard path-style S3 path, e.g. `my-bucket/object-key`,
          `my-bucket` (bucket-level ops), or empty for ListBuckets.
        schema:
          type: string
    get:
      tags:
        - S3 Protocol
      summary: S3 protocol (GET)
      description: >-
        Dispatched to ListBuckets / ListObjectsV2 / GetObject / HeadObject /
        ListParts / GetBucketLocation / GetBucketVersioning based on path shape
        and query.
      responses:
        '200':
          description: Success
        '206':
          description: Partial content (Range GetObject)
        '403':
          description: SignatureDoesNotMatch / InvalidAccessKeyId / RequestTimeTooSkewed
        '404':
          description: NoSuchBucket / NoSuchKey
        '501':
          description: NotImplemented (backend is not S3-compatible, or op unsupported)
      security:
        - s3SigV4: []
components:
  securitySchemes:
    s3SigV4:
      type: http
      scheme: aws4-hmac-sha256
      description: |
        AWS SigV4 authentication using S3 access keys minted by
        `POST /api/storage/s3/access-keys`. Region must match the server's
        `S3_REGION` (fallback `AWS_REGION`, default `us-east-2`); service
        scope must be `s3`.

````