portal/api/s5/swagger.yaml

openapi: 3.0.0
info:
    title: S5 Storage API
    version: "1.0"
paths:
    # Account API
    /s5/account/register:
        get:
            summary: Initiate account registration
            security: []
            parameters:
                - name: pubKey
                  description: Public key of the account
                  in: query
                  required: true
                  schema:
                    type: string
            responses:
                '200':
                    description: Registration challenge
        post:
            summary: Complete account registration
            security: []
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AccountRegisterRequest'
            responses:
                '201':
                    description: Account created
    /s5/account/login:
        get:
            summary: Initiate account login
            security: []
            parameters:
                - name: pubKey
                  description: Public key of the account
                  in: query
                  required: true
                  schema:
                    type: string
            responses:
                '200':
                    description: Login challenge
        post:
            summary: Complete account login
            security: []
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/AccountLoginRequest'
            responses:
                '200':
                    description: Login successful
    /s5/account:
        get:
            summary: Retrieve account information
            responses:
                '200':
                    description: Account information
    /s5/account/stats:
        get:
            summary: Retrieve account statistics
            responses:
                '200':
                    description: Account statistics
                    content:
                        application/json:
                            schema:
                                $ref: "#/components/schemas/AccountStatsResponse"
    /s5/account/pins.bin:
        get:
            summary: Retrieve account pins
            responses:
                '200':
                    description: Account pins

    # Upload API
    /s5/upload:
        post:
            summary: Upload a small file
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            properties:
                                file:
                                    type: string
                                    format: binary
                    application/octet-stream:
                        schema:
                            type: string
                            format: binary
            responses:
                '200':
                    description: File uploaded
                '500':
                    description: Error uploading file
    /s5/upload/directory:
        post:
            summary: Upload a directory
            description: >
                This endpoint accepts multiple files in a multipart/form-data request.
                Each file can be uploaded under its own field name, which the server will process dynamically.
                The endpoint also accepts additional query parameters such as `tryfiles` and `errorpages` to configure the upload behavior.
            parameters:
                - name: tryFiles
                  in: query
                  required: true
                  schema:
                    $ref: '#/components/schemas/UploadRequestTryFiles'
                - name: errorPages
                  in: query
                  required: true
                  schema:
                    $ref: '#/components/schemas/UploadRequestErrorPages'
                - name: name
                  in: query
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            type: object
                            additionalProperties:
                                type: string
                                format: binary

            responses:
                '201':
                    description: Directory uploaded

    # Tus API
    /s5/upload/tus:
        post:
            summary: TUS Upload
            description: >
                An empty POST request is used to create a new upload resource. The
                Upload-Length header indicates the size of the entire upload in bytes.
                If the Creation With Upload extension is available, the Client MAY include
                parts of the upload in the initial Creation request
            parameters:
                -   name: Content-Length
                    in: header
                    description: Must be 0 for creation extension. May be a positive number for
                        Creation With Upload extension.
                    schema:
                        type: integer
                -   name: Upload-Length
                    in: header
                    schema:
                        $ref: "#/components/schemas/Upload-Length"
                -   name: Tus-Resumable
                    in: header
                    schema:
                        $ref: "#/components/schemas/Tus-Resumable"
                -   name: Upload-Metadata
                    in: header
                    description: Added by the Creation extension. The Upload-Metadata request
                        and response header MUST consist of one or more comma-separated key-value
                        pairs. The key and value MUST be separated by a space. The key MUST NOT
                        contain spaces and commas and MUST NOT be empty. The key SHOULD be ASCII
                        encoded and the value MUST be Base64 encoded. All keys MUST be unique. The
                        value MAY be empty. In these cases, the space, which would normally separate
                        the key and the value, MAY be left out. Since metadata can contain arbitrary
                        binary values, Servers SHOULD carefully validate metadata values or sanitize
                        them before using them as header values to avoid header smuggling.
                    schema:
                        type: string
                -   name: Upload-Concat
                    in: header
                    description: Added by the Concatenation extension. The Upload-Concat request
                        and response header MUST be set in both partial and final upload creation
                        requests. It indicates whether the upload is either a partial or final upload.
                        If the upload is a partial one, the header value MUST be partial. In the
                        case of a final upload, its value MUST be final followed by a semicolon
                        and a space-separated list of partial upload URLs that will be concatenated.
                        The partial uploads URLs MAY be absolute or relative and MUST NOT contain
                        spaces as defined in RFC 3986.
                    schema:
                        type: string
                -   name: Upload-Defer-Length
                    in: header
                    description: Added by the Creation Defer Length extension. The Upload-Defer-Length
                        request and response header indicates that the size of the upload is not
                        known currently and will be transferred later. Its value MUST be 1. If the
                        length of an upload is not deferred, this header MUST be omitted.
                    schema:
                        type: integer
                        enum:
                            - 1
                -   name: Upload-Offset
                    in: header
                    schema:
                        $ref: "#/components/schemas/Upload-Offset"
                -   name: Upload-Checksum
                    in: header
                    schema:
                        $ref: "#/components/schemas/Upload-Checksum"
            requestBody:
                description: (Possibly partial) content of the file. Required if Content-Length > 0.
                required: false
                content:
                    application/offset+octet-stream:
                        schema:
                            type: string
                            format: binary
            responses:
                201:
                    description: Created
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Upload-Offset:
                            schema:
                                $ref: "#/components/schemas/Upload-Offset"
                        Upload-Expires:
                            description: Added by the Creation With Upload Extension in combination
                                with the expiration extension. The Upload-Expires response header
                                indicates the time after which the unfinished upload expires. A Server
                                MAY wish to remove incomplete uploads after a given period of time
                                to prevent abandoned uploads from taking up extra storage. The Client
                                SHOULD use this header to determine if an upload is still valid before
                                attempting to resume the upload. This header MUST be included in every
                                PATCH response if the upload is going to expire. If the expiration
                                is known at the creation, the Upload-Expires header MUST be included
                                in the response to the initial POST request. Its value MAY change
                                over time. If a Client does attempt to resume an upload which has
                                since been removed by the Server, the Server SHOULD respond with the
                                404 Not Found or 410 Gone status. The latter one SHOULD be used if
                                the Server is keeping track of expired uploads. In both cases the
                                Client SHOULD start a new upload. The value of the Upload-Expires
                                header MUST be in RFC 7231 datetime format.
                            schema:
                                type: string
                        Location:
                            description: Url of the created resource.
                            schema:
                                type: string
                400:
                    description: Added by the Creation With Upload Extension in combination
                        with the checksum extension. The checksum algorithm is not supported by
                        the server
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                412:
                    description: Precondition Failed
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Tus-Version:
                            schema:
                                $ref: "#/components/schemas/Tus-Version"
                413:
                    description: If the length of the upload exceeds the maximum, which MAY
                        be specified using the Tus-Max-Size header, the Server MUST respond with
                        the 413 Request Entity Too Large status.
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                415:
                    description: Added by the Creation With Upload Extension. Content-Type was
                        not application/offset+octet-stream
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                460:
                    description: Added by the Creation With Upload Extension in combination
                        with the checksum extension. Checksums mismatch
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
        options:
            summary: Request to gather information about the Server's current configuration
            description: An OPTIONS request MAY be used to gather information about the
                Server's current configuration. A successful response indicated by the 204
                No Content or 200 OK status MUST contain the Tus-Version header. It MAY include
                the Tus-Extension and Tus-Max-Size headers.
            responses:
                200:
                    description: Success
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Tus-Checksum-Algorithm:
                            schema:
                                $ref: "#/components/schemas/Tus-Checksum-Algorithm"
                        Tus-Version:
                            schema:
                                $ref: "#/components/schemas/Tus-Version"
                        Tus-Max-Size:
                            schema:
                                $ref: "#/components/schemas/Tus-Max-Size"
                        Tus-Extension:
                            schema:
                                $ref: "#/components/schemas/Tus-Extension"
                204:
                    description: Success
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Tus-Checksum-Algorithm:
                            schema:
                                $ref: "#/components/schemas/Tus-Checksum-Algorithm"
                        Tus-Version:
                            schema:
                                $ref: "#/components/schemas/Tus-Version"
                        Tus-Max-Size:
                            schema:
                                $ref: "#/components/schemas/Tus-Max-Size"
                        Tus-Extension:
                            schema:
                                $ref: "#/components/schemas/Tus-Extension"
    /s5/upload/tus/{id}:
        delete:
            summary: Added by the Termination extension.
            description: When receiving a DELETE request for an existing upload the Server
                SHOULD free associated resources and MUST respond with the 204 No Content
                status confirming that the upload was terminated. For all future requests
                to this URL, the Server SHOULD respond with the 404 Not Found or 410 Gone
                status.
            operationId: FilesDelete
            parameters:
                -   name: id
                    in: path
                    required: true
                    schema:
                        type: string
                -   name: Tus-Resumable
                    in: header
                    required: true
                    schema:
                        $ref: "#/components/schemas/Tus-Resumable"
            responses:
                204:
                    description: Upload was terminated
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                412:
                    description: Precondition Failed
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Tus-Version:
                            schema:
                                $ref: "#/components/schemas/Tus-Version"
        head:
            summary: Used to determine the offset at which the upload should be continued.
            description: Used to determine the offset at which the upload should be continued.
            operationId: FilesHead
            parameters:
                -   name: id
                    in: path
                    required: true
                    schema:
                        type: string
                -   name: Tus-Resumable
                    in: header
                    required: true
                    schema:
                        $ref: "#/components/schemas/Tus-Resumable"
            responses:
                200:
                    description: Returns offset
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Cache-Control:
                            schema:
                                type: string
                                enum:
                                    - no-store
                        Upload-Offset:
                            schema:
                                $ref: "#/components/schemas/Upload-Offset"
                        Upload-Length:
                            schema:
                                $ref: "#/components/schemas/Upload-Length"
                403:
                    description: If the resource is not found, the Server SHOULD return either
                        the 404 Not Found, 410 Gone or 403 Forbidden status without the Upload-Offset
                        header.
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                404:
                    description: If the resource is not found, the Server SHOULD return either
                        the 404 Not Found, 410 Gone or 403 Forbidden status without the Upload-Offset
                        header.
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                410:
                    description: If the resource is not found, the Server SHOULD return either
                        the 404 Not Found, 410 Gone or 403 Forbidden status without the Upload-Offset
                        header.
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                412:
                    description: Precondition Failed
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Tus-Version:
                            schema:
                                $ref: "#/components/schemas/Tus-Version"
        patch:
            summary: Used to resume the upload
            description: 'The Server SHOULD accept PATCH requests against any upload URL
        and apply the bytes contained in the message at the given offset specified
        by the Upload-Offset header. All PATCH requests MUST use Content-Type: application/offset+octet-stream,
        otherwise the server SHOULD return a 415 Unsupported Media Type status.'
            operationId: FilePatch
            parameters:
                -   name: id
                    in: path
                    required: true
                    schema:
                        type: string
                -   name: Tus-Resumable
                    in: header
                    required: true
                    schema:
                        $ref: "#/components/schemas/Tus-Resumable"
                -   name: Content-Length
                    in: header
                    description: Length of the body of this request
                    required: true
                    schema:
                        type: integer
                -   name: Upload-Offset
                    in: header
                    required: true
                    schema:
                        $ref: "#/components/schemas/Upload-Offset"
                -   name: Upload-Checksum
                    in: header
                    schema:
                        $ref: "#/components/schemas/Upload-Checksum"
            requestBody:
                description: Remaining (possibly partial) content of the file. Required if Content-Length > 0.
                required: false
                content:
                    application/offset+octet-stream:
                        schema:
                            type: string
                            format: binary
            responses:
                204:
                    description: Upload offset was updated
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Upload-Offset:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Upload-Expires:
                            description: Added by the expiration extension. The Upload-Expires response
                                header indicates the time after which the unfinished upload expires.
                                A Server MAY wish to remove incomplete uploads after a given period
                                of time to prevent abandoned uploads from taking up extra storage.
                                The Client SHOULD use this header to determine if an upload is still
                                valid before attempting to resume the upload. This header MUST be
                                included in every PATCH response if the upload is going to expire.
                                If the expiration is known at the creation, the Upload-Expires header
                                MUST be included in the response to the initial POST request. Its
                                value MAY change over time. If a Client does attempt to resume an
                                upload which has since been removed by the Server, the Server SHOULD
                                respond with the 404 Not Found or 410 Gone status. The latter one
                                SHOULD be used if the Server is keeping track of expired uploads.
                                In both cases the Client SHOULD start a new upload. The value of the
                                Upload-Expires header MUST be in RFC 7231 datetime format.
                            schema:
                                type: string
                400:
                    description: Added by the checksum extension. The checksum algorithm is
                        not supported by the server
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                403:
                    description: In the concatenation extension, the Server MUST respond with
                        the 403 Forbidden status to PATCH requests against a final upload URL
                        and MUST NOT modify the final or its partial uploads.
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                404:
                    description: PATCH request against a non-existent resource
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                409:
                    description: PATCH request with Upload-Offset unequal to the offset of the resource on the server. The Upload-Offset header's value MUST be equal to the current offset of the resource.
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                410:
                    description: PATCH request against a non-existent resource
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                412:
                    description: Precondition Failed
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                        Tus-Version:
                            schema:
                                $ref: "#/components/schemas/Tus-Version"
                415:
                    description: Content-Type was not application/offset+octet-stream
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"
                460:
                    description: Added by the checksum extension. Checksums mismatch
                    headers:
                        Tus-Resumable:
                            schema:
                                $ref: "#/components/schemas/Tus-Resumable"

    # Download API
    /s5/blob/{cid}:
        get:
            summary: Retrieve a blob
            responses:
                '302':
                    description: Redirecting to discovered blob url
    /s5/metadata/{cid}:
        get:
            summary: Retrieve file metadata
            description: >
                * Resolvers are currently not supported

                * Raw files don't have metadata
            responses:
                '200':
                    description: File metadata
                    content:
                        application/json:
                            schema:
                                type: object
    /s5/download/{cid}:
        get:
            summary: Download a file
            responses:
                '200':
                    description: File content
                    content:
                        application/octet-stream:
                            schema:
                                type: string
                                format: binary

    # Pins API
    /s5/pin/{cid}:
        post:
            summary: Pin a file
            responses:
                '204':
                    description: File pinned
    /s5/delete/{cid}:
        delete:
            summary: Delete a file. This will only unpin it from the account, and potentially delete it later if there are no more global pins.
            responses:
                '204':
                    description: File deleted

    # Debug API
    /s5/debug/download_urls/{cid}:
        get:
            summary: Retrieve download URLs
            parameters:
                - name: hash
                  in: query
                  required: true
                  schema:
                    type: string
                    description: This is base64 url encoded
                - name: kinds
                  in: query
                  required: false
                  schema:
                    type: string
                    description: This is a comma separated list of kinds, which are integer identifiers.
            responses:
                '200':
                    description: Download URLs
                    content:
                        text/plain:
                            schema:
                                type: string
    /s5/debug/storage_locations/{hash}:
        get:
            summary: Retrieve storage locations
            responses:
                '200':
                    description: Storage locations
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/DebugStorageLocationsResponse'
    # Registry API
    /s5/registry:
        get:
            summary: Retrieve a registry entry
            parameters:
                - name: pk
                  description: Public key of the registry entry
                  in: query
                  required: true
                  schema:
                      type: string
            responses:
                '200':
                    description: Registry entry
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/RegistryQueryResponse'
        post:
            summary: Create or update a registry entry
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/RegistrySetRequest'
            responses:
                '200':
                    description: Registry entry set
    /s5/registry/subscription:
        post:
            summary: Listen for websocket updates for a given registry entry
            requestBody:
                content:
                    text/plain:
                        schema:
                            nullable: true
            responses:
                '200':
                    description: Success
components:
    schemas:
        AccountRegisterChallengeResponse:
            type: object
            properties:
                challenge:
                    type: string
        AccountRegisterRequest:
            type: object
            properties:
                pubkey:
                    type: string
                    description: This is base64 url encoded
                response:
                    type: string
                    description: This is base64 url encoded
                signature:
                    type: string
                    description: This is base64 url encoded
                email:
                    type: string
            required:
                - pubkey
                - response
                - signature
        AccountLoginChallengeResponse:
            type: object
            properties:
                challenge:
                    type: string
                    description: This is base64 url encoded
        AccountLoginRequest:
            type: object
            properties:
                pubkey:
                    type: string
                    description: This is base64 url encoded
                response:
                    type: string
                    description: This is base64 url encoded
                signature:
                    type: string
                    description: This is base64 url encoded
            required:
                - pubkey
                - response
                - signature
        BasicUploadResponse:
            type: object
            properties:
                CID:
                    type: string
        UploadRequestTryFiles:
            type: array
            items:
                type: string
        UploadRequestErrorPages:
            type: object
            additionalProperties:
                type: string
            description: >
                Object keys are expected to be string representations of integers (e.g., "404", "500"),
                with their values being strings. Due to limitations in the OpenAPI Specification,
                this pattern cannot be enforced through the schema and should be validated at runtime.
        AccountStats:
            type: object
            properties:
                total:
                    $ref: '#/components/schemas/AccountStatsTotal'
        AccountStatsTotal:
            type: object
            properties:
                usedStorage:
                    type: integer
        AccountTier:
            type: object
            properties:
                id:
                    type: integer
                name:
                    type: string
                uploadBandwidth:
                    type: integer
                storageLimit:
                    type: integer
                scopes:
                    type: array
                    additionalProperties: true
        AccountInfoResponse:
            type: object
            properties:
                email:
                    type: string
                quotaExceeded:
                    type: boolean
                emailConfirmed:
                    type: boolean
                isRestricted:
                    type: boolean
                tier:
                    $ref: '#/components/schemas/AccountTier'
        AccountStatsResponse:
            allOf:
                - $ref: "#/components/schemas/AccountInfoResponse"
                - type: object
                  properties:
                      stats:
                          $ref: "#/components/schemas/AccountStats"
        RegistryQueryResponse:
            type: object
            properties:
                pk:
                    type: string
                revision:
                    type: integer
                data:
                    type: string
                signature:
                    type: string
        RegistrySetRequest:
            type: object
            properties:
                pk:
                    type: string
                revision:
                    type: integer
                data:
                    type: string
                signature:
                    type: string
        DebugStorageLocationsResponse:
            type: object
            properties:
                locations:
                    type: array
                    items:
                        $ref: '#/components/schemas/DebugStorageLocation'
        DebugStorageLocation:
            type: object
            properties:
                location:
                    type: integer
                parts:
                    type: array
                    items:
                        type: string
                expiry:
                    type: integer
                nodeId:
                    type: string
                score:
                    type: integer
        Tus-Resumable:
            type: string
            enum:
                - 1.0.0
            description: Protocol version
        Tus-Version:
            description: The Tus-Version response header MUST be a comma-separated
                list of protocol versions supported by the Server. The list MUST be
                sorted by Server's preference where the first one is the most preferred
                one.
            type: string
        Tus-Extension:
            description: The Tus-Extension response header MUST be a comma-separated
                list of the extensions supported by the Server. If no extensions are
                supported, the Tus-Extension header MUST be omitted.
            type: string
        Tus-Max-Size:
            description: The Tus-Max-Size response header MUST be a non-negative
                integer indicating the maximum allowed size of an entire upload in
                bytes. The Server SHOULD set this header if there is a known hard
                limit.
            type: integer
        Upload-Length:
            description: The Upload-Length request and response header indicates the size
                of the entire upload in bytes. The value MUST be a non-negative integer.
                In the concatenation extension, the Client MUST NOT include the Upload-Length
                header in the final upload creation
            type: integer
        Upload-Offset:
            description: The Upload-Offset request and response header indicates
                a byte offset within a resource. The value MUST be a non-negative
                integer.
            type: integer

        Tus-Checksum-Algorithm:
            description: Added by the checksum extension. The Tus-Checksum-Algorithm
                response header MUST be a comma-separated list of the checksum algorithms
                supported by the server.
            type: string
        Upload-Checksum:
            description: Added by the checksum extension. The Upload-Checksum request
                header contains information about the checksum of the current body payload.
                The header MUST consist of the name of the used checksum algorithm and the
                Base64 encoded checksum separated by a space.
            type: string
    securitySchemes:
        BearerAuth:
            type: http
            scheme: bearer
            bearerFormat: JWT
        CookieAuth:
            type: apiKey
            in: cookie
            name: s5-auth-token
        QueryAuth:
            type: apiKey
            in: query
            name: s5-auth-token
security:
    - BearerAuth: []
    - CookieAuth: []
    - QueryAuth: []