openapi: 3.0.3
info:
  title: Open Kyrgyz API
  description: REST API for Kyrgyz verb conjugation and noun declension
  version: 2.0.0
  license:
    name: MIT

servers:
  - url: https://open-kyrgyz.kg/api
    description: Production

paths:
  /v1/verbs/conjugations/{verb}:
    get:
      summary: Conjugate a Kyrgyz verb
      parameters:
        - name: verb
          in: path
          required: true
          schema:
            type: string
          description: Verb stem in Kyrgyz Cyrillic (e.g. бар, кел, жаз)
        - name: tenses
          in: query
          required: false
          schema:
            type: string
          description: |
            Comma-separated list of tenses/sections to include. Omit for all.
            Tense values: PresentAndFuture, PresentContinuous, FutureProbable, FutureGoingTo,
            PastDefinite, PastIndefinite, PastUsedTo, PastSudden, Conditional, Intention
            Special values: Imperative, Optative
            Example: tenses=PastDefinite,Imperative
        - name: forms
          in: query
          required: false
          schema:
            type: string
          description: |
            Comma-separated verb forms to include. Omit for all.
            Values: Positive, Negative, Interrogative, NegativeAndInterrogative
        - name: includeMoods
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Include passive, reflexive, cooperative moods
        - name: includeVerbForms
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include verb forms (gerund, participle, cause, goal, etc.)
        - name: includeTimeForms
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include time-related forms (when, while, before, after, etc.)
      responses:
        '200':
          description: Conjugation result
          content:
            application/json:
              schema:
                type: object
                properties:
                  verb:
                    type: string
                  tenses:
                    type: array
                    items:
                      type: object
                  imperatives:
                    type: object
                  optative:
                    type: object
                  moods:
                    type: object
                  verbForms:
                    type: object
                  timeForms:
                    type: object
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /v1/nouns/declensions/{noun}:
    get:
      summary: Decline a Kyrgyz noun
      parameters:
        - name: noun
          in: path
          required: true
          schema:
            type: string
          description: Noun in Kyrgyz Cyrillic (e.g. үй, бала, китеп)
        - name: includeCases
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Include singular and plural declensions across 6 cases
        - name: includePossessive
          in: query
          required: false
          schema:
            type: boolean
            default: true
          description: Include possessive forms with full case declensions for all 7 pronouns
        - name: includeCopula
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Include copula (to be) forms for all 8 pronouns
      responses:
        '200':
          description: Declension result
          content:
            application/json:
              schema:
                type: object
                properties:
                  noun:
                    type: string
                  cases:
                    type: object
                  possessive:
                    type: object
                  copula:
                    type: array
                    items:
                      type: object
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
