openapi: 3.2.0
info:
  title: Nasuni Data Service (NDS) AWS API
  description: "# Overview\n\nWelcome to Nasuni Data Service (NDS) for AWS API Documentation.\n\nThis documentation describes the S3-compatible, read-only endpoints exposed via AWS S3 Object Lambda for accessing data stored in a Nasuni Volume.\n\n## Authentication\n\nThis API sits behind **AWS S3 Object Lambda**. Authenticate exactly as you would to S3:\n\n- **AWS Signature Version 4 (headers)** — Signed requests include:\n  - `Authorization: AWS4-HMAC-SHA256 ...`\n  - `X-Amz-Date: YYYYMMDD'T'HHMMSS'Z'`\n  - `X-Amz-Content-Sha256: UNSIGNED-PAYLOAD`\n  - `X-Amz-Security-Token` (when using temporary credentials)\n\n- **Presigned URLs** — Generated by AWS SDK/CLI. Credentials/signature appear as query params:\n  `X-Amz-Algorithm`, `X-Amz-Credential`, `X-Amz-Date`, `X-Amz-Expires`,\n  `X-Amz-SignedHeaders`, `X-Amz-Signature`, and optional `X-Amz-Security-Token`.\n\n## Available Operations\n* **ListObjects / ListObjectsV2**: List files in a volume.\n* **HeadObject**: Retrieve file metadata and headers.\n* **GetObject**: Download file content; supports single byte-range requests.\n"
  termsOfService: https://www.nasuni.com/legal
  contact:
    name: Nasuni Support
    url: https://www.nasuni.com/support
    email: support@nasuni.com
  license:
    name: Nasuni
    url: https://www.nasuni.com/legal
  version: 1.1.0
security:
- awsSigV4: []
tags:
- name: Nasuni Data Service (NDS) AWS API
paths:
  /:
    get:
      summary: ListObjects — list objects in a bucket (V1 Legacy)
      description: 'Returns a list of objects (files) in the specified bucket (Nasuni volume) using the legacy S3 ListObjects API.


        This is the legacy method for listing objects, using markers for pagination.


        **Request example**:

        ```

        GET /?prefix=documents/&max-keys=1000&marker=documents/old.txt

        ```

        '
      operationId: listObjects
      parameters:
      - $ref: '#/components/parameters/AwsAuthorizationHeader'
      - $ref: '#/components/parameters/XAmzDateHeader'
      - $ref: '#/components/parameters/XAmzContentSha256Header'
      - $ref: '#/components/parameters/XAmzSecurityTokenHeader'
      - name: prefix
        in: query
        required: false
        schema:
          type: string
        description: Limits the response to keys that begin with the specified prefix
        example: documents/2025/
      - name: delimiter
        in: query
        required: false
        schema:
          type: string
          maxLength: 1
        description: 'Character used to group keys. Typically set to ''/'' to simulate directory hierarchy.

          When specified, keys containing the delimiter after the prefix are rolled up into CommonPrefixes.

          '
        example: /
      - name: max-keys
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
        description: 'Maximum number of keys to return. If 0, returns an empty result.

          Default and maximum are deployment-configured (commonly 1000).

          '
      - name: marker
        in: query
        required: false
        schema:
          type: string
        description: Marker for pagination. Set to the key to start with when listing objects.
      - name: encoding-type
        in: query
        required: false
        schema:
          type: string
          enum:
          - url
        description: Requests URL encoding for object keys in the response.
      responses:
        '200':
          description: Successful ListObjects (V1) response
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/ListBucketResultV1'
              examples:
                listObjectsV1:
                  summary: V1 response (with NextMarker)
                  value: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<ListBucketResult>\n  <Name>6c19a28d-19cd-4876-ac90-1a2fe3a22426-1</Name>\n  <Prefix>documents/</Prefix>\n  <Delimiter>/</Delimiter>\n  <KeyCount>1</KeyCount>\n  <MaxKeys>1000</MaxKeys>\n  <IsTruncated>true</IsTruncated>\n  <NextMarker>documents/videos/sample.mp4</NextMarker>\n  <Contents>\n    <Key>documents/readme.txt</Key>\n    <LastModified>2025-01-15T10:30:00.000Z</LastModified>\n    <ETag>\"abc123\"</ETag>\n    <Size>512</Size>\n    <StorageClass>STANDARD</StorageClass>\n  </Contents>\n  <CommonPrefixes>\n    <Prefix>documents/images/</Prefix>\n  </CommonPrefixes>\n  <CommonPrefixes>\n    <Prefix>documents/videos/</Prefix>\n  </CommonPrefixes>\n</ListBucketResult>\n"
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NoSuchBucket'
        '424':
          $ref: '#/components/responses/FailedDependency'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/NotImplemented'
      tags:
      - Nasuni Data Service (NDS) AWS API
  /{key}:
    head:
      summary: Get object metadata
      description: 'Retrieves metadata about an object without returning the object content.


        Returns standard S3 headers plus Nasuni-specific metadata as x-amz-meta-* headers.

        '
      operationId: headObject
      parameters:
      - $ref: '#/components/parameters/AwsAuthorizationHeader'
      - $ref: '#/components/parameters/XAmzDateHeader'
      - $ref: '#/components/parameters/XAmzContentSha256Header'
      - $ref: '#/components/parameters/XAmzSecurityTokenHeader'
      - name: key
        in: path
        required: true
        schema:
          type: string
        description: The object key (file path within the volume)
        example: documents/report.pdf
      responses:
        '200':
          description: Object metadata retrieved successfully
          headers:
            Content-Length:
              schema:
                type: integer
              description: Size of the object in bytes
              example: 1048576
            Content-Type:
              schema:
                type: string
              description: MIME type of the object (guessed from file extension)
              example: application/pdf
            Last-Modified:
              schema:
                type: string
              description: Date and time the object was last modified
              example: Wed, 15 Jan 2025 10:30:00 GMT
            ETag:
              schema:
                type: string
              description: Entity tag for the object (quoted)
              example: '"9bb58f26192e4ba00f01e2e7b136bbd8"'
            x-amz-meta-nasuni-meta-chunked-info:
              schema:
                type: string
              description: If present, a JSON dictionary that maps each metadata field that was split across multiple headers to the number of chunks it was split into.
              example: 'x-amz-meta-nasuni-meta-chunked-info: {"large-metadata-value":2}, x-amz-meta-large-metadata-value-1: ..., x-amz-meta-large-metadata-value-2: ...'
            x-amz-meta-nasuni-meta-trimmed:
              schema:
                type: string
              description: If present and set to "true", indicates that the server omitted some custom metadata from the response because the total payload exceeded the allowed size.
            x-amz-meta-handle:
              schema:
                type: string
              description: Nasuni internal file handle
              example: 3.uni8eF3bF59-1749497123-456
            x-amz-meta-uid:
              schema:
                type: string
              description: Unix user ID of file owner
              example: '1000'
            x-amz-meta-gid:
              schema:
                type: string
              description: Unix group ID
              example: '1000'
            x-amz-meta-mode:
              schema:
                type: string
              description: Unix file permissions (octal)
              example: '0100644'
            x-amz-meta-size:
              schema:
                type: string
              description: File size in bytes
              example: '1048576'
            x-amz-meta-mtime:
              schema:
                type: string
              description: Modification time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-ctime:
              schema:
                type: string
              description: Change time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-atime:
              schema:
                type: string
              description: Access time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-firsthandle:
              schema:
                type: string
              description: First handle in the file version chain
              example: 3.uni8eF3bF59-1749497123-1
        '403':
          description: Access denied or NDS disabled.
        '404':
          description: Object not found
        '424':
          description: Failed dependency (volume not accessible)
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/NotImplemented'
      tags:
      - Nasuni Data Service (NDS) AWS API
    get:
      summary: Get object content
      description: 'Downloads the content of an object from the bucket.


        ## Range Requests


        Supports HTTP range requests for partial file downloads. Use the `Range` header to specify byte ranges.


        ## Size Limitations


        Files exceeding the configured maximum size limit of 2 GiB will return a 416 error with code `InvalidRange`.


        ## Response Headers


        The response includes all headers from HeadObject plus content-specific headers.

        '
      operationId: getObject
      parameters:
      - $ref: '#/components/parameters/AwsAuthorizationHeader'
      - $ref: '#/components/parameters/XAmzDateHeader'
      - $ref: '#/components/parameters/XAmzContentSha256Header'
      - $ref: '#/components/parameters/XAmzSecurityTokenHeader'
      - name: key
        in: path
        required: true
        schema:
          type: string
        description: The object key (file path within the volume)
      - name: Range
        in: header
        required: false
        schema:
          type: string
        description: 'HTTP Range header for partial object retrieval.

          Format: `bytes=start-end` where start and end are 0-based byte offsets.

          Multiple ranges are not supported.

          '
        example: bytes=0-1023
      responses:
        '200':
          description: Object retrieved successfully (full content)
          headers:
            Content-Length:
              schema:
                type: integer
              description: Size of the returned content
            Content-Type:
              schema:
                type: string
              description: MIME type of the object
            Last-Modified:
              schema:
                type: string
              description: Date and time the object was last modified
            ETag:
              schema:
                type: string
              description: Entity tag for the object
            x-amz-meta-nasuni-meta-chunked-info:
              schema:
                type: string
              description: If present, a JSON dictionary that maps each metadata field that was split across multiple headers to the number of chunks it was split into.
              example: 'x-amz-meta-nasuni-meta-chunked-info: {"large-metadata-value":2}, x-amz-meta-large-metadata-value-1: ..., x-amz-meta-large-metadata-value-2: ...'
            x-amz-meta-nasuni-meta-trimmed:
              schema:
                type: string
              description: If present and set to "true", indicates that the server omitted some custom metadata from the response because the total payload exceeded the allowed size.
            x-amz-meta-handle:
              schema:
                type: string
              description: Nasuni internal file handle
              example: 3.uni8eF3bF59-1749497123-456
            x-amz-meta-uid:
              schema:
                type: string
              description: Unix user ID of file owner
              example: '1000'
            x-amz-meta-gid:
              schema:
                type: string
              description: Unix group ID
              example: '1000'
            x-amz-meta-mode:
              schema:
                type: string
              description: Unix file permissions (octal)
              example: '0100644'
            x-amz-meta-size:
              schema:
                type: string
              description: File size in bytes
              example: '1048576'
            x-amz-meta-mtime:
              schema:
                type: string
              description: Modification time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-ctime:
              schema:
                type: string
              description: Change time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-atime:
              schema:
                type: string
              description: Access time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-firsthandle:
              schema:
                type: string
              description: First handle in the file version chain
              example: 3.uni8eF3bF59-1749497123-1
          content:
            '*/*':
              schema:
                type: string
                format: binary
              examples:
                textFile:
                  summary: Text file content
                  value: This is the content of the file.
        '206':
          description: Partial content returned (range request successful)
          headers:
            Content-Range:
              schema:
                type: string
              description: The byte range returned
              example: bytes 0-1023/1048576
            Content-Length:
              schema:
                type: integer
              description: Size of the partial content returned
            Last-Modified:
              schema:
                type: string
              description: Date and time the object was last modified
            ETag:
              schema:
                type: string
              description: Entity tag for the object
            x-amz-meta-nasuni-meta-chunked-info:
              schema:
                type: string
              description: If present, a JSON dictionary that maps each metadata field that was split across multiple headers to the number of chunks it was split into.
              example: 'x-amz-meta-nasuni-meta-chunked-info: {"large-metadata-value":2}, x-amz-meta-large-metadata-value-1: ..., x-amz-meta-large-metadata-value-2: ...'
            x-amz-meta-nasuni-meta-trimmed:
              schema:
                type: string
              description: If present and set to "true", indicates that the server omitted some custom metadata from the response because the total payload exceeded the allowed size.
            x-amz-meta-handle:
              schema:
                type: string
              description: Nasuni internal file handle
              example: 3.uni8eF3bF59-1749497123-456
            x-amz-meta-uid:
              schema:
                type: string
              description: Unix user ID of file owner
              example: '1000'
            x-amz-meta-gid:
              schema:
                type: string
              description: Unix group ID
              example: '1000'
            x-amz-meta-mode:
              schema:
                type: string
              description: Unix file permissions (octal)
              example: '0100644'
            x-amz-meta-size:
              schema:
                type: string
              description: File size in bytes
              example: '1048576'
            x-amz-meta-mtime:
              schema:
                type: string
              description: Modification time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-ctime:
              schema:
                type: string
              description: Change time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-atime:
              schema:
                type: string
              description: Access time (ISO 8601)
              example: '2025-01-15T10:30:00.000Z'
            x-amz-meta-firsthandle:
              schema:
                type: string
              description: First handle in the file version chain
              example: 3.uni8eF3bF59-1749497123-1
          content:
            '*/*':
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/AccessDenied'
        '404':
          $ref: '#/components/responses/NoSuchKey'
        '416':
          description: Range not satisfiable
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                invalidRange:
                  summary: File size exceeds limit
                  value: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>InvalidRange</Code>\n  <Message>File exceeds max size of 2147483648 bytes</Message>\n</Error>\n"
        '424':
          $ref: '#/components/responses/FailedDependency'
        '500':
          $ref: '#/components/responses/InternalError'
        '501':
          $ref: '#/components/responses/NotImplemented'
      tags:
      - Nasuni Data Service (NDS) AWS API
components:
  schemas:
    Object:
      type: object
      xml:
        name: Contents
      properties:
        Key:
          type: string
          description: Object key (file path)
        LastModified:
          type: string
          format: date-time
          description: Last modification time
        ETag:
          type: string
          description: Entity tag (always quoted)
        Size:
          type: integer
          format: int64
          description: Size in bytes
        StorageClass:
          type: string
          enum:
          - STANDARD
          description: Storage class (always STANDARD for NDS)
    Error:
      type: object
      xml:
        name: Error
      properties:
        Code:
          type: string
          description: Error code
        Message:
          type: string
          description: Human-readable error message
        Resource:
          type: string
          description: Resource related to the error
        RequestId:
          type: string
          description: Unique request identifier
    ListBucketResultBase:
      type: object
      xml:
        name: ListBucketResult
      properties:
        Name:
          type: string
          description: Name of the bucket
        Prefix:
          type: string
          description: Keys that begin with the indicated prefix
        Delimiter:
          type: string
          description: Delimiter used for grouping
        MaxKeys:
          type: integer
          description: Maximum number of keys returned
        KeyCount:
          type: integer
          description: Number of keys returned in this result
        IsTruncated:
          type: string
          enum:
          - 'true'
          - 'false'
          description: Whether additional keys exist beyond MaxKeys
        EncodingType:
          type: string
          enum:
          - url
          description: Encoding type applied to object keys
        Contents:
          type: array
          xml:
            wrapped: false
          items:
            $ref: '#/components/schemas/Object'
        CommonPrefixes:
          type: array
          xml:
            wrapped: false
          items:
            type: object
            properties:
              Prefix:
                type: string
    ListBucketResultV1:
      allOf:
      - $ref: '#/components/schemas/ListBucketResultBase'
      - type: object
        properties:
          NextMarker:
            type: string
            description: Marker for next page (ListObjects only)
  responses:
    AccessDenied:
      description: Access denied or NDS disabled
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            ndsNotLicensed:
              summary: NDS not available in license
              value: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NDSDisabled</Code>\n  <Message>NDS is not available in your license</Message>\n</Error>\n"
            ndsDisabledConfig:
              summary: NDS disabled in configuration
              value: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NDSDisabled</Code>\n  <Message>NDS is available in your license but is disabled or misconfigured</Message>\n</Error>\n"
    FailedDependency:
      description: Volume not accessible (not shared or missing TOC)
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>FailedDependency</Code>\n  <Message>Volume requires Remote Access enabled and at least one snapshot</Message>\n</Error>\n"
    InternalError:
      description: Internal server error
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>InternalError</Code>\n  <Message>Unexpected error.</Message>\n</Error>\n"
        application/octet-stream:
          schema:
            type: string
            description: May be empty depending on operation.
    NoSuchBucket:
      description: The specified bucket does not exist
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NoSuchBucket</Code>\n  <Message>The specified bucket does not exist</Message>\n</Error>\n"
    NoSuchKey:
      description: The specified key does not exist
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NoSuchKey</Code>\n  <Message>The specified key does not exist.</Message>\n</Error>\n"
    NotImplemented:
      description: Not Implemented - Operation not supported by NDS
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/Error'
          example: "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<Error>\n  <Code>NotImplemented</Code>\n  <Message>The specified operation is not supported by NDS</Message>\n</Error>\n"
  parameters:
    AwsAuthorizationHeader:
      name: Authorization
      in: header
      required: false
      description: 'AWS Signature Version 4 authorization header.

        Omit when using a presigned URL.

        '
      schema:
        type: string
        example: AWS4-HMAC-SHA256 Credential=AKIA.../20250115/us-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=0123456789abcdef...
    XAmzSecurityTokenHeader:
      name: X-Amz-Security-Token
      in: header
      required: false
      description: Session token when using temporary credentials (STS/role).
      schema:
        type: string
    XAmzDateHeader:
      name: X-Amz-Date
      in: header
      required: false
      description: ISO8601 timestamp used by SigV4, e.g. 20250115T103000Z. Omit with presigned URLs.
      schema:
        type: string
        example: 20250115T103000Z
    XAmzContentSha256Header:
      name: X-Amz-Content-Sha256
      in: header
      required: false
      description: 'For GET/HEAD, S3 commonly uses `UNSIGNED-PAYLOAD`.

        SDKs set this automatically. Omit with presigned URLs.

        '
      schema:
        type: string
        example: UNSIGNED-PAYLOAD
  securitySchemes:
    awsSigV4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. Presigned URLs also supported.