openapi: 3.0.1
info:
  title: Tigris Object Storage (S3-Compatible) Buckets Objects API
  description: 'Specification of the Tigris globally distributed object storage API. Tigris is compatible with the AWS S3 API, so the standard AWS S3 SDKs, tools, and libraries work unchanged against the Tigris endpoint at https://t3.storage.dev (the legacy host fly.storage.tigris.dev still resolves). Requests are authenticated with AWS Signature Version 4 using a Tigris access key id (tid_...) and secret access key (tsec_...). This document models the documented, supported subset of the S3 surface: bucket management, object CRUD, multipart upload, object tagging, storage-class tiering, and the path-style operations that back presigned URLs. The companion AWS IAM-compatible API is served at https://iam.storage.dev. Tigris is region-agnostic - use region "auto".'
  termsOfService: https://www.tigrisdata.com/docs/legal/terms-of-service/
  contact:
    name: Tigris Support
    url: https://www.tigrisdata.com/docs/support/
    email: support@tigrisdata.com
  version: '2026-06-20'
servers:
- url: https://t3.storage.dev
  description: Tigris global S3-compatible object storage endpoint (region auto)
- url: https://fly.storage.tigris.dev
  description: Legacy Tigris endpoint hostname (still supported)
security:
- sigv4: []
tags:
- name: Objects
  description: S3-compatible object CRUD, tagging, and tiering operations.
paths:
  /{bucket}:
    parameters:
    - $ref: '#/components/parameters/Bucket'
    get:
      operationId: listObjectsV2
      tags:
      - Objects
      summary: List objects in a bucket (ListObjectsV2 / ListObjects).
      parameters:
      - name: list-type
        in: query
        description: Set to 2 for ListObjectsV2.
        schema:
          type: integer
          enum:
          - 2
      - name: prefix
        in: query
        description: Limits the response to keys that begin with the prefix.
        schema:
          type: string
      - name: delimiter
        in: query
        description: Groups keys sharing a common prefix into CommonPrefixes.
        schema:
          type: string
      - name: continuation-token
        in: query
        description: Token returned by a prior truncated response for pagination.
        schema:
          type: string
      - name: max-keys
        in: query
        description: Maximum number of keys to return.
        schema:
          type: integer
      - name: encoding-type
        in: query
        schema:
          type: string
          enum:
          - url
      responses:
        '200':
          description: Object listing returned as S3 XML (ListBucketResult).
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListBucketResult'
  /{bucket}/{key}:
    parameters:
    - $ref: '#/components/parameters/Bucket'
    - $ref: '#/components/parameters/Key'
    put:
      operationId: putObject
      tags:
      - Objects
      summary: Upload an object (PutObject) or copy an object (CopyObject).
      description: Stores an object. Supply x-amz-storage-class to set the tier (STANDARD, STANDARD_IA, GLACIER, GLACIER_IR). Provide x-amz-copy-source to perform a server-side CopyObject instead of a body upload. Custom metadata (x-amz-meta-*) and SHA256 checksums are supported.
      parameters:
      - name: x-amz-storage-class
        in: header
        description: Storage tier - STANDARD, STANDARD_IA, GLACIER, or GLACIER_IR.
        schema:
          type: string
          enum:
          - STANDARD
          - STANDARD_IA
          - GLACIER
          - GLACIER_IR
      - name: x-amz-copy-source
        in: header
        description: Source "/bucket/key" for a server-side copy (CopyObject).
        schema:
          type: string
      - name: Content-Type
        in: header
        schema:
          type: string
      requestBody:
        description: Raw object bytes (omit for a CopyObject).
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Object stored (or copied). ETag returned in the header.
    get:
      operationId: getObject
      tags:
      - Objects
      summary: Download an object (GetObject), optionally ranged or conditional.
      parameters:
      - name: Range
        in: header
        description: Byte range to retrieve, e.g. "bytes=0-1023".
        schema:
          type: string
      - name: If-Match
        in: header
        schema:
          type: string
      - name: If-None-Match
        in: header
        schema:
          type: string
      - name: If-Modified-Since
        in: header
        schema:
          type: string
      - name: If-Unmodified-Since
        in: header
        schema:
          type: string
      responses:
        '200':
          description: Object body returned.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '206':
          description: Partial object body returned for a ranged request.
        '304':
          description: Not modified (conditional request).
        '404':
          description: Object not found.
    head:
      operationId: headObject
      tags:
      - Objects
      summary: Retrieve object metadata without the body (HeadObject).
      responses:
        '200':
          description: Object metadata returned in headers.
        '404':
          description: Object not found.
    delete:
      operationId: deleteObject
      tags:
      - Objects
      summary: Delete an object (DeleteObject).
      responses:
        '204':
          description: Object deleted.
  /{bucket}/{key}#tagging:
    parameters:
    - $ref: '#/components/parameters/Bucket'
    - $ref: '#/components/parameters/Key'
    put:
      operationId: putObjectTagging
      tags:
      - Objects
      summary: Set the tag set on an object (PutObjectTagging).
      description: Operates on the object's ?tagging subresource.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Tagging'
      responses:
        '200':
          description: Tag set applied.
    get:
      operationId: getObjectTagging
      tags:
      - Objects
      summary: Retrieve the tag set on an object (GetObjectTagging).
      responses:
        '200':
          description: Tag set returned.
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Tagging'
    delete:
      operationId: deleteObjectTagging
      tags:
      - Objects
      summary: Remove the tag set from an object (DeleteObjectTagging).
      responses:
        '204':
          description: Tag set removed.
  /{bucket}#delete:
    parameters:
    - $ref: '#/components/parameters/Bucket'
    post:
      operationId: deleteObjects
      tags:
      - Objects
      summary: Delete multiple objects in one request (DeleteObjects).
      description: Operates on the bucket ?delete subresource. Supports quiet mode.
      requestBody:
        required: true
        content:
          application/xml:
            schema:
              $ref: '#/components/schemas/Delete'
      responses:
        '200':
          description: Per-key delete results returned as S3 XML.
  /{bucket}/{key}#restore:
    parameters:
    - $ref: '#/components/parameters/Bucket'
    - $ref: '#/components/parameters/Key'
    post:
      operationId: restoreObject
      tags:
      - Objects
      summary: Restore an archived (GLACIER) object (RestoreObject).
      description: Restores an object stored in the Archive tier so it becomes retrievable. Operates on the object ?restore subresource.
      responses:
        '202':
          description: Restore request accepted.
        '200':
          description: Restore already in progress or completed.
components:
  schemas:
    Delete:
      type: object
      properties:
        Quiet:
          type: boolean
        Objects:
          type: array
          items:
            type: object
            properties:
              Key:
                type: string
              VersionId:
                type: string
    Object:
      type: object
      properties:
        Key:
          type: string
        LastModified:
          type: string
          format: date-time
        ETag:
          type: string
        Size:
          type: integer
          format: int64
        StorageClass:
          type: string
          enum:
          - STANDARD
          - STANDARD_IA
          - GLACIER
          - GLACIER_IR
    ListBucketResult:
      type: object
      properties:
        Name:
          type: string
        Prefix:
          type: string
        KeyCount:
          type: integer
        MaxKeys:
          type: integer
        IsTruncated:
          type: boolean
        NextContinuationToken:
          type: string
        Contents:
          type: array
          items:
            $ref: '#/components/schemas/Object'
        CommonPrefixes:
          type: array
          items:
            type: object
            properties:
              Prefix:
                type: string
    Tagging:
      type: object
      properties:
        TagSet:
          type: array
          items:
            type: object
            properties:
              Key:
                type: string
              Value:
                type: string
  parameters:
    Key:
      name: key
      in: path
      required: true
      description: Object key. May contain slashes to emulate a directory hierarchy.
      schema:
        type: string
    Bucket:
      name: bucket
      in: path
      required: true
      description: Bucket name (also usable as a virtual-host subdomain of t3.storage.dev).
      schema:
        type: string
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4 request signing. Clients sign each request with a Tigris access key id (AWS_ACCESS_KEY_ID=tid_...) and secret access key (AWS_SECRET_ACCESS_KEY=tsec_...); the signature is carried in the standard Authorization header (or query string for presigned URLs). Use service name "s3" and region "auto". Any AWS SDK / SigV4 signer produces a compatible signature.