openapi: 3.0.3
info:
    title: Yasno API
    description: Yasno API description
    contact:
        name: Alexander Myasnikov
        url: https://amyasnikov.com
        email: myasnikov.alexander@gmail.com
    license:
        name: MIT
        url: https://opensource.org/licenses/MIT
    version: v0.4.0-3-g3d29d49
servers:
    - url: https://yasno.coolify.amyasnikov.com
      description: Production server (amyasnikov.com)
    - url: https://yasno.onrender.com
      description: Production server (Render.com)
    - url: http://127.0.0.1:8080
      description: Development server
paths:
    /{filepath}:
        get:
            tags:
                - front
            summary: Download static
            operationId: front#/{filepath}
            parameters:
                - name: filepath
                  in: path
                  description: Relative file path
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    description: File downloaded
                "404":
                    description: File not found
    /api/v1/auth/signup:
        post:
            tags:
                - core
            summary: createUser core
            operationId: core#createUser
            parameters:
                - name: X-Request-Id
                  in: header
                  description: Unique request identifier for idempotency and client-server correlation.
                  allowEmptyValue: true
                  schema:
                    type: string
                    description: Unique request identifier for idempotency and client-server correlation.
                    example: 1b44e28a-c8e8-4f3c-96fb-8da106cf1c09
                  example: 1b44e28a-c8e8-4f3c-96fb-8da106cf1c09
                - name: X-Metadata
                  in: header
                  description: Configuration metadata exchanged between client and server as a key-value string.
                  allowEmptyValue: true
                  schema:
                    type: string
                    description: Configuration metadata exchanged between client and server as a key-value string.
                    example: debug=true,cache=off,timeout=5s
                  example: debug=true,cache=off,timeout=5s
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateUserRequest2'
                        example:
                            password: Pas@word!-m35r1u
                            username: alice
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateUserResponse'
                            example:
                                userId: 310d4fea-4794-4085-9a0d-fc1d358f8748
                                username: alice
                "202":
                    description: Accepted response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateUserResponse'
                            example:
                                userId: 310d4fea-4794-4085-9a0d-fc1d358f8748
                                username: alice
                "400":
                    description: 'bad_request: Bad Request response.'
                    content:
                        application/vnd.yasno.error+json:
                            schema:
                                $ref: '#/components/schemas/YasnoError'
                            example:
                                category: bad_request
                                code: auth.token.expired
                                details:
                                    field: email
                                    reason: invalid_format
                                message: Your session has expired. Please log in again.
                "500":
                    description: 'internal_error: Internal Server Error response.'
                    content:
                        application/vnd.yasno.error+json:
                            schema:
                                $ref: '#/components/schemas/YasnoError'
                            example:
                                category: bad_request
                                code: auth.token.expired
                                details:
                                    field: email
                                    reason: invalid_format
                                message: Your session has expired. Please log in again.
            security:
                - apiKey_header_Authorization: []
    /api/v1/auth/signup_sync:
        post:
            tags:
                - core
            summary: createUserSync core
            operationId: core#createUserSync
            parameters:
                - name: X-Request-Id
                  in: header
                  description: Unique request identifier for idempotency and client-server correlation.
                  allowEmptyValue: true
                  schema:
                    type: string
                    description: Unique request identifier for idempotency and client-server correlation.
                    example: 1b44e28a-c8e8-4f3c-96fb-8da106cf1c09
                  example: 1b44e28a-c8e8-4f3c-96fb-8da106cf1c09
                - name: X-Metadata
                  in: header
                  description: Configuration metadata exchanged between client and server as a key-value string.
                  allowEmptyValue: true
                  schema:
                    type: string
                    description: Configuration metadata exchanged between client and server as a key-value string.
                    example: debug=true,cache=off,timeout=5s
                  example: debug=true,cache=off,timeout=5s
            requestBody:
                required: true
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateUserSyncRequest2'
                        example:
                            password: Pas@word!-m35r1u
                            username: alice
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/CreateUserSyncResponse'
                            example:
                                userId: 310d4fea-4794-4085-9a0d-fc1d358f8748
                                username: alice
                "400":
                    description: 'bad_request: Bad Request response.'
                    content:
                        application/vnd.yasno.error+json:
                            schema:
                                $ref: '#/components/schemas/YasnoError'
                            example:
                                category: bad_request
                                code: auth.token.expired
                                details:
                                    field: email
                                    reason: invalid_format
                                message: Your session has expired. Please log in again.
                "401":
                    description: 'unauthorized: Unauthorized response.'
                    content:
                        application/vnd.yasno.error+json:
                            schema:
                                $ref: '#/components/schemas/YasnoError'
                            example:
                                category: bad_request
                                code: auth.token.expired
                                details:
                                    field: email
                                    reason: invalid_format
                                message: Your session has expired. Please log in again.
                "500":
                    description: 'internal_error: Internal Server Error response.'
                    content:
                        application/vnd.yasno.error+json:
                            schema:
                                $ref: '#/components/schemas/YasnoError'
                            example:
                                category: bad_request
                                code: auth.token.expired
                                details:
                                    field: email
                                    reason: invalid_format
                                message: Your session has expired. Please log in again.
            security:
                - apiKey_header_Authorization: []
    /health:
        get:
            tags:
                - core
            summary: health core
            description: Health check
            operationId: core#health
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                type: string
                                default: todo
                                example: todo
                            example: todo
                "500":
                    description: 'internal_error: Internal Server Error response.'
                    content:
                        application/vnd.yasno.error+json:
                            schema:
                                $ref: '#/components/schemas/YasnoError'
                            example:
                                category: bad_request
                                code: auth.token.expired
                                details:
                                    field: email
                                    reason: invalid_format
                                message: Your session has expired. Please log in again.
            security:
                - apiKey_header_Authorization: []
    /metadata:
        get:
            tags:
                - core
            summary: metadata core
            description: Технические данные об экземпляре сервиса
            operationId: core#metadata
            responses:
                "200":
                    description: OK response.
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/MetadataResponse'
                            example:
                                appName: yasno
                                arch: amd64
                                branch: master
                                buildTime: "2026-05-31T22:19:13Z"
                                hostname: api-node-01
                                instanceId: 044b850f-0554-4cd0-8496-75d91b8efc99
                                os: linux
                                publicUrl: https://api-node-01.example.com
                                startedAt: "2026-04-08T00:14:34+03:00"
                                version: v0.3.4-44-g95fa72d
                "500":
                    description: 'internal_error: Internal Server Error response.'
                    content:
                        application/vnd.yasno.error+json:
                            schema:
                                $ref: '#/components/schemas/YasnoError'
                            example:
                                category: bad_request
                                code: auth.token.expired
                                details:
                                    field: email
                                    reason: invalid_format
                                message: Your session has expired. Please log in again.
            security:
                - apiKey_header_Authorization: []
    /ping:
        get:
            tags:
                - core
            summary: ping core
            description: Ping
            operationId: core#ping
            responses:
                "200":
                    description: OK response.
                    content:
                        text/plain:
                            schema:
                                type: string
                                default: ""
                                example: pong
                            example: pong
                "500":
                    description: 'internal_error: Internal Server Error response.'
                    content:
                        application/vnd.yasno.error+json:
                            schema:
                                $ref: '#/components/schemas/YasnoError'
                            example:
                                category: bad_request
                                code: auth.token.expired
                                details:
                                    field: email
                                    reason: invalid_format
                                message: Your session has expired. Please log in again.
            security:
                - apiKey_header_Authorization: []
components:
    schemas:
        CreateUserRequest:
            type: object
            properties:
                metadata:
                    type: string
                    description: Configuration metadata exchanged between client and server as a key-value string.
                    example: debug=true,cache=off,timeout=5s
                password:
                    type: string
                    description: User's password, must meet security requirements.
                    example: Pas@word!-m35r1u
                requestId:
                    type: string
                    description: Unique request identifier for idempotency and client-server correlation.
                    example: 1b44e28a-c8e8-4f3c-96fb-8da106cf1c09
                token:
                    type: string
                    description: API key used to perform authorization.
                    example: 6e687a55-fd0e-4a31-9136-eb9f4346b24f
                username:
                    type: string
                    description: Unique login name chosen by the user.
                    example: alice
            description: CreateUserRequest is the request type for the CreateUser operation
            example:
                metadata: debug=true,cache=off,timeout=5s
                password: Pas@word!-m35r1u
                requestId: 1b44e28a-c8e8-4f3c-96fb-8da106cf1c09
                token: 6e687a55-fd0e-4a31-9136-eb9f4346b24f
                username: alice
            required:
                - username
                - password
        CreateUserRequest2:
            type: object
            properties:
                password:
                    type: string
                    description: User's password, must meet security requirements.
                    example: Pas@word!-m35r1u
                username:
                    type: string
                    description: Unique login name chosen by the user.
                    example: alice
            example:
                password: Pas@word!-m35r1u
                username: alice
            required:
                - username
                - password
        CreateUserResponse:
            type: object
            properties:
                userId:
                    type: string
                    description: System-generated unique identifier for the user.
                    example: 310d4fea-4794-4085-9a0d-fc1d358f8748
                    format: uuid
                username:
                    type: string
                    description: Unique login name chosen by the user.
                    example: alice
            description: CreateUserResponse is the response type for the CreateUser operation
            example:
                userId: 310d4fea-4794-4085-9a0d-fc1d358f8748
                username: alice
            required:
                - userId
                - username
        CreateUserSyncRequest:
            type: object
            properties:
                metadata:
                    type: string
                    description: Configuration metadata exchanged between client and server as a key-value string.
                    example: debug=true,cache=off,timeout=5s
                password:
                    type: string
                    description: User's password, must meet security requirements.
                    example: Pas@word!-m35r1u
                requestId:
                    type: string
                    description: Unique request identifier for idempotency and client-server correlation.
                    example: 1b44e28a-c8e8-4f3c-96fb-8da106cf1c09
                token:
                    type: string
                    description: API key used to perform authorization.
                    example: 6e687a55-fd0e-4a31-9136-eb9f4346b24f
                username:
                    type: string
                    description: Unique login name chosen by the user.
                    example: alice
            example:
                metadata: debug=true,cache=off,timeout=5s
                password: Pas@word!-m35r1u
                requestId: 1b44e28a-c8e8-4f3c-96fb-8da106cf1c09
                token: 6e687a55-fd0e-4a31-9136-eb9f4346b24f
                username: alice
            required:
                - username
                - password
        CreateUserSyncRequest2:
            type: object
            properties:
                password:
                    type: string
                    description: User's password, must meet security requirements.
                    example: Pas@word!-m35r1u
                username:
                    type: string
                    description: Unique login name chosen by the user.
                    example: alice
            example:
                password: Pas@word!-m35r1u
                username: alice
            required:
                - username
                - password
        CreateUserSyncResponse:
            type: object
            properties:
                userId:
                    type: string
                    description: System-generated unique identifier for the user.
                    example: 310d4fea-4794-4085-9a0d-fc1d358f8748
                    format: uuid
                username:
                    type: string
                    description: Unique login name chosen by the user.
                    example: alice
            description: CreateUserSyncResponse is the response type for the CreateUser operation
            example:
                userId: 310d4fea-4794-4085-9a0d-fc1d358f8748
                username: alice
            required:
                - userId
                - username
        MetadataResponse:
            type: object
            properties:
                appName:
                    type: string
                    description: Название сервиса
                    example: yasno
                arch:
                    type: string
                    description: Архитектура операционной системы
                    example: amd64
                branch:
                    type: string
                    description: Название ветки
                    example: master
                buildTime:
                    type: string
                    description: Время сборки
                    example: "2026-05-31T22:19:13Z"
                hostname:
                    type: string
                    description: Имя хоста
                    example: api-node-01
                instanceId:
                    type: string
                    description: Уникальный ID запущенного экземпляра
                    example: 044b850f-0554-4cd0-8496-75d91b8efc99
                os:
                    type: string
                    description: Операционная система
                    example: linux
                publicUrl:
                    type: string
                    description: Public URL
                    example: https://api-node-01.example.com
                startedAt:
                    type: string
                    description: Время запуска сервиса
                    example: "2026-04-08T00:14:34+03:00"
                    format: date-time
                version:
                    type: string
                    description: Версия приложения
                    example: v0.3.4-44-g95fa72d
            example:
                appName: yasno
                arch: amd64
                branch: master
                buildTime: "2026-05-31T22:19:13Z"
                hostname: api-node-01
                instanceId: 044b850f-0554-4cd0-8496-75d91b8efc99
                os: linux
                publicUrl: https://api-node-01.example.com
                startedAt: "2026-04-08T00:14:34+03:00"
                version: v0.3.4-44-g95fa72d
            required:
                - appName
                - instanceId
                - startedAt
                - arch
                - os
                - hostname
                - publicUrl
                - version
                - branch
                - buildTime
        YasnoError:
            type: object
            properties:
                category:
                    type: string
                    description: High-level error category for quick classification.
                    example: bad_request
                code:
                    type: string
                    description: Unique machine-readable error code in <domain>.<subdomain>.<type> format.
                    example: auth.token.expired
                details:
                    type: object
                    description: Granular error details (e.g., validation errors per field).
                    example:
                        field: email
                        reason: invalid_format
                    additionalProperties: true
                message:
                    type: string
                    description: Human-readable description of the error, suitable for UI display.
                    example: Your session has expired. Please log in again.
            description: Standard API error
            example:
                category: bad_request
                code: auth.token.expired
                details:
                    field: email
                    reason: invalid_format
                message: Your session has expired. Please log in again.
            required:
                - category
                - code
                - message
    securitySchemes:
        apiKey_header_Authorization:
            type: apiKey
            description: 'Введите ваш токен в формате: Bearer <token>'
            name: Authorization
            in: header
tags:
    - name: front
      description: Frontend pages and static content
    - name: core
      description: Core endpoints
