openapi: 3.1.0
info:
  title: Neuro Editor API
  version: 1.0.0
  description: |
    Платная обработка текста с тарификацией за начатые 1000 символов.
    Лимит - 60 запросов в минуту на один API-ключ (ответ 429).
    Коды ошибок в поле code: validation_error (422), insufficient_balance (402), idempotency_conflict (409), ai_unavailable (503).
servers:
  - url: https://editor.classnyisait.ru/api/v1
paths:
  /text/correct:
    post:
      summary: Исправление текста
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 255 } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string, minLength: 1, maxLength: 10000 }
                lang: { type: string }
                apply: { type: boolean, default: true }
      responses:
        '200': { description: Результат и данные списания, content: { application/json: { schema: { $ref: '#/components/schemas/ProcessResponse' } } } }
        '401': { $ref: '#/components/responses/Error' }
        '402': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
  /text/translate:
    post:
      summary: Перевод текста
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 255 } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text, target_language]
              properties:
                text: { type: string, minLength: 1, maxLength: 10000 }
                target_language: { type: string, minLength: 2, maxLength: 64 }
      responses:
        '200': { description: Результат и данные списания, content: { application/json: { schema: { $ref: '#/components/schemas/ProcessResponse' } } } }
        '401': { $ref: '#/components/responses/Error' }
        '402': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
  /text/improve:
    post:
      summary: Улучшение текста
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 255 } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string, minLength: 1, maxLength: 10000 }
      responses:
        '200': { description: Результат и данные списания, content: { application/json: { schema: { $ref: '#/components/schemas/ProcessResponse' } } } }
        '401': { $ref: '#/components/responses/Error' }
        '402': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
  /text/custom:
    post:
      summary: Обработка своей инструкцией
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 255 } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text, instruction]
              properties:
                text: { type: string, minLength: 1, maxLength: 10000 }
                instruction: { type: string, minLength: 1, maxLength: 300 }
      responses:
        '200': { description: Результат и данные списания, content: { application/json: { schema: { $ref: '#/components/schemas/ProcessResponse' } } } }
        '401': { $ref: '#/components/responses/Error' }
        '402': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
  /text/suggest-reply:
    post:
      summary: Подсказка ответа
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 255 } }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [text]
              properties:
                text: { type: string, minLength: 1, maxLength: 10000 }
      responses:
        '200': { description: Результат и данные списания, content: { application/json: { schema: { $ref: '#/components/schemas/ProcessResponse' } } } }
        '401': { $ref: '#/components/responses/Error' }
        '402': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
  /text/styles/{style_id}:
    post:
      summary: Стилизация общим серверным пресетом
      description: Промпт выбирается сервером. В теле передаётся только текст; подмена style_id или instruction запрещена.
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 255 } }
        - name: style_id
          in: path
          required: true
          schema:
            type: string
            enum: [corporate, formal, friendly, short, expand, simple, zen, yoda, biblical, viking, shakespeare, sarcastic, business, marketing, emoji]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [text]
              properties:
                text: { type: string, minLength: 1, maxLength: 10000 }
      responses:
        '200': { description: Результат и данные списания, content: { application/json: { schema: { $ref: '#/components/schemas/ProcessResponse' } } } }
        '401': { $ref: '#/components/responses/Error' }
        '402': { $ref: '#/components/responses/Error' }
        '404': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
  /text/process:
    post:
      operationId: processText
      security:
        - bearerAuth: []
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string, maxLength: 255 }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: '#/components/schemas/CorrectRequest'
                - $ref: '#/components/schemas/ImproveRequest'
                - $ref: '#/components/schemas/TranslateRequest'
                - $ref: '#/components/schemas/SuggestReplyRequest'
              discriminator:
                propertyName: operation
      responses:
        '200': { description: Результат и данные списания, content: { application/json: { schema: { $ref: '#/components/schemas/ProcessResponse' } } } }
        '401': { $ref: '#/components/responses/Error' }
        '402': { $ref: '#/components/responses/Error' }
        '409': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
        '503': { $ref: '#/components/responses/Error' }
  /portals/welcome-bonus:
    post:
      summary: Приветственный бонус 100 ₽ за первое подключение портала Битрикс24
      description: Бонус начисляется один раз на портал. Аккаунт владельца ключа должен иметь подтверждённый email (иначе 403). Портал подтверждается проверкой публичного адреса по HTTPS.
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [portal_host, challenge]
              properties:
                module_code: { type: string, enum: [classnyisait.ai.editor, classnyisait.aieditor] }
                portal_host: { type: string, maxLength: 253 }
                challenge: { type: string, pattern: '^[a-f0-9]{64}$' }
      responses:
        '200': { description: Бонус начислен или уже использован, content: { application/json: { schema: { type: object, properties: { credited_kopecks: { type: integer }, balance_kopecks: { type: integer } } } } } }
        '401': { $ref: '#/components/responses/Error' }
        '403': { $ref: '#/components/responses/Error' }
        '422': { $ref: '#/components/responses/Error' }
        '429': { $ref: '#/components/responses/Error' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
  schemas:
    BaseRequest:
      type: object
      required: [operation, text]
      properties:
        text: { type: string, minLength: 1, maxLength: 10000 }
    CorrectRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          required: [operation]
          properties: { operation: { const: correct } }
    ImproveRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          required: [operation]
          properties:
            operation: { const: improve }
            style_id: { type: string, maxLength: 64 }
            instruction: { type: string, maxLength: 300 }
    SuggestReplyRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          required: [operation]
          properties: { operation: { const: suggest_reply } }
    TranslateRequest:
      allOf:
        - $ref: '#/components/schemas/BaseRequest'
        - type: object
          required: [operation, target_language]
          properties:
            operation: { const: translate }
            target_language: { type: string, minLength: 2, maxLength: 64 }
    ProcessResponse:
      type: object
      required: [id, operation, result, characters, charged_units, charged_amount, balance, currency]
      properties:
        id: { type: string }
        operation: { enum: [correct, improve, translate, suggest_reply] }
        result: { type: string }
        characters: { type: integer }
        charged_units: { type: integer, description: Число начатых блоков по 1000 символов }
        charged_amount: { type: integer, description: Списано, копейки }
        balance: { type: integer, description: Баланс после списания, копейки }
        currency: { const: RUB }
    Error:
      type: object
      properties:
        code: { type: string }
        message: { type: string }
  responses:
    Error:
      description: Ошибка запроса
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }