openapi.yaml

openapi: 3.1.0
info:
  title: GPT Gateway
  description: FastAPI middleware to list, read, write, and recursively scan GitHub repositories. Enables GPT to navigate file structures and edit code.
  version: 1.0.1

servers:
  - url: https://nomena-gpt.xyz/
    description: GPT Gateway API root

paths:
  /list-files/:
    get:
      operationId: listFiles
      summary: List files in a GitHub repository path
      description: Return a flat list of files and folders in a given path of a GitHub repository.
      parameters:
        - name: owner
          in: query
          required: true
          description: GitHub username or organization
          schema:
            type: string
        - name: repo
          in: query
          required: true
          description: Repository name
          schema:
            type: string
        - name: path
          in: query
          required: false
          description: Path inside the repository
          schema:
            type: string
            default: ""
        - name: branch
          in: query
          required: false
          description: Git branch name
          schema:
            type: string
            default: main
      responses:
        "200":
          description: List of file and folder objects
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  path:
                    type: string
                  files:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        path:
                          type: string
                        type:
                          type: string
                      required:
                        - name
                        - path
                        - type

  /read-file/:
    get:
      operationId: readFile
      summary: Read contents of a file from a GitHub repository
      parameters:
        - name: owner
          in: query
          required: true
          description: GitHub username or organization
          schema:
            type: string
        - name: repo
          in: query
          required: true
          description: Repository name
          schema:
            type: string
        - name: path
          in: query
          required: true
          description: Full path to the file in the repo
          schema:
            type: string
        - name: branch
          in: query
          required: false
          description: Branch name
          schema:
            type: string
            default: main
      responses:
        "200":
          description: File content
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  path:
                    type: string
                  content:
                    type: string

  /write-file/:
    put:
      operationId: writeFile
      summary: Write or update a file in a GitHub repository
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - owner
                - repo
                - path
                - branch
                - content
                - message
              properties:
                owner:
                  type: string
                repo:
                  type: string
                branch:
                  type: string
                path:
                  type: string
                content:
                  type: string
                message:
                  type: string
                author_name:
                  type: string
                author_email:
                  type: string
      responses:
        "200":
          description: File written successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  result:
                    type: object

  /scan-repo/:
    post:
      operationId: scanRepo
      summary: Recursively scan a GitHub repository and return its file tree
      description: Returns the full recursive structure of a GitHub repository starting from the given path. **Note:** The tree is shown up to two levels deep in this schema for -compatibility.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - owner
                - repo
              properties:
                owner:
                  type: string
                  example: nomenarkt
                repo:
                  type: string
                  example: lamina
                path:
                  type: string
                  example: ""
                branch:
                  type: string
                  example: main
                depth:
                  type: integer
                  example: 2
      responses:
        "200":
          description: Recursive file tree
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                  tree:
                    type: array
                    items:
                      $ref: "#/components/schemas/TreeNode"

components:
  schemas:
    TreeNode:
      type: object
      properties:
        name:
          type: string
        path:
          type: string
        type:
          type: string
        children:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
              path:
                type: string
              type:
                type: string
              # Recursion stops here for tool compatibility; see docs for recursive structure.