Governance Policies

Define, evaluate, and assign governance policies that gate workflow execution, including policy lifecycle, solutions, gate submissions and approvals, enforcement checks, metrics, and audit records.

All endpoints require authentication via X-API-Key header and the appropriate scope.

---

Policy Object

{
  "_id": "pol_abc123",
  "name": "Production Deployment Gate",
  "description": "Requires security review before production deploys",
  "category": "security",
  "severity": "high",
  "applicableResourceTypes": ["app", "workflow"],
  "stages": [
    {
      "id": "stage_1",
      "name": "Security Review",
      "gates": [{ "id": "gate_sec_1", "type": "approval" }]
    }
  ],
  "isActive": true,
  "isDraft": false,
  "createdBy": "user_456",
  "organizationId": "org_xyz",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

---

GET /api/v1/governance/policies

List governance policies with pagination and filters.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Description
category	string	No	Filter by policy category
severity	string	No	Filter by severity
isActive	string	No	Filter by active state (true or false)
search	string	No	Search term for name or description
limit	integer	No	Number of results to return
offset	integer	No	Number of results to skip
sort	string	No	Sort field and direction (default createdAt:desc)

Response 200 OK

{
  "count": 1,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "_id": "pol_abc123",
      "name": "Production Deployment Gate",
      "category": "security",
      "severity": "high",
      "isActive": true
    }
  ]
}

---

POST /api/v1/governance/policies

Create a new governance policy with stages and gates.

Scope: governance:write

Request Body

{
  "name": "Production Deployment Gate",
  "description": "Requires security review before production deploys",
  "category": "security",
  "severity": "high",
  "applicableResourceTypes": ["app", "workflow"],
  "stages": [
    {
      "id": "stage_1",
      "name": "Security Review",
      "gates": [{ "id": "gate_sec_1", "type": "approval" }]
    }
  ],
  "isActive": true,
  "isDraft": false
}

Field	Type	Required	Description
name	string	Yes	Policy name
description	string	Yes	Policy description
category	string	Yes	Policy category
severity	string	Yes	Policy severity
applicableResourceTypes	array	Yes	Resource types this policy applies to
stages	array	Yes	Stage definitions with gates
isActive	boolean	Yes	Whether the policy is active
isDraft	boolean	Yes	Whether the policy is in draft state

Response 201 Created

{
  "policyId": "pol_abc123"
}

---

GET /api/v1/governance/policies/:id

Get a single governance policy by ID.

Scope: governance:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Policy ID

Response 200 OK

Returns the full Policy object.

---

PUT /api/v1/governance/policies/:id

Update an existing governance policy by ID.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Policy ID

Request Body

Any subset of the policy fields documented in POST /api/v1/governance/policies.

Response 200 OK

Returns the updated Policy object.

---

DELETE /api/v1/governance/policies/:id

Delete a governance policy by ID.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Policy ID

Response 204 No Content

---

GET /api/v1/governance/solutions

List governance solutions with pagination and filters.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by solution status
search	string	No	Search term for name or description
limit	integer	No	Number of results to return
offset	integer	No	Number of results to skip

Response 200 OK

{
  "count": 1,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "_id": "sol_abc123",
      "name": "Customer Portal",
      "status": "in-review"
    }
  ]
}

---

POST /api/v1/governance/solutions

Create a new governance solution.

Scope: governance:write

Request Body

Solution payload as accepted by the governance.solutions.create Meteor method.

Response 201 Created

{
  "solutionId": "sol_abc123"
}

---

GET /api/v1/governance/solutions/:id

Get a single governance solution by ID.

Scope: governance:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Solution ID

Response 200 OK

Returns the full solution document.

---

PUT /api/v1/governance/solutions/:id

Update an existing governance solution by ID.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Solution ID

Request Body

Any subset of the solution fields supported by governance.solutions.update.

Response 200 OK

Returns the updated solution document.

---

DELETE /api/v1/governance/solutions/:id

Delete a governance solution by ID.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Solution ID

Response 204 No Content

---

GET /api/v1/governance/solutions/:id/requirements

Get the policy requirements for a solution.

Scope: governance:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Solution ID

Response 200 OK

Returns the computed governance requirements for this solution.

---

POST /api/v1/governance/solutions/:id/gates/:sub/submit

Submit data for a specific governance gate on a solution.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Solution ID
sub	string	Yes	Gate ID

Request Body

{
  "policyId": "pol_abc123",
  "data": { "answers": {} }
}

Field	Type	Required	Description
policyId	string	Yes	Policy that owns the gate
data	object	No	Gate submission payload (default {})

Response 200 OK

Returns the created/updated gate submission record.

---

POST /api/v1/governance/gate-submissions/:id/approve

Approve, deny, or conditionally approve a governance gate submission.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Gate submission ID

Request Body

{
  "decision": "approved",
  "comments": "Looks good"
}

Field	Type	Required	Description
decision	string	Yes	One of approved, denied, conditional
comments	string	No	Reviewer comments

Response 200 OK

Returns the updated gate submission record.

---

POST /api/v1/governance/gate-submissions/:id/waive

Admin-only: waive a governance gate with a reason.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Gate submission ID

Request Body

{
  "reason": "Compensating control documented in ticket SEC-1234"
}

Field	Type	Required	Description
reason	string	Yes	Waiver justification

Response 200 OK

Returns the updated gate submission record.

---

GET /api/v1/governance/gate-submissions/pending-reviews

List governance gates awaiting the caller's approval.

Scope: governance:read

Response 200 OK

Returns the list of pending review items for the caller.

---

POST /api/v1/governance/solutions/:id/recompute

Recompute a solution's gate status.

Scope: governance:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Solution ID

Response 200 OK

Returns the recomputed status payload.

---

GET /api/v1/governance/enforcement/check

Check if a resource can be deployed (governance gate check).

Scope: governance:read

Query Parameters

Parameter	Type	Required	Description
resourceId	string	Yes	ID of the resource to check
resourceType	string	Yes	Type of the resource to check

Response 200 OK

Returns the enforcement decision (allowed, blocking policies, etc.) for the resource.

---

GET /api/v1/governance/metrics

Get aggregate governance metrics for the organization.

Scope: governance:read

Response 200 OK

Returns the governance metrics rollup.

---

GET /api/v1/governance/resource-types

List the resource types recognized by the governance system.

Scope: governance:read

Response 200 OK

[
  { "id": "app", "label": "Application" },
  { "id": "workflow", "label": "Workflow" },
  { "id": "addon", "label": "Add-on" },
  { "id": "dataSource", "label": "Data Source" },
  { "id": "volume", "label": "Volume" },
  { "id": "mlModel", "label": "AI Model" },
  { "id": "aiGatewayModel", "label": "AI Gateway Model" },
  { "id": "workspace", "label": "Workspace" },
  { "id": "project", "label": "Project" },
  { "id": "skill", "label": "Skill" },
  { "id": "prompt", "label": "Prompt" },
  { "id": "agent", "label": "Agent" },
  { "id": "codeSession", "label": "Code Session" },
  { "id": "abTest", "label": "A/B Test" },
  { "id": "marketplaceApp", "label": "Marketplace App" }
]

---

GET /api/v1/governance/audit

List governance audit records. Admin-only.

Scope: governance:read

Query Parameters

Parameter	Type	Required	Description
entityType	string	No	Filter by audited entity type
action	string	No	Filter by action
userId	string	No	Filter by user ID
startDate	string	No	Filter by timestamp $gte (ISO 8601)
endDate	string	No	Filter by timestamp $lte (ISO 8601)
limit	integer	No	Number of results to return (max 500)
offset	integer	No	Number of results to skip
sort	string	No	Sort field and direction (default timestamp:desc)

Response 200 OK

{
  "count": 1,
  "limit": 100,
  "offset": 0,
  "items": [
    {
      "_id": "aud_abc123",
      "entityType": "policy",
      "action": "create",
      "userId": "user_456",
      "timestamp": "2025-02-01T14:22:00Z",
      "metadata": { "organizationId": "org_xyz" }
    }
  ]
}

Error Responses

• 403 — Admin role required