openapi: "3.0.3"
info:
  title: Naas API
  description: A creative "no" generator API
  version: "1.0.0"
servers:
  - url: https://api.naas.lol
paths:
  /no:
    get:
      summary: Random no
      description: Returns a random creative way to say no. Filter by style or content mode. Get all available styles from /styles and all available modes from /modes.
      parameters:
        - name: style
          in: query
          required: false
          description: Filter by style. See /styles for all available styles.
          schema:
            type: string
        - name: mode
          in: query
          required: false
          description: |-
            Content mode. See /modes for all available modes. Defaults to safe.
            WARNING: nsfw and rogue modes contain adult language, not suitable around children or in professional settings. Authentication required for nsfw and rogue.
          schema:
            type: string
            enum: [safe, nsfw, rogue]
            default: safe
        - name: lang
          in: query
          required: false
          description: Filter by language name. See /languages for all available languages. Defaults to English. Authentication required for non-English languages.
          schema:
            type: string
      responses:
        "200":
          description: A random no
          content:
            application/json:
              schema:
                type: object
                required: [id, text, style, mode, language]
                properties:
                  id:
                    type: integer
                  text:
                    type: string
                  style:
                    type: string
                  mode:
                    type: string
                  language:
                    type: string
        "400":
          description: Unknown style parameter or invalid mode
        "401":
          description: Authentication required for nsfw/rogue mode
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
        "500":
          description: No data in database
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
  /languages:
    get:
      summary: List languages
      description: Lists all available languages you can use to filter responses.
      responses:
        "200":
          description: All available languages
          content:
            application/json:
              schema:
                type: object
                required: [languages]
                properties:
                  languages:
                    type: array
                    items:
                      type: string
  /modes:
    get:
      summary: List modes
      description: |-
        Lists all available content modes. safe is public.
        WARNING: nsfw and rogue modes contain adult language, keep away from children and professional environments. Authentication required for nsfw and rogue.
      responses:
        "200":
          description: All available modes
          content:
            application/json:
              schema:
                type: object
                required: [modes]
                properties:
                  modes:
                    type: array
                    items:
                      type: string
  /styles:
    get:
      summary: List styles
      description: Lists all available styles you can use to filter responses.
      responses:
        "200":
          description: All available styles
          content:
            application/json:
              schema:
                type: object
                required: [styles]
                properties:
                  styles:
                    type: array
                    items:
                      type: string
        "429":
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
  /count:
    get:
      summary: Count nos
      description: "Returns a nested breakdown of nos by language, style, and mode as { language: { style: { mode: count } } }. All parameters are optional — omit all to get the full breakdown, or filter to narrow which keys appear."
      parameters:
        - name: language
          in: query
          required: false
          description: Filter by language. See /languages for all available languages.
          schema:
            type: string
        - name: style
          in: query
          required: false
          description: Filter by style. See /styles for all available styles.
          schema:
            type: string
        - name: mode
          in: query
          required: false
          description: Filter by content mode (safe, nsfw, rogue).
          schema:
            type: string
            enum: [safe, nsfw, rogue]
      responses:
        "200":
          description: "Count breakdown. Shape is always { language: { style: { mode: count } } }. Params filter which keys appear."
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: object
                  additionalProperties:
                    type: object
                    additionalProperties:
                      type: integer
  /{path}:
    get:
      summary: Catch-all
      description: Any other path returns a 404 error.
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
      responses:
        "404":
          description: Not found
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string