Sovereign Git Forge + Scenario Soft API (EGOV-99) — OpenAPI 1.0.0-soft

Scope: The published reference for Sovereign Git Forge + Scenario Soft API (EGOV-99). 20 paths — the measured spec-vs-implementation coverage lives in the complete API inventory. Status: rendered 2026-11-09 from the OpenAPI source for Sovereign Git Forge + Scenario Soft API (EGOV-99) — regenerate with node scripts/render-platform-map-api-docs.mjs. See also: the OpenAPI spec index.

Servers

URL	Notes
http://127.0.0.1:3030	Agent BFF Soft

Tag	Summary
gitops	EGOV Soft pack plan/apply/health
git	Soft forge repos/PRs/compile
scenario	Soft scenarios/compositions
voyage	Soft voyage start (invent-refuse LIVE)
docs	Soft document history fabric (EGOV-123/124)
ops	Soft readiness

Paths — 20 paths / 21 operations

Method	Path	Operation ID	Summary
POST	/v1/realms/{realmId}/git/edit-pr	proposeEditPrSoft	Soft Edit→PR Soft (EGOV-42; invent-refuse LIVE)
POST	/v1/realms/{realmId}/gitops/overlay-preview	previewOverlaySoft	Soft branch/overlay preview Soft (EGOV-75; invent-refuse LIVE/widen)
GET	/v1/realms/{realmId}/git/prs	listGitPrsSoft	Soft PR list
GET	/v1/docs/families	listDocFamiliesSoft	Soft document families (EGOV-123)
GET	/v1/docs/families/{familyId}	getDocFamilySoft	Soft document family + Soft history stub
POST	/v1/docs/publish	publishDocSoft	Soft publish (invent-refuse LIVE)
GET	/v1/realms/{realmId}/gitops/pack-health	getGitopsPackHealthSoft	Soft pack health (EGOV-96)
GET	/v1/realms/{realmId}/gitops/governance/status	getGovernanceGitopsStatusSoft	Soft governance GitOps status
POST	/v1/realms/{realmId}/gitops/governance/apply	applyGovernanceGitopsSoft	Soft apply proposed pin (DSS-43 + GIT_PIN_MISMATCH)
GET	/v1/realms/{realmId}/git/repos	listGitReposSoft	Soft forge repo bindings
POST	/v1/realms/{realmId}/git/compile	compileGitSoft	Soft compile stub (invent-refuse LIVE)
GET	/v1/realms/{realmId}/scenarios	listScenariosSoft	Soft scenario index (Git SoT)
GET	/v1/realms/{realmId}/compositions	listCompositionsSoft	Soft composition list
GET	/v1/voyages	listVoyagesSoft	Soft voyage receipts
POST	/v1/voyages	startVoyageSoft	Soft voyage start (invent-refuse LIVE)
GET	/v1/voyages/{voyageId}	getVoyageSoft	Soft voyage detail
POST	/v1/voyages/{voyageId}/resume	resumeVoyageSoft	Soft voyage HITL resume (invent-refuse LIVE)
POST	/v1/voyages/{voyageId}/cancel	cancelVoyageSoft	Soft voyage cancel (invent-refuse LIVE)
GET	/v1/git-forge/ops/readiness	gitForgeReadinessSoft	Soft forge readiness (never claims LIVE)
GET	/v1/git-forge/openapi	gitForgeOpenApiSoft	Soft host OpenAPI fragment Soft (EGOV-99)
GET	/v1/git-forge/openapi/meta	gitForgeOpenApiMetaSoft	Soft OpenAPI meta Soft (path_count; invent-refuse LIVE publish)

Operations

POST /v1/realms/{realmId}/git/edit-pr

Summary: Soft Edit→PR Soft (EGOV-42; invent-refuse LIVE)

Tags: git Operation ID: proposeEditPrSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Responses:

Status	Meaning
200	Soft PR proposed
403	LIVE invent-refuse Soft

POST /v1/realms/{realmId}/gitops/overlay-preview

Summary: Soft branch/overlay preview Soft (EGOV-75; invent-refuse LIVE/widen)

Tags: gitops Operation ID: previewOverlaySoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Responses:

Status	Meaning
200	Soft overlay preview
403	LIVE or ceiling-widen invent-refuse Soft

GET /v1/realms/{realmId}/git/prs

Summary: Soft PR list

Tags: git Operation ID: listGitPrsSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string
state	query	no	string

Responses:

Status	Meaning
200	Soft PR list

GET /v1/docs/families

Summary: Soft document families (EGOV-123)

Tags: docs Operation ID: listDocFamiliesSoft Responses:

Status	Meaning
200	Soft family list

GET /v1/docs/families/{familyId}

Summary: Soft document family + Soft history stub

Tags: docs Operation ID: getDocFamilySoft

Parameters:

Name	In	Required	Type	Notes
familyId	path	yes	string

Responses:

Status	Meaning
200	Soft family
404	Not found Soft

POST /v1/docs/publish

Summary: Soft publish (invent-refuse LIVE)

Tags: docs Operation ID: publishDocSoft Responses:

Status	Meaning
200	Soft publish receipt
403	LIVE invent-refuse Soft

GET /v1/realms/{realmId}/gitops/pack-health

Summary: Soft pack health (EGOV-96)

Tags: gitops Operation ID: getGitopsPackHealthSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Responses:

Status	Meaning
200	Soft pack health

GET /v1/realms/{realmId}/gitops/governance/status

Summary: Soft governance GitOps status

Tags: gitops Operation ID: getGovernanceGitopsStatusSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Responses:

Status	Meaning
200	Soft status

POST /v1/realms/{realmId}/gitops/governance/apply

Summary: Soft apply proposed pin (DSS-43 + GIT_PIN_MISMATCH)

Tags: gitops Operation ID: applyGovernanceGitopsSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Request body:

Content type: application/json

Field	Type	Notes

Responses:

Status	Meaning
200	Soft apply receipt
403	invent_refuse LIVE or GIT_SIGNER_IS_PR_AUTHOR / GIT_PIN_MISMATCH

GET /v1/realms/{realmId}/git/repos

Summary: Soft forge repo bindings

Tags: git Operation ID: listGitReposSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Responses:

Status	Meaning
200	Soft repo list

POST /v1/realms/{realmId}/git/compile

Summary: Soft compile stub (invent-refuse LIVE)

Tags: git Operation ID: compileGitSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Responses:

Status	Meaning
200	Soft compile
403	GIT_LIVE_INVENT_REFUSED

GET /v1/realms/{realmId}/scenarios

Summary: Soft scenario index (Git SoT)

Tags: scenario Operation ID: listScenariosSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Responses:

Status	Meaning
200	Soft scenarios

GET /v1/realms/{realmId}/compositions

Summary: Soft composition list

Tags: scenario Operation ID: listCompositionsSoft

Parameters:

Name	In	Required	Type	Notes
realmId	path	yes	string

Responses:

Status	Meaning
200	Soft compositions

GET /v1/voyages

Summary: Soft voyage receipts

Tags: voyage Operation ID: listVoyagesSoft Responses:

Status	Meaning
200	Soft voyages

POST /v1/voyages

Summary: Soft voyage start (invent-refuse LIVE)

Tags: voyage Operation ID: startVoyageSoft Request body:

Content type: application/json

Field	Type	Notes

Responses:

Status	Meaning
200	Soft voyage started
403	GIT_LIVE_INVENT_REFUSED
422	SCENARIO_ENTITY_UNBOUND

GET /v1/voyages/{voyageId}

Summary: Soft voyage detail

Tags: voyage Operation ID: getVoyageSoft

Parameters:

Name	In	Required	Type	Notes
voyageId	path	yes	string

Responses:

Status	Meaning
200	Soft voyage
404	not found

POST /v1/voyages/{voyageId}/resume

Summary: Soft voyage HITL resume (invent-refuse LIVE)

Tags: voyage Operation ID: resumeVoyageSoft

Parameters:

Name	In	Required	Type	Notes
voyageId	path	yes	string

Responses:

Status	Meaning
200	Soft resumed
403	GIT_LIVE_INVENT_REFUSED
404	VOYAGE_NOT_FOUND

POST /v1/voyages/{voyageId}/cancel

Summary: Soft voyage cancel (invent-refuse LIVE)

Tags: voyage Operation ID: cancelVoyageSoft

Parameters:

Name	In	Required	Type	Notes
voyageId	path	yes	string

Responses:

Status	Meaning
200	Soft cancelled
403	GIT_LIVE_INVENT_REFUSED
404	VOYAGE_NOT_FOUND

GET /v1/git-forge/ops/readiness

Summary: Soft forge readiness (never claims LIVE)

Tags: ops Operation ID: gitForgeReadinessSoft Responses:

Status	Meaning
200	Soft readiness

GET /v1/git-forge/openapi

Summary: Soft host OpenAPI fragment Soft (EGOV-99)

Tags: ops Operation ID: gitForgeOpenApiSoft Responses:

Status	Meaning
200	Soft OpenAPI document Soft

GET /v1/git-forge/openapi/meta

Summary: Soft OpenAPI meta Soft (path_count; invent-refuse LIVE publish)

Tags: ops Operation ID: gitForgeOpenApiMetaSoft Responses:

Status	Meaning
200	Soft OpenAPI meta Soft

Full specification — verbatim source of truth

{
  "openapi": "3.0.3",
  "info": {
    "title": "Sovereign Git Forge + Scenario Soft API (EGOV-99)",
    "description": "Soft≠LIVE fragment for forge GitOps, scenarios, and voyages. Soft desks never invent LIVE. Normative contracts: docs/governance/event-orchestrated/10_FORGE_API_NATS_WEBHOOK_CONTRACTS.md",
    "version": "1.0.0-soft"
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3030",
      "description": "Agent BFF Soft"
    }
  ],
  "tags": [
    {
      "name": "gitops",
      "description": "EGOV Soft pack plan/apply/health"
    },
    {
      "name": "git",
      "description": "Soft forge repos/PRs/compile"
    },
    {
      "name": "scenario",
      "description": "Soft scenarios/compositions"
    },
    {
      "name": "voyage",
      "description": "Soft voyage start (invent-refuse LIVE)"
    },
    {
      "name": "docs",
      "description": "Soft document history fabric (EGOV-123/124)"
    },
    {
      "name": "ops",
      "description": "Soft readiness"
    }
  ],
  "paths": {
    "/v1/realms/{realmId}/git/edit-pr": {
      "post": {
        "tags": [
          "git"
        ],
        "operationId": "proposeEditPrSoft",
        "summary": "Soft Edit→PR Soft (EGOV-42; invent-refuse LIVE)",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft PR proposed"
          },
          "403": {
            "description": "LIVE invent-refuse Soft"
          }
        }
      }
    },
    "/v1/realms/{realmId}/gitops/overlay-preview": {
      "post": {
        "tags": [
          "gitops"
        ],
        "operationId": "previewOverlaySoft",
        "summary": "Soft branch/overlay preview Soft (EGOV-75; invent-refuse LIVE/widen)",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft overlay preview"
          },
          "403": {
            "description": "LIVE or ceiling-widen invent-refuse Soft"
          }
        }
      }
    },
    "/v1/realms/{realmId}/git/prs": {
      "get": {
        "tags": [
          "git"
        ],
        "operationId": "listGitPrsSoft",
        "summary": "Soft PR list",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft PR list"
          }
        }
      }
    },
    "/v1/docs/families": {
      "get": {
        "tags": [
          "docs"
        ],
        "operationId": "listDocFamiliesSoft",
        "summary": "Soft document families (EGOV-123)",
        "responses": {
          "200": {
            "description": "Soft family list"
          }
        }
      }
    },
    "/v1/docs/families/{familyId}": {
      "get": {
        "tags": [
          "docs"
        ],
        "operationId": "getDocFamilySoft",
        "summary": "Soft document family + Soft history stub",
        "parameters": [
          {
            "name": "familyId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft family"
          },
          "404": {
            "description": "Not found Soft"
          }
        }
      }
    },
    "/v1/docs/publish": {
      "post": {
        "tags": [
          "docs"
        ],
        "operationId": "publishDocSoft",
        "summary": "Soft publish (invent-refuse LIVE)",
        "responses": {
          "200": {
            "description": "Soft publish receipt"
          },
          "403": {
            "description": "LIVE invent-refuse Soft"
          }
        }
      }
    },
    "/v1/realms/{realmId}/gitops/pack-health": {
      "get": {
        "tags": [
          "gitops"
        ],
        "operationId": "getGitopsPackHealthSoft",
        "summary": "Soft pack health (EGOV-96)",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft pack health",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PackHealthSoft"
                }
              }
            }
          }
        }
      }
    },
    "/v1/realms/{realmId}/gitops/governance/status": {
      "get": {
        "tags": [
          "gitops"
        ],
        "operationId": "getGovernanceGitopsStatusSoft",
        "summary": "Soft governance GitOps status",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft status"
          }
        }
      }
    },
    "/v1/realms/{realmId}/gitops/governance/apply": {
      "post": {
        "tags": [
          "gitops"
        ],
        "operationId": "applyGovernanceGitopsSoft",
        "summary": "Soft apply proposed pin (DSS-43 + GIT_PIN_MISMATCH)",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApplyPinBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Soft apply receipt"
          },
          "403": {
            "description": "invent_refuse LIVE or GIT_SIGNER_IS_PR_AUTHOR / GIT_PIN_MISMATCH"
          }
        }
      }
    },
    "/v1/realms/{realmId}/git/repos": {
      "get": {
        "tags": [
          "git"
        ],
        "operationId": "listGitReposSoft",
        "summary": "Soft forge repo bindings",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft repo list"
          }
        }
      }
    },
    "/v1/realms/{realmId}/git/compile": {
      "post": {
        "tags": [
          "git"
        ],
        "operationId": "compileGitSoft",
        "summary": "Soft compile stub (invent-refuse LIVE)",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft compile"
          },
          "403": {
            "description": "GIT_LIVE_INVENT_REFUSED"
          }
        }
      }
    },
    "/v1/realms/{realmId}/scenarios": {
      "get": {
        "tags": [
          "scenario"
        ],
        "operationId": "listScenariosSoft",
        "summary": "Soft scenario index (Git SoT)",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft scenarios"
          }
        }
      }
    },
    "/v1/realms/{realmId}/compositions": {
      "get": {
        "tags": [
          "scenario"
        ],
        "operationId": "listCompositionsSoft",
        "summary": "Soft composition list",
        "parameters": [
          {
            "name": "realmId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft compositions"
          }
        }
      }
    },
    "/v1/voyages": {
      "get": {
        "tags": [
          "voyage"
        ],
        "operationId": "listVoyagesSoft",
        "summary": "Soft voyage receipts",
        "responses": {
          "200": {
            "description": "Soft voyages"
          }
        }
      },
      "post": {
        "tags": [
          "voyage"
        ],
        "operationId": "startVoyageSoft",
        "summary": "Soft voyage start (invent-refuse LIVE)",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VoyageStartBody"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Soft voyage started"
          },
          "403": {
            "description": "GIT_LIVE_INVENT_REFUSED"
          },
          "422": {
            "description": "SCENARIO_ENTITY_UNBOUND"
          }
        }
      }
    },
    "/v1/voyages/{voyageId}": {
      "get": {
        "tags": [
          "voyage"
        ],
        "operationId": "getVoyageSoft",
        "summary": "Soft voyage detail",
        "parameters": [
          {
            "name": "voyageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft voyage"
          },
          "404": {
            "description": "not found"
          }
        }
      }
    },
    "/v1/voyages/{voyageId}/resume": {
      "post": {
        "tags": [
          "voyage"
        ],
        "operationId": "resumeVoyageSoft",
        "summary": "Soft voyage HITL resume (invent-refuse LIVE)",
        "parameters": [
          {
            "name": "voyageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft resumed"
          },
          "403": {
            "description": "GIT_LIVE_INVENT_REFUSED"
          },
          "404": {
            "description": "VOYAGE_NOT_FOUND"
          }
        }
      }
    },
    "/v1/voyages/{voyageId}/cancel": {
      "post": {
        "tags": [
          "voyage"
        ],
        "operationId": "cancelVoyageSoft",
        "summary": "Soft voyage cancel (invent-refuse LIVE)",
        "parameters": [
          {
            "name": "voyageId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Soft cancelled"
          },
          "403": {
            "description": "GIT_LIVE_INVENT_REFUSED"
          },
          "404": {
            "description": "VOYAGE_NOT_FOUND"
          }
        }
      }
    },
    "/v1/git-forge/ops/readiness": {
      "get": {
        "tags": [
          "ops"
        ],
        "operationId": "gitForgeReadinessSoft",
        "summary": "Soft forge readiness (never claims LIVE)",
        "responses": {
          "200": {
            "description": "Soft readiness"
          }
        }
      }
    },
    "/v1/git-forge/openapi": {
      "get": {
        "tags": [
          "ops"
        ],
        "operationId": "gitForgeOpenApiSoft",
        "summary": "Soft host OpenAPI fragment Soft (EGOV-99)",
        "responses": {
          "200": {
            "description": "Soft OpenAPI document Soft"
          }
        }
      }
    },
    "/v1/git-forge/openapi/meta": {
      "get": {
        "tags": [
          "ops"
        ],
        "operationId": "gitForgeOpenApiMetaSoft",
        "summary": "Soft OpenAPI meta Soft (path_count; invent-refuse LIVE publish)",
        "responses": {
          "200": {
            "description": "Soft OpenAPI meta Soft"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "PackHealthSoft": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "soft": {
            "type": "boolean"
          },
          "live": {
            "type": "boolean"
          },
          "health": {
            "type": "string",
            "enum": [
              "green",
              "amber",
              "red"
            ]
          },
          "invent_refuse_live": {
            "type": "boolean"
          },
          "governance_live": {
            "type": "boolean"
          }
        }
      },
      "ApplyPinBody": {
        "type": "object",
        "properties": {
          "digest": {
            "type": "string"
          },
          "profile": {
            "type": "string",
            "enum": [
              "soft",
              "live"
            ]
          },
          "hard_desk": {
            "type": "boolean"
          },
          "signer": {
            "type": "string"
          },
          "pr_author": {
            "type": "string"
          },
          "dry_run": {
            "type": "boolean"
          }
        }
      },
      "VoyageStartBody": {
        "type": "object",
        "properties": {
          "journey_id": {
            "type": "string"
          },
          "composition_id": {
            "type": "string"
          },
          "entity_id": {
            "type": "string"
          },
          "org_id": {
            "type": "string"
          },
          "realm_id": {
            "type": "string"
          },
          "live": {
            "type": "boolean"
          },
          "hard_desk": {
            "type": "boolean"
          },
          "profile": {
            "type": "string"
          }
        }
      }
    }
  }
}