openapi: 3.0.0
info:
  version: 1.0.0
  title: Nhost authentication storage API
  description: Comprehensive authentication service for managing user identities, sessions, and authentication methods
  license:
    name: MIT License
    url: https://opensource.org/licenses/MIT
  contact:
    name: Nhost Support
    email: support@nhost.io
    url: https://nhost.io
servers:
- url: https://{subdomain}.auth.{region}.nhost.run/v1
  description: Nhost Authentication API Server
tags:
- name: storage
  description: Storage operations and presigned URLs
paths:
  /files/{id}/presignedurl:
    get:
      summary: Retrieve presigned URL to retrieve the file
      operationId: getFilePresignedURL
      description: 'Retrieve presigned URL to retrieve the file. Expiration of the URL is

        determined by bucket configuration

        '
      tags:
      - storage
      security:
      - Authorization: []
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the file
        schema:
          type: string
      responses:
        '200':
          description: File gathered successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PresignedURLResponse'
        default:
          description: Some error occurred
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /files/{id}/presignedurl/contents:
    get:
      summary: Retrieve contents of file
      operationId: getFileWithPresignedURL
      description: Retrieve contents of file
      tags:
      - storage
      security:
      - Authorization: []
      parameters:
      - name: id
        required: true
        in: path
        description: Unique identifier of the file
        schema:
          type: string
      - name: X-Amz-Algorithm
        description: Use presignedurl endpoint to generate this automatically
        required: true
        in: query
        schema:
          type: string
      - name: X-Amz-Credential
        description: Use presignedurl endpoint to generate this automatically
        required: true
        in: query
        schema:
          type: string
      - name: X-Amz-Date
        description: Use presignedurl endpoint to generate this automatically
        required: true
        in: query
        schema:
          type: string
      - name: X-Amz-Expires
        description: Use presignedurl endpoint to generate this automatically
        required: true
        in: query
        schema:
          type: string
      - name: X-Amz-Signature
        description: Use presignedurl endpoint to generate this automatically
        required: true
        in: query
        schema:
          type: string
      - name: X-Amz-SignedHeaders
        description: Use presignedurl endpoint to generate this automatically
        required: true
        in: query
        schema:
          type: string
      - name: X-Amz-Checksum-Mode
        description: Use presignedurl endpoint to generate this automatically
        required: true
        in: query
        schema:
          type: string
      - name: X-Amz-Security-Token
        description: Use presignedurl endpoint to generate this automatically
        required: false
        in: query
        schema:
          type: string
      - name: x-id
        description: Use presignedurl endpoint to generate this automatically
        required: true
        in: query
        schema:
          type: string
      - name: if-match
        description: Only return the file if the current ETag matches one of the values provided
        in: header
        schema:
          type: string
      - name: if-none-match
        description: Only return the file if the current ETag does not match any of the values provided
        in: header
        schema:
          type: string
      - name: if-modified-since
        description: Only return the file if it has been modified after the given date
        in: header
        schema:
          $ref: '#/components/schemas/RFC2822Date'
      - name: if-unmodified-since
        description: Only return the file if it has not been modified after the given date
        in: header
        schema:
          $ref: '#/components/schemas/RFC2822Date'
      - name: q
        description: Image quality (1-100). Only applies to JPEG, WebP and PNG files
        in: query
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: h
        description: Maximum height to resize image to while maintaining aspect ratio. Only applies to image files
        in: query
        schema:
          type: integer
          minimum: 1
      - name: w
        description: Maximum width to resize image to while maintaining aspect ratio. Only applies to image files
        in: query
        schema:
          type: integer
          minimum: 1
      - name: b
        description: Blur the image using this sigma value. Only applies to image files
        in: query
        schema:
          type: number
          minimum: 0
      - name: f
        description: Output format for image files. Use 'auto' for content negotiation based on Accept header
        in: query
        schema:
          $ref: '#/components/schemas/OutputImageFormat'
      - name: Range
        description: 'Range of bytes to retrieve from the file. Format: bytes=start-end'
        in: header
        schema:
          type: string
          pattern: ^bytes=(\d+-\d*|\d*-\d+)(,(\d+-\d*|\d*-\d+))*$
      responses:
        '200':
          description: File content retrieved successfully
          headers:
            Cache-Control:
              description: Directives for caching mechanisms
              schema:
                type: string
            Content-Type:
              description: MIME type of the file
              schema:
                type: string
            Etag:
              description: Entity tag for cache validation
              schema:
                type: string
            Content-Disposition:
              description: Indicates if the content should be displayed inline or as an attachment
              schema:
                type: string
            Last-Modified:
              description: Date and time the file was last modified
              schema:
                type: string
                format: date-time
            Surrogate-Key:
              description: Cache key for surrogate caching
              schema:
                type: string
            Surrogate-Control:
              description: Cache control directives for surrogate caching
              schema:
                type: string
            Accept-Ranges:
              description: Always set to bytes. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Ranges
              schema:
                type: string
          content:
            application/octet-stream: {}
        '206':
          description: Partial file content retrieved successfully
          headers:
            Cache-Control:
              description: Directives for caching mechanisms
              schema:
                type: string
            Content-Type:
              description: MIME type of the file
              schema:
                type: string
            Content-Range:
              description: Range of bytes returned in the response
              schema:
                type: string
            Etag:
              description: Entity tag for cache validation
              schema:
                type: string
            Content-Disposition:
              description: Indicates if the content should be displayed inline or as an attachment
              schema:
                type: string
            Last-Modified:
              description: Date and time the file was last modified
              schema:
                type: string
                format: date-time
            Surrogate-Key:
              description: Cache key for surrogate caching
              schema:
                type: string
            Surrogate-Control:
              description: Cache control directives for surrogate caching
              schema:
                type: string
          content:
            application/octet-stream: {}
        '304':
          description: File not modified since the condition specified in If-Modified-Since or If-None-Match headers
          headers:
            Cache-Control:
              description: Directives for caching mechanisms
              schema:
                type: string
            Etag:
              description: Entity tag for cache validation
              schema:
                type: string
            Surrogate-Control:
              description: Cache control directives for surrogate caching
              schema:
                type: string
        '412':
          description: Precondition failed for conditional request headers (If-Match, If-Unmodified-Since, If-None-Match)
          headers:
            Cache-Control:
              description: Directives for caching mechanisms
              schema:
                type: string
            Etag:
              description: Entity tag for cache validation
              schema:
                type: string
            Surrogate-Control:
              description: Cache control directives for surrogate caching
              schema:
                type: string
        default:
          description: Error occurred
          headers:
            X-Error:
              description: Error message details
              schema:
                type: string
components:
  schemas:
    ErrorResponse:
      type: object
      description: Error information returned by the API.
      properties:
        error:
          type: object
          additionalProperties: false
          description: Error details.
          properties:
            message:
              type: string
              description: Human-readable error message.
              example: File not found
            data:
              type: object
              additionalProperties: true
              description: Additional data related to the error, if any.
          required:
          - message
      additionalProperties: false
    OutputImageFormat:
      type: string
      description: Output format for image files. Use 'auto' for content negotiation based on Accept header
      default: same
      enum:
      - auto
      - same
      - jpeg
      - webp
      - png
      - avif
      example: same
    RFC2822Date:
      type: string
      description: Date in RFC 2822 format
      pattern: ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{1,2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} \w+$
      example: Tue, 12 Aug 2025 12:03:50 GMT
      x-go-type: Time
    PresignedURLResponse:
      type: object
      description: Contains a presigned URL for direct file operations.
      properties:
        url:
          type: string
          description: The presigned URL for file operations.
          example: https://storage.example.com/files/abc123?signature=xyz
        expiration:
          type: integer
          description: The time in seconds until the URL expires.
          example: 3600
      required:
      - url
      - expiration
      additionalProperties: false
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Bearer authentication with JWT access token. Used to authenticate requests to protected endpoints.
    BearerAuthElevated:
      type: http
      scheme: bearer
      description: Bearer authentication that requires elevated permissions. Used for sensitive operations that may require additional security measures such as recent authentication. For details see https://docs.nhost.io/guides/auth/elevated-permissions