openapi: 3.1.0
info:
  title: AIOS GitOps Controlled Access API
  version: V1R1C0-chatgpt-actions
  description: Controlled ChatGPT Actions API for AIOS online GitOps baseline. Read endpoints are public. Write endpoints require Bearer token and create Git commits on non-main branches.
servers:
  - url: https://cnnetmkt.top
security: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque-token
  schemas:
    BranchRequest:
      type: object
      required: [branch]
      properties:
        branch: {type: string, example: patch/chatgpt-actions-demo}
        base: {type: string, default: main}
        message: {type: string}
    FileCommitRequest:
      type: object
      required: [branch, path, content]
      properties:
        branch: {type: string}
        base: {type: string, default: main}
        create_branch: {type: boolean, default: false}
        path: {type: string, example: docs/gitops/chatgpt-change.md}
        content: {type: string}
        message: {type: string}
    CommitRequest:
      type: object
      properties:
        branch: {type: string}
        paths:
          type: array
          items: {type: string}
        message: {type: string}
    PatchRequest:
      type: object
      required: [patch_name]
      properties:
        patch_name: {type: string}
        branch: {type: string}
        base: {type: string, default: main}
        risk: {type: string, enum: [low, medium, high]}
        description: {type: string}
        message: {type: string}
    TagRequest:
      type: object
      required: [version]
      properties:
        version: {type: string, example: V1R1C1}
        message: {type: string}
        execute:
          type: boolean
          description: Owner-approved calls only. Otherwise an approval request commit is created.
    RollbackRequest:
      type: object
      required: [target_version]
      properties:
        target_version: {type: string}
        reason: {type: string}
        branch: {type: string}
    ModelRequest:
      type: object
      required: [provider_name, base_url, model_name]
      properties:
        username: {type: string}
        provider_name: {type: string}
        base_url: {type: string}
        model_name: {type: string}
        display_name: {type: string}
        api_key_secret_ref:
          type: string
          description: Preferred. Git stores this secret_ref only.
        api_key:
          type: string
          writeOnly: true
          description: Accepted only for runtime secret storage; never committed to Git or logs.
        branch: {type: string}
        message: {type: string}
    ModelPriorityRequest:
      type: object
      required: [items]
      properties:
        username: {type: string}
        branch: {type: string}
        items:
          type: array
          items:
            type: object
            properties:
              model_id: {type: string}
              priority: {type: integer}
              enabled: {type: boolean}
              fallback_policy: {type: string}
    NLRequest:
      type: object
      required: [text]
      properties:
        text: {type: string}
        branch: {type: string}
paths:
  /api/base:
    get:
      operationId: getBaseline
      summary: Read current AIOS baseline
      responses: {'200': {description: OK}}
  /api/ver:
    get:
      operationId: listVersions
      summary: List GitOps versions
      responses: {'200': {description: OK}}
  /api/diff:
    get:
      operationId: getDiff
      summary: Read Git diff between refs
      parameters:
        - in: query
          name: from
          schema: {type: string, default: HEAD~1}
        - in: query
          name: to
          schema: {type: string, default: HEAD}
      responses: {'200': {description: OK}}
  /api/patch:
    get:
      operationId: listPatches
      summary: List patch records
      responses: {'200': {description: OK}}
    post:
      operationId: createPatch
      summary: Create a patch branch and commit metadata
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/PatchRequest'}
      responses: {'200': {description: Patch branch committed}, '401': {description: Unauthorized}, '403': {description: Forbidden}}
  /api/model:
    get:
      operationId: readModelRegistry
      summary: Read visible model registry and priority
      responses: {'200': {description: OK}}
    post:
      operationId: registerModel
      summary: Register a custom model; API keys are stored as runtime secrets and Git receives secret_ref only
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ModelRequest'}
      responses: {'200': {description: Model registered and committed}, '401': {description: Unauthorized}, '403': {description: Forbidden}}
  /api/run:
    get:
      operationId: getRuntimeStatus
      summary: Read runtime status
      responses: {'200': {description: OK}}
  /api/branch:
    post:
      operationId: createBranch
      summary: Create a non-main branch and commit branch metadata
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/BranchRequest'}
      responses: {'200': {description: Branch created}, '401': {description: Unauthorized}, '403': {description: Forbidden}}
  /api/file:
    post:
      operationId: commitFile
      summary: Write a file and create a Git commit on a non-main branch
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/FileCommitRequest'}
      responses: {'200': {description: File committed}, '400': {description: Secret rejected or invalid path}, '401': {description: Unauthorized}}
  /api/commit:
    post:
      operationId: commitChanges
      summary: Commit existing workspace changes on a non-main branch
      security: [{bearerAuth: []}]
      requestBody:
        required: false
        content:
          application/json:
            schema: {$ref: '#/components/schemas/CommitRequest'}
      responses: {'200': {description: Commit result}, '401': {description: Unauthorized}}
  /api/tag:
    post:
      operationId: requestOrCreateTag
      summary: Request tag creation; owner execution is required for direct tag
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/TagRequest'}
      responses: {'200': {description: Tag request committed or tag created}, '403': {description: Forbidden}}
  /api/rollback:
    post:
      operationId: requestRollback
      summary: Commit a rollback request requiring owner/admin approval
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/RollbackRequest'}
      responses: {'200': {description: Rollback request committed}, '401': {description: Unauthorized}}
  /api/model-priority:
    put:
      operationId: setModelPriority
      summary: Set model priority and commit policy file
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ModelPriorityRequest'}
      responses: {'200': {description: Priority updated and committed}, '401': {description: Unauthorized}}
  /api/nl:
    post:
      operationId: planNaturalLanguageGitOpsAction
      summary: Convert natural language to a safe committed plan without executing V-level changes
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/NLRequest'}
      responses: {'200': {description: Plan committed}, '401': {description: Unauthorized}}