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:
    PublicationState:
      type: string
      description: Canonical durable publication state. Legacy TAG_CREATED_LOCAL is normalized on read and is never emitted by new writes.
      enum:
        - PENDING
        - LOCAL_TAG_CREATED
        - REMOTE_PUSH_PENDING
        - REMOTE_PUSH_CONFIRMED
        - GITEA_API_CONFIRMED
        - BASELINE_UPDATE_PENDING
        - BASELINE_UPDATED
        - PRODUCTION_DEPLOYED
        - RECONCILIATION_REQUIRED
        - MANUAL_OWNER_REVIEW_REQUIRED
    PublicationStatus:
      type: object
      required: [version, state]
      properties:
        version: {type: string}
        state: {$ref: '#/components/schemas/PublicationState'}
        fail_closed: {type: boolean}
    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}
    AtomicFileCommitRequest:
      type: object
      additionalProperties: false
      required: [branch, path, content, message, expected_head_oid, idempotency_key]
      properties:
        branch:
          type: string
          pattern: '^patch/[A-Za-z0-9._/-]+$'
        path:
          type: string
          minLength: 1
          maxLength: 512
        content:
          type: string
          maxLength: 1048576
        message:
          type: string
          minLength: 1
          maxLength: 200
        expected_head_oid:
          type: string
          pattern: '^[0-9a-f]{40}$'
        idempotency_key:
          type: string
          pattern: '^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$'
    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, target_oid, evidence_closure_oid, approval_plan_id]
      properties:
        version: {type: string, example: V1R1C1}
        target_oid:
          type: string
          pattern: '^[0-9a-fA-F]{40}$'
          description: Full approved commit OID. The tag is created explicitly at this commit, never implicitly at workspace HEAD.
        evidence_closure_oid:
          type: string
          pattern: '^[0-9a-fA-F]{40}$'
          description: Required evidence closure commit. target_oid must be its ancestor.
        approval_plan_id:
          type: string
          description: Audited owner-approved release or tag plan identifier.
        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}
    DeploymentPlan:
      type: object
      required: [service, release_path, release_root, cutover_link, dropin_path, dropin_sha256, systemd_unit_sha256, rollback_path, rollback_sha256, source_commit, tree_oid, artifact_sha256, manifest_sha256, package_closure_sha256, authoritative_git_dir, repository_identity, writer_expected, baseline_before_sha256, registry_before_sha256, production_tag_refset_before_sha256, health_contract_version, timeout_policy, retry_policy, policy_sha256, health_contract]
      properties:
        service: {type: string}
        release_path: {type: string}
        release_root: {type: string}
        cutover_link: {type: string}
        dropin_path: {type: string}
        dropin_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        systemd_unit_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        rollback_path: {type: string}
        rollback_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        source_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
        tree_oid: {type: string, pattern: '^[0-9a-f]{40}$'}
        artifact_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        manifest_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        package_closure_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        authoritative_git_dir: {type: string}
        repository_identity: {type: string}
        writer_expected: {type: boolean, enum: [false]}
        baseline_before_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        registry_before_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        production_tag_refset_before_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        health_contract_version: {type: string}
        timeout_policy: {type: object}
        retry_policy: {type: object}
        policy_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        health_contract: {type: object, additionalProperties: true}
    ReleaseCandidateInput:
      type: object
      required: [source_commit, version]
      additionalProperties: false
      properties:
        candidate_id: {type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.-]{2,127}$'}
        source_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
        version: {type: string, pattern: '^V[0-9]+R[0-9]+C[0-9]+(?:[-.][A-Za-z0-9][A-Za-z0-9.-]*)?$'}
    ReleaseIntentInput:
      type: object
      required: [event_id, source_commit]
      additionalProperties: false
      properties:
        event_id: {type: string, pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{2,255}$'}
        source_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
    SignedReleasePlanApproval:
      type: object
      required: [release_plan_id, candidate_id, source_commit, tree_oid, artifact_sha256, manifest_sha256, deployment_plan_sha256, release_plan_sha256, policy_sha256, approval_plan_id, evidence_closure_oid, owner_approval_record_oid, capabilities, owner_identity, trust_domain, issued_at, not_before, expires_at, nonce, key_id, signature]
      properties:
        release_plan_id: {type: string}
        candidate_id: {type: string}
        source_commit: {type: string, pattern: '^[0-9a-f]{40}$'}
        tree_oid: {type: string, pattern: '^[0-9a-f]{40}$'}
        artifact_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        manifest_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        deployment_plan_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        release_plan_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        policy_sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        approval_plan_id: {type: string}
        evidence_closure_oid: {type: string, pattern: '^[0-9a-f]{40}$'}
        owner_approval_record_oid: {type: string, pattern: '^[0-9a-f]{40}$'}
        owner_identity: {type: string}
        trust_domain: {type: string}
        issued_at: {type: string, format: date-time}
        not_before: {type: string, format: date-time}
        capabilities:
          type: array
          uniqueItems: true
          items:
            type: string
            enum: [runtime_switch, tag_publish, baseline_registry_finalize]
        expires_at: {type: string, format: date-time}
        nonce: {type: string, minLength: 16}
        key_id: {type: string}
        signature: {type: string, format: byte, writeOnly: true}
    StartDeploymentRequest:
      type: object
      required: [candidate_id]
      additionalProperties: false
      properties:
        candidate_id: {type: string}
paths:
  /createReleaseIntent:
    post:
      operationId: createReleaseIntent
      summary: Create an idempotent intent; all build evidence comes from the trusted builder
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ReleaseIntentInput'}
      responses:
        '200': {description: Intent created or idempotently returned}
        '400': {description: Caller evidence or invalid intent rejected}
      x-openai-isConsequential: true
  /createReleaseCandidate:
    post:
      operationId: createReleaseCandidate
      summary: Submit release intent to the trusted builder; caller evidence is rejected
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/ReleaseCandidateInput'}
      responses:
        '200': {description: Candidate created or idempotently returned}
        '400': {description: Invalid or conflicting candidate evidence}
        '401': {description: Unauthorized}
      x-openai-isConsequential: true
  /getReleaseCandidate:
    get:
      operationId: getReleaseCandidate
      summary: Read a durable release candidate
      parameters:
        - {in: query, name: candidate_id, required: true, schema: {type: string}}
      responses:
        '200': {description: Candidate}
        '404': {description: Candidate not found}
  /getReleasePlan:
    get:
      operationId: getReleasePlan
      parameters:
        - {in: query, name: candidate_id, required: true, schema: {type: string}}
      responses:
        '200': {description: Immutable release plan}
        '404': {description: Candidate not found}
  /getReleaseAcceptance:
    get:
      operationId: getReleaseAcceptance
      parameters:
        - {in: query, name: candidate_id, required: true, schema: {type: string}}
      responses:
        '200': {description: Builder attestation and acceptance checks}
        '404': {description: Candidate not found}
  /getApprovalEnvelope:
    get:
      operationId: getApprovalEnvelope
      summary: Generate the immutable owner-signature payload
      parameters:
        - {in: query, name: candidate_id, required: true, schema: {type: string}}
      responses:
        '200': {description: Approval envelope fingerprint inputs}
        '404': {description: Candidate not found}
  /submitOwnerApproval:
    post:
      operationId: submitOwnerApproval
      summary: Verify and durably store a signed owner release plan
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SignedReleasePlanApproval'}
      responses:
        '200': {description: Signature verified and approval stored}
        '400': {description: Invalid approval}
        '403': {description: Signature, key, expiry, or revocation failure}
        '409': {description: Conflicting release plan}
      x-openai-isConsequential: true
  /submitSignedApproval:
    post:
      operationId: submitSignedApproval
      summary: Alias for immutable signed owner approval submission
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SignedReleasePlanApproval'}
      responses:
        '200': {description: Signature verified and approval stored}
        '403': {description: Production approval backend unavailable or signature invalid}
      x-openai-isConsequential: true
  /startDeployment:
    post:
      operationId: startDeployment
      summary: Resume the durable approved Saga; caller cannot replace approval
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/StartDeploymentRequest'}
      responses:
        '200': {description: Shadow result or deployment Saga result}
        '403': {description: Execution disabled or approval invalid}
        '409': {description: Saga conflict}
      x-openai-isConsequential: true
  /getReleaseSaga:
    get:
      operationId: getReleaseSaga
      summary: Read durable Saga state and event journal
      parameters:
        - {in: query, name: candidate_id, required: true, schema: {type: string}}
      responses:
        '200': {description: Saga snapshot}
        '404': {description: Saga not found}
  /getCapabilityStatus:
    get:
      operationId: getCapabilityStatus
      parameters:
        - {in: query, name: candidate_id, required: true, schema: {type: string}}
      responses:
        '200': {description: Durable single-use capability records}
  /getRecoveryStatus:
    get:
      operationId: getRecoveryStatus
      responses:
        '200': {description: Fail-closed recovery classification}
  /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}}
      x-openai-isConsequential: true
  /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}}
      x-openai-isConsequential: true
  /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}}
      x-openai-isConsequential: true
  /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}}
      x-openai-isConsequential: true
  /api/commit-file:
    post:
      operationId: commitFileAtomic
      summary: Atomically write one allowlisted file, commit, push, and verify using Token Policy V2
      security: [{bearerAuth: []}]
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/AtomicFileCommitRequest'}
      responses:
        '200': {description: Completed or idempotently replayed}
        '400': {description: Invalid canonical request}
        '401': {description: Missing, invalid, expired, or revoked Token Policy V2 grant}
        '403': {description: Audience, source, branch, operation, path, or policy denied}
        '409': {description: Idempotency conflict or manual review required}
        '413': {description: Request too large}
        '503': {description: Push or remote verification unavailable; recoverable}
      x-openai-isConsequential: true
  /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}}
      x-openai-isConsequential: true
  /api/tag-publication-status:
    get:
      operationId: getTagPublicationStatus
      summary: Read durable publication Saga status without mutation
      parameters:
        - {in: query, name: version, required: true, schema: {type: string, pattern: '^V\d+R\d+C\d+(?:-[A-Za-z0-9_.-]+)?$'}}
      responses:
        '200':
          description: Canonical publication state or fail-closed UNKNOWN
          content:
            application/json:
              schema: {$ref: '#/components/schemas/PublicationStatus'}
        '400': {description: Version required}
  /api/release-consistency:
    get:
      operationId: getReleaseConsistency
      summary: Compare Registry, Baseline, remote tag, Gitea API, listing, repository identity, and expected target
      parameters:
        - {in: query, name: version, required: true, schema: {type: string}}
        - {in: query, name: target_oid, required: true, schema: {type: string, pattern: '^[0-9a-fA-F]{40}$'}}
        - {in: query, name: evidence_closure_oid, required: true, schema: {type: string, pattern: '^[0-9a-fA-F]{40}$'}}
        - {in: query, name: approval_plan_id, required: true, schema: {type: string}}
      responses: {'200': {description: PASS, FAIL, or fail-closed UNKNOWN}}
  /api/release-acceptance:
    get:
      operationId: runReleaseAcceptance
      summary: Run read-only release acceptance; UNKNOWN is not accepted
      parameters:
        - {in: query, name: version, required: true, schema: {type: string}}
        - {in: query, name: target_oid, required: true, schema: {type: string, pattern: '^[0-9a-fA-F]{40}$'}}
        - {in: query, name: evidence_closure_oid, required: true, schema: {type: string, pattern: '^[0-9a-fA-F]{40}$'}}
        - {in: query, name: approval_plan_id, required: true, schema: {type: string}}
      responses: {'200': {description: Acceptance result with accepted boolean}}
  /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: Gitea-confirmed tag and fail-closed baseline result}, '400': {description: Missing governance evidence or invalid OID}, '403': {description: Forbidden}, '409': {description: Existing tag target conflict or evidence lineage mismatch}, '502': {description: Gitea reconciliation required}, '503': {description: Remote push pending}}
      x-openai-isConsequential: true
  /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}}
      x-openai-isConsequential: true
  /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}}
      x-openai-isConsequential: true
  /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: Safe GitOps plan}
        '401': {description: Unauthorized}
      x-openai-isConsequential: true