Sovereign OS Compliance API — OpenAPI 1.0.0

Scope: The published reference for Sovereign OS Compliance API. 8 paths — the measured spec-vs-implementation coverage lives in the complete API inventory. Status: rendered 2026-11-09 from the OpenAPI source for Sovereign OS Compliance API — 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	Local development (Agent BFF)
https://api.sovereign.exchange	Production

Tag	Summary
Policies	Compliance policy management
Audit Log	Compliance audit trail
Webhooks	Webhook ingress for external compliance systems
Community Compliance	Community-scoped compliance policies and audits

Paths — 8 paths / 11 operations

Method	Path	Operation ID	Summary
GET	/v1/compliance/policies	listPolicies	List compliance policies
POST	/v1/compliance/policies	createPolicy	Create a compliance policy
GET	/v1/compliance/audit-log	listAuditLog	List audit log entries
POST	/v1/compliance/audit-log	createAuditLog	Create an audit log entry
POST	/v1/compliance/webhook/{source}	receiveWebhook	Receive a compliance webhook
POST	/v1/compliance/webhook/{source}/{correlationId}	receiveWebhookWithCorrelation	Receive a compliance webhook with correlation ID
GET	/v1/compliance/webhook/status	getWebhookStatus	Get webhook ingress status
GET	/v1/compliance/webhook/audit	getWebhookAuditLog	Get webhook audit log
GET	/v1/communities/{communityId}/compliance/policies	listCommunityPolicies	List compliance policies for a community
POST	/v1/communities/{communityId}/compliance/policies	createCommunityPolicy	Create a compliance policy for a community
POST	/v1/communities/{communityId}/compliance/audit	recordCommunityAudit	Record a compliance audit result for a community

Operations

GET /v1/compliance/policies

Summary: List compliance policies Description: Returns a list of compliance policies, optionally filtered by status and scope.

Tags: Policies Operation ID: listPolicies

Parameters:

Name	In	Required	Type	Notes
status	query	no	string enum: active, inactive, draft	Filter by policy status
scope_id	query	no	string	Filter by scope ID
limit	query	no	int

Responses:

Status	Meaning
200	List of policies
500

POST /v1/compliance/policies

Summary: Create a compliance policy

Tags: Policies Operation ID: createPolicy Request body:

Content type: application/json

Field	Type	Notes
title	string	Policy title
content	string	Policy content or description
scope_id	string	Scope ID this policy applies to

Responses:

Status	Meaning
201	Policy created
400
500

GET /v1/compliance/audit-log

Summary: List audit log entries Description: Returns compliance audit log entries, optionally filtered by policy ID.

Tags: Audit Log Operation ID: listAuditLog

Parameters:

Name	In	Required	Type	Notes
policy_id	query	no	string	Filter by policy ID
limit	query	no	int

Responses:

Status	Meaning
200	Audit log entries
500

POST /v1/compliance/audit-log

Summary: Create an audit log entry

Tags: Audit Log Operation ID: createAuditLog Request body:

Content type: application/json

Field	Type	Notes
policy_id	string	Policy ID
actor_id	string	Actor performing the action
action_type	string	Type of action (e.g., 'created', 'updated', 'enforced', 'violated')
result	string	Result of the action
scope_id	string	Scope ID

Responses:

Status	Meaning
201	Audit log entry created
400
500

POST /v1/compliance/webhook/{source}

Summary: Receive a compliance webhook Description: Generic webhook ingress for external compliance systems. Valid sources: traces-nt, tancis, eudr, cbam, rashff, general.

Tags: Webhooks Operation ID: receiveWebhook

Parameters:

Name	In	Required	Type	Notes
source	path	yes	string enum: traces-nt, tancis, eudr, cbam, rashff, general	Source system identifier

Request body:

Content type: application/json

Field	Type	Notes

Responses:

Status	Meaning
200	Webhook processed
400	Invalid source
429
500

POST /v1/compliance/webhook/{source}/{correlationId}

Summary: Receive a compliance webhook with correlation ID Description: Webhook ingress with explicit correlation ID for request tracking.

Tags: Webhooks Operation ID: receiveWebhookWithCorrelation

Parameters:

Name	In	Required	Type	Notes
source	path	yes	string enum: traces-nt, tancis, eudr, cbam, rashff, general
correlationId	path	yes	string	Correlation ID for request tracking

Request body:

Content type: application/json

Field	Type	Notes

Responses:

Status	Meaning
200	Webhook processed
400	Invalid source
429
500

GET /v1/compliance/webhook/status

Summary: Get webhook ingress status

Tags: Webhooks Operation ID: getWebhookStatus Responses:

Status	Meaning
200	Webhook status

GET /v1/compliance/webhook/audit

Summary: Get webhook audit log

Tags: Webhooks Operation ID: getWebhookAuditLog

Parameters:

Name	In	Required	Type	Notes
limit	query	no	int

Responses:

Status	Meaning
200	Webhook audit log

GET /v1/communities/{communityId}/compliance/policies

Summary: List compliance policies for a community

Tags: Community Compliance Operation ID: listCommunityPolicies

Parameters:

Name	In	Required	Type	Notes
communityId	path	yes	string

Responses:

Status	Meaning
200	Community compliance policies

POST /v1/communities/{communityId}/compliance/policies

Summary: Create a compliance policy for a community

Tags: Community Compliance Operation ID: createCommunityPolicy

Parameters:

Name	In	Required	Type	Notes
communityId	path	yes	string

Request body:

Content type: application/json

Field	Type	Notes
title	string
content	string
standard	string	Compliance standard (e.g., 'EUDR', 'CBAM', 'ISO_14001')

Responses:

Status	Meaning
201	Policy created

POST /v1/communities/{communityId}/compliance/audit

Summary: Record a compliance audit result for a community

Tags: Community Compliance Operation ID: recordCommunityAudit

Parameters:

Name	In	Required	Type	Notes
communityId	path	yes	string

Request body:

Content type: application/json

Field	Type	Notes
policy_id	string
action_type	string
result	string enum: pass, fail, conditional
evidence_ref	string	Reference to evidence document

Responses:

Status	Meaning
201	Audit result recorded

Full specification — verbatim source of truth

{
  "openapi": "3.0.3",
  "info": {
    "title": "Sovereign OS Compliance API",
    "description": "Compliance iPaaS API — policies, audit logs, webhook ingress, and community-scoped compliance management. Supports EUDR, CBAM, VCM, and general compliance workflows.",
    "version": "1.0.0",
    "contact": {
      "name": "Sovereign OS Platform",
      "url": "https://sovereign.exchange"
    }
  },
  "servers": [
    {
      "url": "http://127.0.0.1:3030",
      "description": "Local development (Agent BFF)"
    },
    {
      "url": "https://api.sovereign.exchange",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Policies",
      "description": "Compliance policy management"
    },
    {
      "name": "Audit Log",
      "description": "Compliance audit trail"
    },
    {
      "name": "Webhooks",
      "description": "Webhook ingress for external compliance systems"
    },
    {
      "name": "Community Compliance",
      "description": "Community-scoped compliance policies and audits"
    }
  ],
  "paths": {
    "/v1/compliance/policies": {
      "get": {
        "tags": [
          "Policies"
        ],
        "operationId": "listPolicies",
        "summary": "List compliance policies",
        "description": "Returns a list of compliance policies, optionally filtered by status and scope.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "inactive",
                "draft"
              ]
            },
            "description": "Filter by policy status"
          },
          {
            "name": "scope_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by scope ID"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of policies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CompliancePolicy"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": [
          "Policies"
        ],
        "operationId": "createPolicy",
        "summary": "Create a compliance policy",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "Policy title"
                  },
                  "content": {
                    "type": "string",
                    "description": "Policy content or description"
                  },
                  "scope_id": {
                    "type": "string",
                    "description": "Scope ID this policy applies to"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Policy created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CompliancePolicy"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/compliance/audit-log": {
      "get": {
        "tags": [
          "Audit Log"
        ],
        "operationId": "listAuditLog",
        "summary": "List audit log entries",
        "description": "Returns compliance audit log entries, optionally filtered by policy ID.",
        "parameters": [
          {
            "name": "policy_id",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Filter by policy ID"
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50,
              "maximum": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit log entries",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AuditLogEntry"
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      },
      "post": {
        "tags": [
          "Audit Log"
        ],
        "operationId": "createAuditLog",
        "summary": "Create an audit log entry",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "policy_id",
                  "action_type"
                ],
                "properties": {
                  "policy_id": {
                    "type": "string",
                    "description": "Policy ID"
                  },
                  "actor_id": {
                    "type": "string",
                    "description": "Actor performing the action"
                  },
                  "action_type": {
                    "type": "string",
                    "description": "Type of action (e.g., 'created', 'updated', 'enforced', 'violated')"
                  },
                  "result": {
                    "type": "string",
                    "description": "Result of the action"
                  },
                  "scope_id": {
                    "type": "string",
                    "description": "Scope ID"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Audit log entry created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AuditLogEntry"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/compliance/webhook/{source}": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "receiveWebhook",
        "summary": "Receive a compliance webhook",
        "description": "Generic webhook ingress for external compliance systems. Valid sources: traces-nt, tancis, eudr, cbam, rashff, general.",
        "parameters": [
          {
            "name": "source",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "traces-nt",
                "tancis",
                "eudr",
                "cbam",
                "rashff",
                "general"
              ]
            },
            "description": "Source system identifier"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPayload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook processed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid source"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/compliance/webhook/{source}/{correlationId}": {
      "post": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "receiveWebhookWithCorrelation",
        "summary": "Receive a compliance webhook with correlation ID",
        "description": "Webhook ingress with explicit correlation ID for request tracking.",
        "parameters": [
          {
            "name": "source",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "traces-nt",
                "tancis",
                "eudr",
                "cbam",
                "rashff",
                "general"
              ]
            }
          },
          {
            "name": "correlationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Correlation ID for request tracking"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPayload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook processed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookResult"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid source"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/v1/compliance/webhook/status": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhookStatus",
        "summary": "Get webhook ingress status",
        "responses": {
          "200": {
            "description": "Webhook status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/WebhookStatus"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/compliance/webhook/audit": {
      "get": {
        "tags": [
          "Webhooks"
        ],
        "operationId": "getWebhookAuditLog",
        "summary": "Get webhook audit log",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Webhook audit log",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/WebhookAuditEntry"
                      }
                    },
                    "count": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/communities/{communityId}/compliance/policies": {
      "get": {
        "tags": [
          "Community Compliance"
        ],
        "operationId": "listCommunityPolicies",
        "summary": "List compliance policies for a community",
        "parameters": [
          {
            "name": "communityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Community compliance policies",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/CompliancePolicy"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Community Compliance"
        ],
        "operationId": "createCommunityPolicy",
        "summary": "Create a compliance policy for a community",
        "parameters": [
          {
            "name": "communityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "content": {
                    "type": "string"
                  },
                  "standard": {
                    "type": "string",
                    "description": "Compliance standard (e.g., 'EUDR', 'CBAM', 'ISO_14001')"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Policy created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/CompliancePolicy"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/communities/{communityId}/compliance/audit": {
      "post": {
        "tags": [
          "Community Compliance"
        ],
        "operationId": "recordCommunityAudit",
        "summary": "Record a compliance audit result for a community",
        "parameters": [
          {
            "name": "communityId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "policy_id",
                  "action_type",
                  "result"
                ],
                "properties": {
                  "policy_id": {
                    "type": "string"
                  },
                  "action_type": {
                    "type": "string"
                  },
                  "result": {
                    "type": "string",
                    "enum": [
                      "pass",
                      "fail",
                      "conditional"
                    ]
                  },
                  "evidence_ref": {
                    "type": "string",
                    "description": "Reference to evidence document"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Audit result recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/AuditLogEntry"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CompliancePolicy": {
        "type": "object",
        "properties": {
          "policy_id": {
            "type": "string",
            "description": "Unique policy identifier"
          },
          "title": {
            "type": "string",
            "description": "Policy title"
          },
          "content": {
            "type": "string",
            "description": "Policy content or description"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "inactive",
              "draft"
            ]
          },
          "scope_id": {
            "type": "string",
            "description": "Scope this policy applies to"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "AuditLogEntry": {
        "type": "object",
        "properties": {
          "log_id": {
            "type": "string",
            "description": "Unique log entry identifier"
          },
          "policy_id": {
            "type": "string",
            "description": "Related policy ID"
          },
          "actor_id": {
            "type": "string",
            "description": "Actor performing the action"
          },
          "action_type": {
            "type": "string",
            "description": "Type of action"
          },
          "result": {
            "type": "string",
            "description": "Result of the action"
          },
          "scope_id": {
            "type": "string",
            "description": "Scope ID"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookPayload": {
        "type": "object",
        "properties": {
          "event_type": {
            "type": "string",
            "description": "Type of webhook event"
          },
          "data": {
            "type": "object",
            "description": "Event payload data"
          },
          "metadata": {
            "type": "object",
            "description": "Additional metadata"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookResult": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "correlation_id": {
            "type": "string"
          },
          "event_id": {
            "type": "string"
          }
        }
      },
      "WebhookStatus": {
        "type": "object",
        "properties": {
          "started": {
            "type": "boolean"
          },
          "subject": {
            "type": "string"
          },
          "processed": {
            "type": "integer"
          },
          "failed": {
            "type": "integer"
          },
          "last_event_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "WebhookAuditEntry": {
        "type": "object",
        "properties": {
          "event": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "correlation_id": {
            "type": "string"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time"
          },
          "error": {
            "type": "string"
          }
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Bad request — missing required fields",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "InternalError": {
        "description": "Internal server error",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "error": {
                  "type": "string"
                },
                "retry_after_ms": {
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    }
  }
}