Files
aios/docs/gitops/openapi-chatgpt-actions.yaml
T

570 lines
22 KiB
YAML

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