OpenAPI Specification
openapi: 3.0.0
info:
version: 1.0.0
title: Nhost authentication files 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: files
description: File management operations
paths:
/files:
post:
summary: Upload files
description: Upload one or more files to a specified bucket. Supports batch uploading with optional custom metadata for each file. If uploading multiple files, either provide metadata for all files or none.
operationId: uploadFiles
tags:
- files
security:
- Authorization: []
requestBody:
description: File upload data including files and optional metadata
required: true
content:
multipart/form-data:
schema:
type: object
properties:
bucket-id:
type: string
description: Target bucket identifier where files will be stored.
example: user-uploads
metadata[]:
type: array
description: Optional custom metadata for each uploaded file. Must match the order of the file[] array.
items:
$ref: '#/components/schemas/UploadFileMetadata'
file[]:
description: Array of files to upload.
type: array
items:
type: string
format: binary
required:
- file[]
responses:
'201':
description: Files successfully uploaded
content:
application/json:
schema:
type: object
properties:
processedFiles:
type: array
description: List of successfully processed files with their metadata.
items:
$ref: '#/components/schemas/FileMetadata'
required:
- processedFiles
default:
description: Error occurred during upload
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponseWithProcessedFiles'
/files/{id}:
delete:
summary: Delete file
description: Permanently delete a file from storage. This removes both the file content and its associated metadata.
operationId: deleteFile
tags:
- files
security:
- Authorization: []
parameters:
- name: id
required: true
in: path
description: Unique identifier of the file to delete
schema:
type: string
responses:
'204':
description: File successfully deleted
default:
description: Error occurred during file deletion
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
get:
summary: Download file
description: Retrieve and download the complete file content. Supports conditional requests, image transformations, and range requests for partial downloads.
operationId: getFile
tags:
- files
security:
- Authorization: []
parameters:
- name: id
required: true
in: path
description: Unique identifier of the file to download
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
head:
summary: Check file information
description: Retrieve file metadata headers without downloading the file content. Supports conditional requests and provides caching information.
operationId: getFileMetadataHeaders
tags:
- files
security:
- Authorization: []
parameters:
- name: id
required: true
in: path
description: Unique identifier of the file to check
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'
responses:
'200':
description: File information headers 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-Length:
description: Size of the file in bytes
schema:
type: integer
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
Accept-Ranges:
description: Always set to bytes. https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Ranges
schema:
type: string
Surrogate-Key:
description: Cache key for surrogate caching
schema:
type: string
Surrogate-Control:
description: Cache control directives for surrogate caching
schema:
type: string
'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)
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
put:
summary: Replace file
description: 'Replace an existing file with new content while preserving the file ID. The operation follows these steps:
1. The isUploaded flag is set to false to mark the file as being updated
2. The file content is replaced in the storage backend
3. File metadata is updated (size, mime-type, isUploaded, etc.)
Each step is atomic, but if a step fails, previous steps will not be automatically rolled back.
'
operationId: replaceFile
tags:
- files
security:
- Authorization: []
parameters:
- name: id
required: true
in: path
description: Unique identifier of the file to replace
schema:
type: string
requestBody:
description: File replacement data including new file content and optional metadata
required: true
content:
multipart/form-data:
schema:
type: object
properties:
metadata:
$ref: '#/components/schemas/UpdateFileMetadata'
file:
description: New file content to replace the existing file
type: string
format: binary
responses:
'200':
description: File successfully replaced
content:
application/json:
schema:
$ref: '#/components/schemas/FileMetadata'
default:
description: Error occurred during file replacement
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
schemas:
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
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
FileMetadata:
type: object
description: Comprehensive metadata information about a file in storage.
properties:
id:
type: string
description: Unique identifier for the file.
example: d5e76ceb-77a2-4153-b7da-1f7c115b2ff2
name:
type: string
description: Name of the file including extension.
example: profile-picture.jpg
size:
description: Size of the file in bytes.
type: integer
format: int64
example: 245678
bucketId:
type: string
description: ID of the bucket containing the file.
example: users-bucket
etag:
type: string
description: Entity tag for cache validation.
example: '"a1b2c3d4e5f6"'
createdAt:
type: string
format: date-time
description: Timestamp when the file was created.
example: '2023-01-15T12:34:56Z'
updatedAt:
type: string
format: date-time
description: Timestamp when the file was last updated.
example: '2023-01-16T09:45:32Z'
isUploaded:
type: boolean
description: Whether the file has been successfully uploaded.
example: true
mimeType:
type: string
description: MIME type of the file.
example: image/jpeg
uploadedByUserId:
type: string
description: ID of the user who uploaded the file.
example: abc123def456
metadata:
type: object
additionalProperties: true
description: Custom metadata associated with the file.
example:
alt: Profile picture
category: avatar
required:
- id
- name
- size
- bucketId
- etag
- createdAt
- updatedAt
- isUploaded
- mimeType
additionalProperties: false
UploadFileMetadata:
type: object
description: Metadata provided when uploading a new file.
properties:
id:
type: string
description: Optional custom ID for the file. If not provided, a UUID will be generated.
example: custom-id-123
name:
type: string
description: Name to assign to the file. If not provided, the original filename will be used.
example: custom-filename.png
metadata:
type: object
additionalProperties: true
description: Custom metadata to associate with the file.
example:
alt: Custom image
category: document
additionalProperties: false
ErrorResponseWithProcessedFiles:
type: object
description: Error information returned by the API.
properties:
processedFiles:
type: array
description: List of files that were successfully processed before the error occurred.
items:
$ref: '#/components/schemas/FileMetadata'
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
UpdateFileMetadata:
type: object
description: Metadata that can be updated for an existing file.
properties:
name:
type: string
description: New name to assign to the file.
example: renamed-file.jpg
metadata:
type: object
additionalProperties: true
description: Updated custom metadata to associate with the file.
example:
alt: Updated image description
category: profile
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