{
"components": {
"schemas": {
"AcknowledgeRelocationNoticeBody": {
"additionalProperties": false,
"description": "Request body for an organisation's response to a relocation notice.",
"properties": {
"comment": {
"description": "The organisation's comment; required when objecting.",
"nullable": true,
"type": "string"
},
"response": {
"description": "\"acknowledged\" (default when omitted) or \"objected\". An objection must carry a\r\nEssence.Core.Instance.Api.Controllers.OrgResidencyController.AcknowledgeRelocationNoticeBody.Comment.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ActingOrganizationDto": {
"additionalProperties": false,
"properties": {
"organizationId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ActivateSovereignInstanceCommand": {
"additionalProperties": false,
"properties": {
"instanceId": {
"format": "uuid",
"type": "string"
},
"validatorAddress": {
"nullable": true,
"type": "string"
},
"validatorPublicKeyBase64": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AdminCreateOrganizationRequest": {
"additionalProperties": false,
"description": "Request body for M:Essence.Core.Instance.Api.Controllers.AdminOrganizationsController.CreateOrganization(Essence.Core.Instance.Api.Controllers.AdminCreateOrganizationRequest,System.Threading.CancellationToken).",
"properties": {
"adminDisplayName": {
"nullable": true,
"type": "string"
},
"adminEmail": {
"nullable": true,
"type": "string"
},
"globalInstanceId": {
"format": "uuid",
"type": "string"
},
"orgAdminUserId": {
"format": "uuid",
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"organizationName": {
"nullable": true,
"type": "string"
},
"parentSovereignInstanceId": {
"format": "uuid",
"type": "string"
},
"pricingPlanId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"slug": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AgeAssuranceLevel": {
"enum": [
"SelfDeclared",
"Basic",
"Substantial",
"High"
],
"type": "string"
},
"AlertActionRequest": {
"additionalProperties": false,
"description": "The body of a monitoring alert action. Only `suppress` requires it.",
"properties": {
"reason": {
"description": "Why the alert is being muted.",
"nullable": true,
"type": "string"
},
"suppressedUntil": {
"description": "When the mute lapses (UTC). Must be in the future.",
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ApprovalDecisionBody": {
"additionalProperties": false,
"description": "Request body for an approve / deny / expire decision (S-03.02 write).",
"properties": {
"expiresAt": {
"description": "Optional approval expiry (approve only); must be in the future.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"mechanism": {
"description": "Legal mechanism name for an approval (SCC/BCR/TIA/Adequacy); defaults to SCC.",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Operator-supplied reason for the decision (required).",
"nullable": true,
"type": "string"
},
"scope": {
"description": "Optional decision scope qualifier (approve only).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ApproveRegistrationRequestBody": {
"additionalProperties": false,
"description": "Request body for approving a registration request.",
"properties": {
"conditions": {
"description": "Gets or sets optional conditions attached to the approval.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AssignRoleRequest": {
"additionalProperties": false,
"description": "Request model for assigning a role to a user.",
"properties": {
"expiresAt": {
"description": "Gets or sets the optional expiration date for the role assignment.",
"format": "date-time",
"nullable": true,
"type": "string"
},
"instanceScope": {
"description": "Gets or sets the instance scope for the role.",
"nullable": true,
"type": "string"
},
"roleId": {
"description": "Gets or sets the role ID to assign.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"AssuranceCreditPreviewDto": {
"additionalProperties": false,
"properties": {
"basisCredentialId": {
"format": "uuid",
"type": "string"
},
"originLoA": {
"nullable": true,
"type": "string"
},
"originScheme": {
"nullable": true,
"type": "string"
},
"policyId": {
"nullable": true,
"type": "string"
},
"provisionalDomesticAssurance": {
"nullable": true,
"type": "string"
},
"residualCheckDescription": {
"nullable": true,
"type": "string"
},
"residualCheckRequired": {
"type": "boolean"
}
},
"type": "object"
},
"AttestCrossBoundaryReplicationRequest": {
"additionalProperties": false,
"description": "Request to record + attest a CC-090 cross-boundary encrypted-backup geo-replication.",
"properties": {
"backupId": {
"description": "Backup whose ciphertext is being replicated.",
"format": "uuid",
"type": "string"
},
"encryptionKeyId": {
"description": "Identifier (not material) of the encryption key that stays sovereign.",
"nullable": true,
"type": "string"
},
"instanceId": {
"description": "Sovereign instance the backup belongs to.",
"format": "uuid",
"type": "string"
},
"requestedBy": {
"description": "Activating actor; overridden by the authenticated principal when present so the audit\r\ntrail attributes to the real caller.",
"nullable": true,
"type": "string"
},
"sourceRegion": {
"description": "Sovereign-local source region.",
"nullable": true,
"type": "string"
},
"sovereignKmsRegion": {
"description": "Sovereign KMS region the encryption key never leaves.",
"nullable": true,
"type": "string"
},
"targetRegion": {
"description": "Foreign (out-of-boundary) target region for the ciphertext.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"BatchProvisionSupervisedInstancesCommand": {
"additionalProperties": false,
"properties": {
"controlTemplateRef": {
"nullable": true,
"type": "string"
},
"graduationScheduleRef": {
"nullable": true,
"type": "string"
},
"guardianId": {
"format": "uuid",
"type": "string"
},
"roster": {
"items": {
"$ref": "#/components/schemas/SupervisedInstanceRosterEntry"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"BatchProvisionSupervisedInstancesResultDto": {
"additionalProperties": false,
"properties": {
"batchId": {
"format": "uuid",
"type": "string"
},
"controlTemplateRef": {
"nullable": true,
"type": "string"
},
"instances": {
"items": {
"$ref": "#/components/schemas/SupervisedInstanceDto"
},
"nullable": true,
"type": "array"
},
"provisionedCount": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"BindCustomDomainRequest": {
"additionalProperties": false,
"properties": {
"customDomain": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CertificateDto": {
"additionalProperties": false,
"properties": {
"certificateType": {
"$ref": "#/components/schemas/CertificateType"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"instanceId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"isExpiringSoon": {
"readOnly": true,
"type": "boolean"
},
"isHsmBacked": {
"type": "boolean"
},
"isValid": {
"readOnly": true,
"type": "boolean"
},
"issuedAt": {
"format": "date-time",
"type": "string"
},
"revocationReason": {
"$ref": "#/components/schemas/CertificateRevocationReason"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"serialNumber": {
"nullable": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/CertificateStatus"
},
"subjectName": {
"nullable": true,
"type": "string"
},
"thumbprint": {
"nullable": true,
"type": "string"
}
},
"required": [
"certificateType",
"expiresAt",
"isHsmBacked",
"issuedAt",
"serialNumber",
"status",
"subjectName",
"thumbprint"
],
"type": "object"
},
"CertificateRevocationReason": {
"enum": [
"Unspecified",
"KeyCompromise",
"CACompromise",
"AffiliationChanged",
"Superseded",
"CessationOfOperation",
"CertificateHold",
"RemoveFromCRL",
"PrivilegeWithdrawn",
"AACompromise"
],
"type": "string"
},
"CertificateStatus": {
"enum": [
"Valid",
"Revoked",
"Expired",
"Pending"
],
"type": "string"
},
"CertificateType": {
"enum": [
"Root",
"Intermediate",
"Leaf"
],
"type": "string"
},
"CircuitBreakerState": {
"additionalProperties": false,
"description": "Represents the state of a circuit breaker for a specific target instance.",
"properties": {
"breakDuration": {
"description": "Gets or sets the duration the circuit stays open before transitioning to half-open.",
"format": "date-span",
"type": "string"
},
"consecutiveFailureCount": {
"description": "Gets or sets the consecutive failure count.",
"format": "int32",
"type": "integer"
},
"failureThreshold": {
"description": "Gets or sets the failure threshold that triggers the circuit to open.",
"format": "int32",
"type": "integer"
},
"lastOpenedAt": {
"description": "Gets or sets the timestamp when the circuit was last opened (null if never opened).",
"format": "date-time",
"nullable": true,
"type": "string"
},
"state": {
"description": "Gets or sets the current circuit state (Closed, Open, HalfOpen).",
"nullable": true,
"type": "string"
},
"targetInstanceId": {
"description": "Gets or sets the target instance ID.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CircuitBreakerStatesResponse": {
"additionalProperties": false,
"description": "Response model for circuit breaker states query.",
"properties": {
"checkedAt": {
"description": "Gets or sets the timestamp when the states were checked.",
"format": "date-time",
"type": "string"
},
"circuitBreakers": {
"additionalProperties": {
"$ref": "#/components/schemas/CircuitBreakerState"
},
"description": "Gets or sets the dictionary of circuit breaker states keyed by target instance ID.",
"nullable": true,
"type": "object"
}
},
"type": "object"
},
"CompleteMaterialisationRequest": {
"additionalProperties": false,
"properties": {
"databaseConnectionString": {
"description": "The database the operator actually created.",
"nullable": true,
"type": "string"
},
"endpointUrl": {
"description": "Where the instance is reachable.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CompleteRegistrationRequestBody": {
"additionalProperties": false,
"description": "Request body for completing a registration.",
"properties": {
"approvalToken": {
"description": "Gets or sets the approval token to validate.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ComplianceStatus": {
"enum": [
"Compliant",
"NonCompliant",
"UnderReview",
"Exempt"
],
"type": "string"
},
"ComputeRouteRequest": {
"additionalProperties": false,
"description": "Request model for computing an optimal route between instances.",
"properties": {
"sourceInstanceId": {
"description": "Gets or sets the source instance ID.",
"nullable": true,
"type": "string"
},
"targetInstanceId": {
"description": "Gets or sets the target instance ID.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateDeveloperIdRequest": {
"additionalProperties": false,
"description": "Request payload for creating a developer ID.",
"properties": {
"displayName": {
"nullable": true,
"type": "string"
},
"notes": {
"nullable": true,
"type": "string"
},
"ownerEmail": {
"nullable": true,
"type": "string"
},
"slug": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateDnsRecordCommand": {
"additionalProperties": false,
"properties": {
"healthCheckEnabled": {
"type": "boolean"
},
"healthCheckEndpoint": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"priority": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"ttl": {
"format": "int32",
"type": "integer"
},
"type": {
"nullable": true,
"type": "string"
},
"value": {
"nullable": true,
"type": "string"
},
"weight": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"zoneId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"CreateDnsZoneCommand": {
"additionalProperties": false,
"properties": {
"ownerInstanceId": {
"format": "uuid",
"type": "string"
},
"ownerInstanceType": {
"nullable": true,
"type": "string"
},
"parentZoneId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"provider": {
"nullable": true,
"type": "string"
},
"providerConfiguration": {
"nullable": true,
"type": "string"
},
"zoneName": {
"nullable": true,
"type": "string"
},
"zoneType": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateGlobalInstanceCommand": {
"additionalProperties": false,
"properties": {
"autoScalingEnabled": {
"type": "boolean"
},
"availabilityZone": {
"nullable": true,
"type": "string"
},
"backupEnabled": {
"type": "boolean"
},
"backupRetentionDays": {
"format": "int32",
"type": "integer"
},
"complianceCertifications": {
"nullable": true,
"type": "string"
},
"dataCenter": {
"nullable": true,
"type": "string"
},
"endpointUrl": {
"nullable": true,
"type": "string"
},
"highAvailabilityEnabled": {
"type": "boolean"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"maxApiRequestsPerHour": {
"format": "int32",
"type": "integer"
},
"maxConnections": {
"format": "int32",
"type": "integer"
},
"maxStorageGb": {
"format": "int64",
"type": "integer"
},
"monitoringEnabled": {
"type": "boolean"
},
"name": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"tags": {
"nullable": true,
"type": "string"
},
"version": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateInstanceResponseDto": {
"additionalProperties": false,
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"location": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateOrganizationInstanceCommand": {
"additionalProperties": false,
"properties": {
"adminDisplayName": {
"nullable": true,
"type": "string"
},
"adminEmail": {
"nullable": true,
"type": "string"
},
"autoScalingEnabled": {
"type": "boolean"
},
"availabilityZone": {
"nullable": true,
"type": "string"
},
"backupEnabled": {
"type": "boolean"
},
"backupRetentionDays": {
"format": "int32",
"type": "integer"
},
"commercialModel": {
"nullable": true,
"type": "string"
},
"complianceCertifications": {
"nullable": true,
"type": "string"
},
"cpuCores": {
"format": "int32",
"type": "integer"
},
"createdByUserId": {
"format": "uuid",
"type": "string"
},
"creatorOrganizationId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"creatorType": {
"$ref": "#/components/schemas/OrganizationCreatorType"
},
"customDomain": {
"nullable": true,
"type": "string"
},
"customFieldsEnabled": {
"type": "boolean"
},
"customWorkflowsEnabled": {
"type": "boolean"
},
"dataCenter": {
"nullable": true,
"type": "string"
},
"databaseSku": {
"nullable": true,
"type": "string"
},
"dealRegistrationId": {
"nullable": true,
"type": "string"
},
"deploymentModel": {
"$ref": "#/components/schemas/InstanceDeploymentModel"
},
"deploymentRegion": {
"nullable": true,
"type": "string"
},
"endpointUrl": {
"nullable": true,
"type": "string"
},
"faviconUrl": {
"nullable": true,
"type": "string"
},
"founderUserId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"globalInstanceId": {
"format": "uuid",
"type": "string"
},
"highAvailabilityEnabled": {
"type": "boolean"
},
"infrastructureProvider": {
"nullable": true,
"type": "string"
},
"instanceLicenceSubscriptionId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"instancePricingPlanId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"instanceSkuCode": {
"nullable": true,
"type": "string"
},
"integrationsEnabled": {
"type": "boolean"
},
"isDedicated": {
"type": "boolean"
},
"isPendingClaim": {
"type": "boolean"
},
"logoUrl": {
"nullable": true,
"type": "string"
},
"maxApiRequestsPerHour": {
"format": "int32",
"type": "integer"
},
"maxConnections": {
"format": "int32",
"type": "integer"
},
"maxStorageGb": {
"format": "int32",
"type": "integer"
},
"memoryGb": {
"format": "int32",
"type": "integer"
},
"monitoringEnabled": {
"type": "boolean"
},
"name": {
"nullable": true,
"type": "string"
},
"operatorOrganizationId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"organizationDisplayName": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"organizationName": {
"nullable": true,
"type": "string"
},
"parentSovereignInstanceId": {
"format": "uuid",
"type": "string"
},
"partnerId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"pricingPlanId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"primaryColor": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"requestedModuleIds": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"secondaryColor": {
"nullable": true,
"type": "string"
},
"serviceEndpointOverrides": {
"additionalProperties": {
"type": "string"
},
"nullable": true,
"type": "object"
},
"slug": {
"nullable": true,
"type": "string"
},
"storageGb": {
"format": "int32",
"type": "integer"
},
"tags": {
"nullable": true,
"type": "string"
},
"version": {
"nullable": true,
"type": "string"
},
"whiteLabelEnabled": {
"type": "boolean"
}
},
"type": "object"
},
"CreateRegistrationRequestCommand": {
"additionalProperties": false,
"properties": {
"isDedicated": {
"nullable": true,
"type": "boolean"
},
"jurisdictionCode": {
"nullable": true,
"type": "string"
},
"justification": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"organizationName": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"requestType": {
"nullable": true,
"type": "string"
},
"requestedByEmail": {
"nullable": true,
"type": "string"
},
"requestedByUserId": {
"format": "uuid",
"type": "string"
},
"requestingInstanceId": {
"format": "uuid",
"type": "string"
},
"requestingInstanceName": {
"nullable": true,
"type": "string"
},
"slug": {
"nullable": true,
"type": "string"
},
"targetInstanceId": {
"format": "uuid",
"type": "string"
},
"targetInstanceType": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateSovereignInstanceCommand": {
"additionalProperties": false,
"properties": {
"allowedStorageRegions": {
"nullable": true,
"type": "string"
},
"allowedTransferJurisdictions": {
"nullable": true,
"type": "string"
},
"autoScalingEnabled": {
"type": "boolean"
},
"availabilityZone": {
"nullable": true,
"type": "string"
},
"backupEnabled": {
"type": "boolean"
},
"backupRetentionDays": {
"format": "int32",
"type": "integer"
},
"complianceCertifications": {
"nullable": true,
"type": "string"
},
"countryCode": {
"nullable": true,
"type": "string"
},
"dataCenter": {
"nullable": true,
"type": "string"
},
"edgeCachingEnabled": {
"type": "boolean"
},
"endpointUrl": {
"nullable": true,
"type": "string"
},
"globalInstanceId": {
"format": "uuid",
"type": "string"
},
"highAvailabilityEnabled": {
"type": "boolean"
},
"jurisdictionCode": {
"nullable": true,
"type": "string"
},
"jurisdictionName": {
"nullable": true,
"type": "string"
},
"maxApiRequestsPerHour": {
"format": "int32",
"type": "integer"
},
"maxConnections": {
"format": "int32",
"type": "integer"
},
"maxStorageGb": {
"format": "int32",
"type": "integer"
},
"monitoringEnabled": {
"type": "boolean"
},
"name": {
"nullable": true,
"type": "string"
},
"primaryRegion": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"regulatoryFramework": {
"nullable": true,
"type": "string"
},
"requireStandardContractualClauses": {
"type": "boolean"
},
"tags": {
"nullable": true,
"type": "string"
},
"version": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateUserRequest": {
"additionalProperties": false,
"description": "Request model for creating a user.",
"properties": {
"email": {
"description": "Gets or sets the user's email address.",
"nullable": true,
"type": "string"
},
"fullName": {
"description": "Gets or sets the user's full name.",
"nullable": true,
"type": "string"
},
"role": {
"description": "Gets or sets the role to assign to the user.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CreateVaultCommand": {
"additionalProperties": false,
"properties": {
"authenticationTag": {
"nullable": true,
"type": "string"
},
"autoDeleteDays": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"autoDeleteEnabled": {
"type": "boolean"
},
"description": {
"nullable": true,
"type": "string"
},
"initializationVector": {
"nullable": true,
"type": "string"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"keyId": {
"nullable": true,
"type": "string"
},
"maxDocuments": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"maxSizeBytes": {
"format": "int64",
"nullable": true,
"type": "integer"
},
"name": {
"nullable": true,
"type": "string"
},
"ownerId": {
"format": "uuid",
"type": "string"
},
"salt": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CredentialLockdownResponse": {
"additionalProperties": false,
"description": "Response body for a presented-credential lockdown.",
"properties": {
"recordId": {
"description": "The compromise-record id (stable across idempotent retries).",
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"CrossBorderApprovalDto": {
"additionalProperties": false,
"properties": {
"adequacyOutcome": {
"nullable": true,
"type": "string"
},
"dataClassification": {
"nullable": true,
"type": "string"
},
"decidedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"decidedBy": {
"nullable": true,
"type": "string"
},
"decisionReason": {
"nullable": true,
"type": "string"
},
"decisionScope": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"mechanism": {
"nullable": true,
"type": "string"
},
"origin": {
"nullable": true,
"type": "string"
},
"purpose": {
"nullable": true,
"type": "string"
},
"recipient": {
"nullable": true,
"type": "string"
},
"requestedAt": {
"format": "date-time",
"type": "string"
},
"requestedBy": {
"nullable": true,
"type": "string"
},
"sourceJurisdiction": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"targetJurisdiction": {
"nullable": true,
"type": "string"
},
"territories": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"required": [
"adequacyOutcome",
"id",
"purpose",
"recipient",
"requestedAt",
"requestedBy",
"sourceJurisdiction",
"status",
"targetJurisdiction"
],
"type": "object"
},
"CrossBorderApprovalDtoCursorResult": {
"additionalProperties": false,
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/CrossBorderApprovalDto"
},
"nullable": true,
"type": "array"
},
"nextCursor": {
"nullable": true,
"type": "string"
},
"pageSize": {
"format": "int32",
"type": "integer"
},
"previousCursor": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CrossBorderVerdictDto": {
"additionalProperties": false,
"properties": {
"adequacyOutcome": {
"nullable": true,
"type": "string"
},
"approvalId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"approvalStatus": {
"nullable": true,
"type": "string"
},
"approvingAuthority": {
"nullable": true,
"type": "string"
},
"binding": {
"type": "boolean"
},
"decidedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"evaluatedAt": {
"format": "date-time",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"legalBasis": {
"nullable": true,
"type": "string"
},
"recipient": {
"nullable": true,
"type": "string"
},
"sourceJurisdiction": {
"nullable": true,
"type": "string"
},
"targetJurisdiction": {
"nullable": true,
"type": "string"
},
"verdict": {
"nullable": true,
"type": "string"
}
},
"required": [
"adequacyOutcome",
"evaluatedAt",
"legalBasis",
"sourceJurisdiction",
"targetJurisdiction",
"verdict"
],
"type": "object"
},
"CrossRegionRolloutDto": {
"additionalProperties": false,
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"endedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"fromVersion": {
"nullable": true,
"type": "string"
},
"haltReason": {
"nullable": true,
"type": "string"
},
"haltedAutomatically": {
"type": "boolean"
},
"id": {
"format": "uuid",
"type": "string"
},
"nextRegion": {
"nullable": true,
"type": "string"
},
"orderedRegions": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"rolledRegions": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"startedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"state": {
"nullable": true,
"type": "string"
},
"toVersion": {
"nullable": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"CustomDomainBindingDto": {
"additionalProperties": false,
"properties": {
"boundAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"customDomain": {
"nullable": true,
"type": "string"
},
"enabled": {
"type": "boolean"
},
"lastVerificationMessage": {
"nullable": true,
"type": "string"
},
"organizationInstanceId": {
"format": "uuid",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"verificationRecordName": {
"nullable": true,
"type": "string"
},
"verificationRecordValue": {
"nullable": true,
"type": "string"
},
"verifiedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DeclareInstanceServiceLevelRequest": {
"additionalProperties": false,
"properties": {
"availabilityTargetBasisPoints": {
"format": "int32",
"type": "integer"
},
"criticalIncidentResponseMinutes": {
"format": "int32",
"type": "integer"
},
"supportCoverage": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DeclineJointVentureRequest": {
"additionalProperties": false,
"properties": {
"reason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DedicatedMaterialisationQueueItem": {
"additionalProperties": false,
"properties": {
"cpuCores": {
"format": "int32",
"type": "integer"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"memoryGb": {
"format": "int32",
"type": "integer"
},
"organizationName": {
"nullable": true,
"type": "string"
},
"parentSovereignInstanceId": {
"format": "uuid",
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"requestId": {
"format": "uuid",
"type": "string"
},
"requestedAt": {
"format": "date-time",
"type": "string"
},
"storageGb": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"DeveloperIdEntry": {
"additionalProperties": false,
"description": "Represents a developer ID entry.",
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"notes": {
"nullable": true,
"type": "string"
},
"ownerEmail": {
"nullable": true,
"type": "string"
},
"slug": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"suspendedReason": {
"nullable": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"DiscoveryResult": {
"additionalProperties": false,
"properties": {
"discoveredAt": {
"format": "date-time",
"readOnly": true,
"type": "string"
},
"endpoint": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"errorMessage": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"instanceId": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"isHealthy": {
"readOnly": true,
"type": "boolean"
},
"latency": {
"format": "date-span",
"readOnly": true,
"type": "string"
},
"region": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/DiscoveryStatus"
}
},
"type": "object"
},
"DiscoveryStatus": {
"enum": [
"Success",
"Unhealthy",
"Unreachable",
"NotFound",
"Timeout",
"Error",
"Maintenance",
"NoAdequateSovereign"
],
"type": "string"
},
"DnsRecordDto": {
"additionalProperties": false,
"properties": {
"healthCheckEnabled": {
"type": "boolean"
},
"healthCheckEndpoint": {
"nullable": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"lastVerifiedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"priority": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"status": {
"nullable": true,
"type": "string"
},
"ttl": {
"format": "int32",
"type": "integer"
},
"type": {
"nullable": true,
"type": "string"
},
"value": {
"nullable": true,
"type": "string"
},
"weight": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"zoneId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"DnsZoneDto": {
"additionalProperties": false,
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"ownerInstanceId": {
"format": "uuid",
"type": "string"
},
"ownerInstanceType": {
"nullable": true,
"type": "string"
},
"parentZoneId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"provider": {
"nullable": true,
"type": "string"
},
"records": {
"items": {
"$ref": "#/components/schemas/DnsRecordDto"
},
"nullable": true,
"type": "array"
},
"status": {
"nullable": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"type": "string"
},
"zoneType": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"DomainEvent": {
"additionalProperties": false,
"properties": {
"aggregateId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"aggregateType": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"eventId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"nullable": true,
"type": "object"
},
"occurredOn": {
"format": "date-time",
"readOnly": true,
"type": "string"
},
"version": {
"format": "int32",
"readOnly": true,
"type": "integer"
}
},
"type": "object"
},
"DrivingCategoryGrantInput": {
"additionalProperties": false,
"properties": {
"code": {
"nullable": true,
"type": "string"
},
"obtainedOn": {
"format": "date",
"nullable": true,
"type": "string"
},
"validUntil": {
"format": "date",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"EstablishEVisaRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/cross-border/immigration-status/evisa`.",
"properties": {
"credentialId": {
"description": "Opaque eVisa credential identifier.",
"nullable": true,
"type": "string"
},
"validFrom": {
"description": "Start of the eVisa's validity.",
"format": "date",
"type": "string"
},
"validUntil": {
"description": "End of the eVisa's validity; null when open-ended.",
"format": "date",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"FailMaterialisationRequest": {
"additionalProperties": false,
"properties": {
"reason": {
"description": "Why it cannot be built. The organisation is owed an explanation and the next operator is owed the\r\ncontext — a blank is refused.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"FlagPresentedCredentialCompromisedCommand": {
"additionalProperties": false,
"properties": {
"consentRecordRef": {
"nullable": true,
"type": "string"
},
"credentialId": {
"nullable": true,
"type": "string"
},
"flaggedByUserId": {
"format": "uuid",
"type": "string"
},
"issuer": {
"nullable": true,
"type": "string"
},
"relyingPartyRef": {
"nullable": true,
"type": "string"
},
"statusListIndex": {
"format": "int64",
"nullable": true,
"type": "integer"
},
"statusListUrl": {
"nullable": true,
"type": "string"
},
"vaultRef": {
"format": "uuid",
"type": "string"
}
},
"required": [
"consentRecordRef",
"credentialId",
"flaggedByUserId",
"issuer",
"vaultRef"
],
"type": "object"
},
"ForeignCredentialCaptureRequest": {
"additionalProperties": false,
"description": "One submitted foreign credential reference (ZK metadata only — never a payload).",
"properties": {
"issuerJurisdiction": {
"description": "Issuer jurisdiction code (ISO 3166 alpha-2 or a recognised grouping code).",
"nullable": true,
"type": "string"
},
"kind": {
"description": "The credential kind (`foreign-passport` | `residence-permit` | …).",
"nullable": true,
"type": "string"
},
"label": {
"description": "Plain-language, non-identifying label, e.g. \"UAE Emirates ID\".",
"nullable": true,
"type": "string"
},
"originLoA": {
"description": "The asserted origin assurance level (`low` | `substantial` | `high`).",
"nullable": true,
"type": "string"
},
"originScheme": {
"description": "The origin trust-scheme id, e.g. `UAEPass`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ForeignCredentialRefDto": {
"additionalProperties": false,
"properties": {
"id": {
"format": "uuid",
"type": "string"
},
"identifierMask": {
"nullable": true,
"type": "string"
},
"issuerJurisdiction": {
"nullable": true,
"type": "string"
},
"kind": {
"nullable": true,
"type": "string"
},
"label": {
"nullable": true,
"type": "string"
},
"originLoA": {
"nullable": true,
"type": "string"
},
"originScheme": {
"nullable": true,
"type": "string"
},
"rejectionReason": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"GlobalInstance": {
"additionalProperties": false,
"properties": {
"activatedAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"configuration": {
"$ref": "#/components/schemas/InstanceConfiguration"
},
"connectedOrganizationInstances": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"connectedSovereignInstances": {
"items": {
"format": "uuid",
"type": "string"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"createdBy": {
"nullable": true,
"type": "string"
},
"deletedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"deletedBy": {
"nullable": true,
"type": "string"
},
"domainEvents": {
"items": {
"$ref": "#/components/schemas/DomainEvent"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"endpointUrl": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"hasDomainEvents": {
"readOnly": true,
"type": "boolean"
},
"healthCheckStatus": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"isDeleted": {
"readOnly": true,
"type": "boolean"
},
"isHealthy": {
"readOnly": true,
"type": "boolean"
},
"lastHealthCheck": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"metadata": {
"$ref": "#/components/schemas/InstanceMetadata"
},
"name": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"provisionedAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"rowVersion": {
"format": "byte",
"nullable": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/InstanceStatus"
},
"suspensionReason": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"terminatedAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"terminationReason": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"type": {
"$ref": "#/components/schemas/InstanceType"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"updatedBy": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"HealthStatus": {
"additionalProperties": false,
"properties": {
"checkedAt": {
"format": "date-time",
"readOnly": true,
"type": "string"
},
"httpStatusCode": {
"format": "int32",
"nullable": true,
"readOnly": true,
"type": "integer"
},
"isHealthy": {
"readOnly": true,
"type": "boolean"
},
"reason": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"responseTime": {
"format": "date-span",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"HomeRealmDiscoveryRequest": {
"additionalProperties": false,
"properties": {
"domain": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"HomeRealmDiscoveryResponse": {
"additionalProperties": false,
"properties": {
"authorizeUrl": {
"nullable": true,
"type": "string"
},
"isDefaultRealm": {
"type": "boolean"
},
"realmToken": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ImmigrationShareCodeDto": {
"additionalProperties": false,
"properties": {
"claimType": {
"nullable": true,
"type": "string"
},
"codeMask": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"issuedAt": {
"format": "date-time",
"type": "string"
},
"lastRedeemedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"recipientLabel": {
"nullable": true,
"type": "string"
},
"redemptionCount": {
"format": "int32",
"type": "integer"
},
"revokedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"shareCodeId": {
"format": "uuid",
"type": "string"
},
"state": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ImmigrationStatusDto": {
"additionalProperties": false,
"properties": {
"brpMask": {
"nullable": true,
"type": "string"
},
"brpRetiredAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"brpValidUntil": {
"format": "date",
"type": "string"
},
"canPerformCutover": {
"type": "boolean"
},
"canonicalAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"eVisaCredentialId": {
"nullable": true,
"type": "string"
},
"eVisaValidFrom": {
"format": "date",
"nullable": true,
"type": "string"
},
"eVisaValidUntil": {
"format": "date",
"nullable": true,
"type": "string"
},
"shareCodes": {
"items": {
"$ref": "#/components/schemas/ImmigrationShareCodeDto"
},
"nullable": true,
"type": "array"
},
"stage": {
"nullable": true,
"type": "string"
},
"statusVersion": {
"format": "int32",
"type": "integer"
},
"supersessionReceiptRef": {
"nullable": true,
"type": "string"
},
"transitionId": {
"format": "uuid",
"type": "string"
},
"verifications": {
"items": {
"$ref": "#/components/schemas/ImmigrationVerificationDto"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"ImmigrationVerificationConsoleDto": {
"additionalProperties": false,
"properties": {
"policy": {
"$ref": "#/components/schemas/ImmigrationVerificationPolicyDto"
},
"requests": {
"items": {
"$ref": "#/components/schemas/ImmigrationVerificationRequestDto"
},
"nullable": true,
"type": "array"
},
"verifications": {
"items": {
"$ref": "#/components/schemas/ImmigrationVerificationDto"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"ImmigrationVerificationDto": {
"additionalProperties": false,
"properties": {
"basis": {
"nullable": true,
"type": "string"
},
"checkedAt": {
"format": "date-time",
"type": "string"
},
"claimType": {
"nullable": true,
"type": "string"
},
"credentialId": {
"nullable": true,
"type": "string"
},
"entitlementValidUntil": {
"format": "date",
"nullable": true,
"type": "string"
},
"maxStalenessDays": {
"format": "int32",
"type": "integer"
},
"outcome": {
"nullable": true,
"type": "string"
},
"requiresRecheck": {
"type": "boolean"
},
"shareCodeId": {
"format": "uuid",
"type": "string"
},
"statusVersion": {
"format": "int32",
"type": "integer"
},
"subjectStage": {
"nullable": true,
"type": "string"
},
"verificationId": {
"format": "uuid",
"type": "string"
},
"verifierOrgRef": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ImmigrationVerificationPolicyDto": {
"additionalProperties": false,
"properties": {
"acceptedClaimTypes": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"acceptedJurisdictions": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"maxStalenessDays": {
"format": "int32",
"type": "integer"
},
"organizationRef": {
"nullable": true,
"type": "string"
},
"requireCanonicalEVisa": {
"type": "boolean"
}
},
"type": "object"
},
"ImmigrationVerificationRequestDto": {
"additionalProperties": false,
"properties": {
"claimType": {
"nullable": true,
"type": "string"
},
"dueOn": {
"format": "date",
"type": "string"
},
"fulfilledAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"fulfilledByVerificationId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"requestId": {
"format": "uuid",
"type": "string"
},
"requestedAt": {
"format": "date-time",
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"subjectRef": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InboundResidencyDecisionDto": {
"additionalProperties": false,
"properties": {
"adequacy": {
"nullable": true,
"type": "string"
},
"destinationInstance": {
"nullable": true,
"type": "string"
},
"destinationJurisdiction": {
"nullable": true,
"type": "string"
},
"lawfulBasisRef": {
"nullable": true,
"type": "string"
},
"originJurisdiction": {
"nullable": true,
"type": "string"
},
"sourceInstance": {
"nullable": true,
"type": "string"
},
"translatedOnly": {
"type": "boolean"
}
},
"type": "object"
},
"IncidentActionRequest": {
"additionalProperties": false,
"description": "Body of a console incident action.",
"properties": {
"rootCause": {
"description": "Required by the owner to resolve. The console never collected it, which is half of why this\r\nendpoint could not drive the lifecycle.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InstanceActivationStatus": {
"enum": [
"Unknown",
"Active"
],
"type": "string"
},
"InstanceConfiguration": {
"additionalProperties": false,
"properties": {
"autoScalingEnabled": {
"readOnly": true,
"type": "boolean"
},
"backupEnabled": {
"readOnly": true,
"type": "boolean"
},
"backupRetentionDays": {
"format": "int32",
"readOnly": true,
"type": "integer"
},
"highAvailabilityEnabled": {
"readOnly": true,
"type": "boolean"
},
"maxApiRequestsPerHour": {
"format": "int32",
"readOnly": true,
"type": "integer"
},
"maxConnections": {
"format": "int32",
"readOnly": true,
"type": "integer"
},
"maxStorageGb": {
"format": "int64",
"readOnly": true,
"type": "integer"
},
"monitoringEnabled": {
"readOnly": true,
"type": "boolean"
}
},
"type": "object"
},
"InstanceConfigurationDto": {
"additionalProperties": false,
"properties": {
"autoScalingEnabled": {
"example": true,
"type": "boolean"
},
"backupEnabled": {
"example": true,
"type": "boolean"
},
"backupRetentionDays": {
"example": 30,
"format": "int32",
"type": "integer"
},
"highAvailabilityEnabled": {
"example": true,
"type": "boolean"
},
"maxApiRequestsPerHour": {
"example": 10000,
"format": "int32",
"type": "integer"
},
"maxConnections": {
"example": 1000,
"format": "int32",
"type": "integer"
},
"maxStorageGb": {
"example": 500,
"format": "int64",
"type": "integer"
},
"monitoringEnabled": {
"example": true,
"type": "boolean"
}
},
"type": "object"
},
"InstanceDeploymentModel": {
"enum": [
"Unspecified",
"CloudAzure",
"CloudAWS",
"CloudGCP",
"OnPremise",
"Hybrid",
"AirGapped",
"PartnerSovereignCloud",
"CloudOracle",
"CustomerCloud",
"ServiceProviderOperated"
],
"type": "string"
},
"InstanceDiscoveryDocument": {
"additionalProperties": false,
"description": "Public, anonymous-readable instance discovery document served at\r\n`GET /api/v{version}/discovery/.well-known/instance`. Contains\r\nonly metadata — no PII, no tenant data — so it is safe to expose\r\nwithout authentication per RFC 8615.",
"properties": {
"apiVersions": {
"description": "API versions this instance currently advertises.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"discoveryEndpoint": {
"description": "User-discovery endpoint URL template.",
"nullable": true,
"type": "string"
},
"generatedAt": {
"description": "UTC timestamp when the document was generated.",
"format": "date-time",
"type": "string"
},
"healthEndpoint": {
"description": "Liveness endpoint URL fragment.",
"nullable": true,
"type": "string"
},
"instanceId": {
"description": "Stable identifier of this instance.",
"nullable": true,
"type": "string"
},
"metricsEndpoint": {
"description": "Prometheus metrics endpoint URL fragment.",
"nullable": true,
"type": "string"
},
"readyEndpoint": {
"description": "Readiness endpoint URL fragment.",
"nullable": true,
"type": "string"
},
"serviceName": {
"description": "Logical service name (matches the OBS-001 service name).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InstanceListDto": {
"additionalProperties": false,
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"endpointUrl": {
"nullable": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"isHealthy": {
"type": "boolean"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"lastHealthCheck": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/InstanceStatus"
},
"type": {
"$ref": "#/components/schemas/InstanceType"
}
},
"type": "object"
},
"InstanceListDtoCursorResult": {
"additionalProperties": false,
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/InstanceListDto"
},
"nullable": true,
"type": "array"
},
"nextCursor": {
"nullable": true,
"type": "string"
},
"pageSize": {
"format": "int32",
"type": "integer"
},
"previousCursor": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InstanceMember": {
"additionalProperties": false,
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"createdBy": {
"nullable": true,
"type": "string"
},
"deletedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"deletedBy": {
"nullable": true,
"type": "string"
},
"domainEvents": {
"items": {
"$ref": "#/components/schemas/DomainEvent"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"email": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"emailVerified": {
"readOnly": true,
"type": "boolean"
},
"firstName": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"hasDomainEvents": {
"readOnly": true,
"type": "boolean"
},
"id": {
"format": "uuid",
"type": "string"
},
"instanceId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"isActive": {
"readOnly": true,
"type": "boolean"
},
"isDeleted": {
"readOnly": true,
"type": "boolean"
},
"lastName": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"roles": {
"items": {
"type": "string"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"rowVersion": {
"format": "byte",
"nullable": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"updatedBy": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InstanceMetadata": {
"additionalProperties": false,
"properties": {
"availabilityZone": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"complianceCertifications": {
"items": {
"type": "string"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"dataCenter": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"jurisdiction": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"region": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"tags": {
"additionalProperties": {
"type": "string"
},
"nullable": true,
"readOnly": true,
"type": "object"
},
"version": {
"nullable": true,
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"InstanceMetadataDto": {
"additionalProperties": false,
"properties": {
"complianceCertifications": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"tags": {
"additionalProperties": {
"type": "string"
},
"nullable": true,
"type": "object"
},
"version": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InstanceRegistry": {
"additionalProperties": false,
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"createdBy": {
"nullable": true,
"type": "string"
},
"deletedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"deletedBy": {
"nullable": true,
"type": "string"
},
"description": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"domainEvents": {
"items": {
"$ref": "#/components/schemas/DomainEvent"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"entries": {
"additionalProperties": {
"$ref": "#/components/schemas/InstanceRegistryEntry"
},
"nullable": true,
"readOnly": true,
"type": "object"
},
"hasDomainEvents": {
"readOnly": true,
"type": "boolean"
},
"id": {
"format": "uuid",
"type": "string"
},
"isDeleted": {
"readOnly": true,
"type": "boolean"
},
"lastUpdatedAt": {
"format": "date-time",
"readOnly": true,
"type": "string"
},
"name": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"rowVersion": {
"format": "byte",
"nullable": true,
"type": "string"
},
"totalInstances": {
"format": "int32",
"readOnly": true,
"type": "integer"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"updatedBy": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InstanceRegistryEntry": {
"additionalProperties": false,
"properties": {
"activationStatus": {
"$ref": "#/components/schemas/InstanceActivationStatus"
},
"activationUpdatedAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"endpointUrl": {
"nullable": true,
"type": "string"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"instanceName": {
"nullable": true,
"type": "string"
},
"instanceType": {
"$ref": "#/components/schemas/InstanceType"
},
"region": {
"nullable": true,
"type": "string"
},
"registeredAt": {
"format": "date-time",
"type": "string"
},
"registryId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"subscriptionTier": {
"nullable": true,
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"InstanceServiceLevelDto": {
"additionalProperties": false,
"properties": {
"availabilityTargetBasisPoints": {
"format": "int32",
"type": "integer"
},
"availabilityTargetPercent": {
"format": "double",
"type": "number"
},
"criticalIncidentResponseMinutes": {
"format": "int32",
"type": "integer"
},
"declaredAt": {
"format": "date-time",
"type": "string"
},
"supportCoverage": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"InstanceStatus": {
"enum": [
"Provisioning",
"Active",
"Suspended",
"Maintenance",
"Degraded",
"Failed",
"Terminating",
"Terminated"
],
"type": "string"
},
"InstanceType": {
"enum": [
"Global",
"Sovereign",
"Organization",
"Edge",
"Development"
],
"type": "string"
},
"IssueCertificateRequest": {
"additionalProperties": false,
"description": "Request model for issuing a certificate.",
"properties": {
"certificateType": {
"$ref": "#/components/schemas/CertificateType"
},
"instanceId": {
"description": "Optional instance ID to associate with the certificate.",
"format": "uuid",
"nullable": true,
"type": "string"
},
"signingCertificateThumbprint": {
"description": "Thumbprint of the signing certificate (required for leaf certificates).",
"nullable": true,
"type": "string"
},
"subjectName": {
"description": "Subject name (Distinguished Name) for the certificate.\r\nExample: \"CN=Essence Intermediate CA, O=Essence Platform, C=US\"",
"nullable": true,
"type": "string"
},
"validityDays": {
"description": "Number of days the certificate should be valid.",
"format": "int32",
"type": "integer"
}
},
"required": [
"certificateType",
"subjectName",
"validityDays"
],
"type": "object"
},
"IssueCertificateResponse": {
"additionalProperties": false,
"description": "Response model for certificate issuance.",
"properties": {
"issuedAt": {
"description": "UTC timestamp when the certificate was issued.",
"format": "date-time",
"type": "string"
},
"thumbprint": {
"description": "Thumbprint of the issued certificate.",
"nullable": true,
"type": "string"
}
},
"required": [
"issuedAt",
"thumbprint"
],
"type": "object"
},
"IssueShareCodeRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/cross-border/immigration-status/share-codes`.",
"properties": {
"claimType": {
"description": "The entitlement to prove (`right_to_work` | `right_to_rent`).",
"nullable": true,
"type": "string"
},
"recipientLabel": {
"description": "Who the code is for; optional.",
"nullable": true,
"type": "string"
},
"validityDays": {
"description": "Requested validity in days; 0 for the default.",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"IssuedShareCodeDto": {
"additionalProperties": false,
"properties": {
"claimType": {
"nullable": true,
"type": "string"
},
"code": {
"nullable": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"shareCodeId": {
"format": "uuid",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/ImmigrationStatusDto"
}
},
"type": "object"
},
"JointVentureDto": {
"additionalProperties": false,
"properties": {
"approvalQuorum": {
"additionalProperties": {
"format": "int32",
"type": "integer"
},
"nullable": true,
"type": "object"
},
"custodyModel": {
"nullable": true,
"type": "string"
},
"declineReason": {
"nullable": true,
"type": "string"
},
"dualControlScope": {
"nullable": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"proposedAt": {
"format": "date-time",
"type": "string"
},
"respondedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"sponsors": {
"items": {
"$ref": "#/components/schemas/JointVentureSponsorDto"
},
"nullable": true,
"type": "array"
},
"status": {
"nullable": true,
"type": "string"
},
"windDownCopyToBothParents": {
"type": "boolean"
},
"windDownDestructionRequiresBothParents": {
"type": "boolean"
}
},
"type": "object"
},
"JointVentureSponsorDto": {
"additionalProperties": false,
"properties": {
"billingSharePercent": {
"format": "double",
"type": "number"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"organizationName": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"KeySovereigntyAttestation": {
"additionalProperties": false,
"properties": {
"algorithm": {
"nullable": true,
"type": "string"
},
"backupId": {
"format": "uuid",
"type": "string"
},
"contentHash": {
"nullable": true,
"type": "string"
},
"encryptionKeyId": {
"nullable": true,
"type": "string"
},
"foreignRegion": {
"nullable": true,
"type": "string"
},
"keyNeverLeftSovereignKms": {
"type": "boolean"
},
"signature": {
"nullable": true,
"type": "string"
},
"signedAt": {
"format": "date-time",
"type": "string"
},
"sovereignKmsRegion": {
"nullable": true,
"type": "string"
},
"statement": {
"nullable": true,
"type": "string"
}
},
"required": [
"backupId",
"contentHash",
"encryptionKeyId",
"foreignRegion",
"signature",
"signedAt",
"sovereignKmsRegion",
"statement"
],
"type": "object"
},
"LatencyMeasurementResult": {
"additionalProperties": false,
"description": "Result model for latency measurements.",
"properties": {
"endpoint": {
"description": "Gets or sets the endpoint URL that was measured.",
"nullable": true,
"type": "string"
},
"isReachable": {
"description": "Gets or sets a value indicating whether the endpoint was reachable.",
"type": "boolean"
},
"latency": {
"description": "Gets or sets the measured round-trip latency.\r\nReturns TimeSpan.MaxValue if the endpoint is unreachable.",
"format": "date-span",
"type": "string"
},
"measuredAt": {
"description": "Gets or sets the timestamp when the measurement was performed.",
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"LinkImmigrationStatusRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/cross-border/immigration-status/link`.\r\n \r\n\nThere is deliberately no field for the BRP card number or the holder's date of birth. The\r\nentry screen asks for both so the person knows which document they are linking; the device keeps\r\nthem and sends only the trailing mask.",
"properties": {
"brpMask": {
"description": "Trailing characters of the BRP card number (1–8).",
"nullable": true,
"type": "string"
},
"brpValidUntil": {
"description": "The expiry printed on the BRP card.",
"format": "date",
"type": "string"
}
},
"type": "object"
},
"MessageStatusResponse": {
"additionalProperties": false,
"description": "Response model for message delivery status.",
"properties": {
"lastUpdatedAt": {
"description": "Gets or sets the timestamp of the last status update.",
"format": "date-time",
"type": "string"
},
"maxRetries": {
"description": "Gets or sets the maximum number of retry attempts.",
"format": "int32",
"type": "integer"
},
"messageId": {
"description": "Gets or sets the unique identifier of the message.",
"nullable": true,
"type": "string"
},
"queueDepth": {
"description": "Gets or sets the current queue depth for pending messages.",
"format": "int64",
"type": "integer"
},
"retryCount": {
"description": "Gets or sets the current retry attempt number.",
"format": "int32",
"type": "integer"
},
"status": {
"description": "Gets or sets the current delivery status (Pending, Processing, Delivered, Failed, Queued).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"MessagingHealthResponse": {
"additionalProperties": false,
"description": "Response model for messaging subsystem health check.",
"properties": {
"averageDeliveryLatency": {
"description": "Gets or sets the average message delivery latency.",
"format": "date-span",
"type": "string"
},
"checkedAt": {
"description": "Gets or sets the timestamp when the health check was performed.",
"format": "date-time",
"type": "string"
},
"circuitBreakerOpen": {
"description": "Gets or sets a value indicating whether any circuit breaker is open.",
"type": "boolean"
},
"isHealthy": {
"description": "Gets or sets a value indicating whether the messaging subsystem is healthy.",
"type": "boolean"
},
"queueDepth": {
"description": "Gets or sets the current queue depth for pending messages.",
"format": "int64",
"type": "integer"
},
"totalMessagesDelivered": {
"description": "Gets or sets the total number of messages delivered successfully.",
"format": "int64",
"type": "integer"
},
"totalMessagesFailed": {
"description": "Gets or sets the total number of messages that failed permanently.",
"format": "int64",
"type": "integer"
},
"totalMessagesSent": {
"description": "Gets or sets the total number of messages sent.",
"format": "int64",
"type": "integer"
}
},
"type": "object"
},
"MessagingStatistics": {
"additionalProperties": false,
"properties": {
"averageDeliveryLatency": {
"format": "date-span",
"readOnly": true,
"type": "string"
},
"circuitBreakerOpen": {
"readOnly": true,
"type": "boolean"
},
"instanceId": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"p95DeliveryLatency": {
"format": "date-span",
"readOnly": true,
"type": "string"
},
"p99DeliveryLatency": {
"format": "date-span",
"readOnly": true,
"type": "string"
},
"retryRate": {
"format": "double",
"readOnly": true,
"type": "number"
},
"successRate": {
"format": "double",
"readOnly": true,
"type": "number"
},
"throughputMessagesPerSecond": {
"format": "double",
"readOnly": true,
"type": "number"
},
"totalMessagesDelivered": {
"format": "int64",
"readOnly": true,
"type": "integer"
},
"totalMessagesFailed": {
"format": "int64",
"readOnly": true,
"type": "integer"
},
"totalMessagesQueued": {
"format": "int64",
"readOnly": true,
"type": "integer"
},
"totalMessagesSent": {
"format": "int64",
"readOnly": true,
"type": "integer"
},
"windowEnd": {
"format": "date-time",
"readOnly": true,
"type": "string"
},
"windowStart": {
"format": "date-time",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"ModuleEntry": {
"additionalProperties": false,
"description": "Represents an installed module entry surfaced by the organization module endpoints.",
"properties": {
"category": {
"nullable": true,
"type": "string"
},
"description": {
"nullable": true,
"type": "string"
},
"enabled": {
"type": "boolean"
},
"installedAt": {
"format": "date-time",
"type": "string"
},
"moduleId": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"type": "string"
},
"version": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OpenRenunciationTeardownRequest": {
"additionalProperties": false,
"description": "The irreversible confirm's payload.",
"properties": {
"credentialRefs": {
"description": "Opaque references to the nationality-derived credentials the teardown will revoke. Carried to\r\nEPIC 6 so it can attribute EPIC 9's later credential-revoked events to this renunciation.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"jurisdiction": {
"description": "Non-PII code of the nationality being renounced.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OpenReturningNationalIntakeRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/cross-border/returning-national/intake`. Carries the corridor\r\nand the ZK foreign-credential references only; the returning national is taken from the caller's\r\nJWT subject and never from this body.",
"properties": {
"credentials": {
"description": "The foreign credential references the person is arriving with (at least one).",
"items": {
"$ref": "#/components/schemas/ForeignCredentialCaptureRequest"
},
"nullable": true,
"type": "array"
},
"destinationJurisdiction": {
"description": "The destination (home) jurisdiction code.",
"nullable": true,
"type": "string"
},
"originJurisdiction": {
"description": "The origin (departure) jurisdiction code.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OptimalInstanceRequest": {
"additionalProperties": false,
"description": "Request model for `POST /api/v1/discovery/optimal` — the upstream GeoIP2 lookup outcome\r\nused to resolve the optimal instance for a client (FR-03.024b).",
"properties": {
"confidence": {
"description": "Gets or sets the GeoIP country-confidence (0–100). Defaults to 0 when absent.",
"format": "int32",
"nullable": true,
"type": "integer"
},
"countryCode": {
"description": "Gets or sets the ISO 3166-1 alpha-2 client country from the GeoIP2 lookup.\r\nOmitted or empty models a GeoIP-unresolvable lookup.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OrgHostOrganizationResponse": {
"additionalProperties": false,
"properties": {
"organizationId": {
"format": "uuid",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OrgRealmDiscoveryRequest": {
"additionalProperties": false,
"properties": {
"host": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"OrgResidencyEvidencePackageDto": {
"additionalProperties": false,
"properties": {
"generatedAt": {
"format": "date-time",
"type": "string"
},
"notices": {
"items": {
"$ref": "#/components/schemas/OrgResidencyRelocationNoticeDto"
},
"nullable": true,
"type": "array"
},
"status": {
"$ref": "#/components/schemas/OrgResidencyStatusDto"
}
},
"required": [
"generatedAt",
"notices",
"status"
],
"type": "object"
},
"OrgResidencyRelocationNoticeDto": {
"additionalProperties": false,
"properties": {
"destinationRegion": {
"nullable": true,
"type": "string"
},
"effectiveAt": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"legalBasis": {
"nullable": true,
"type": "string"
},
"operationReference": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"plainLanguageImpact": {
"nullable": true,
"type": "string"
},
"raisedAt": {
"format": "date-time",
"type": "string"
},
"raisedBy": {
"nullable": true,
"type": "string"
},
"respondedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"respondedBy": {
"nullable": true,
"type": "string"
},
"response": {
"nullable": true,
"type": "string"
},
"responseComment": {
"nullable": true,
"type": "string"
},
"sourceRegion": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
}
},
"required": [
"destinationRegion",
"effectiveAt",
"id",
"legalBasis",
"organizationId",
"plainLanguageImpact",
"raisedAt",
"raisedBy",
"sourceRegion",
"status"
],
"type": "object"
},
"OrgResidencyStatusDto": {
"additionalProperties": false,
"properties": {
"currentRegion": {
"nullable": true,
"type": "string"
},
"effectiveAt": {
"format": "date-time",
"type": "string"
},
"evidencePackageUrl": {
"nullable": true,
"type": "string"
},
"legalBasis": {
"nullable": true,
"type": "string"
},
"noticeCount": {
"format": "int32",
"type": "integer"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"pendingRelocation": {
"$ref": "#/components/schemas/OrgResidencyRelocationNoticeDto"
}
},
"required": [
"currentRegion",
"effectiveAt",
"evidencePackageUrl",
"legalBasis",
"noticeCount",
"organizationId"
],
"type": "object"
},
"OrgSettings": {
"additionalProperties": false,
"description": "Represents organization-level settings.",
"properties": {
"billingEmail": {
"nullable": true,
"type": "string"
},
"country": {
"nullable": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"domain": {
"nullable": true,
"type": "string"
},
"employeeCount": {
"nullable": true,
"type": "string"
},
"industry": {
"nullable": true,
"type": "string"
},
"locale": {
"nullable": true,
"type": "string"
},
"logoUrl": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"primaryContactEmail": {
"nullable": true,
"type": "string"
},
"primaryContactName": {
"nullable": true,
"type": "string"
},
"slug": {
"nullable": true,
"type": "string"
},
"timezone": {
"nullable": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"OrganizationCreatorType": {
"enum": [
"Unspecified",
"SelfServe",
"Partner",
"EssenceOperator",
"Sponsor"
],
"type": "string"
},
"OrganizationInstanceDto": {
"additionalProperties": false,
"properties": {
"configuration": {
"$ref": "#/components/schemas/InstanceConfigurationDto"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"customDomain": {
"nullable": true,
"type": "string"
},
"customDomainEnabled": {
"type": "boolean"
},
"endpointUrl": {
"nullable": true,
"type": "string"
},
"globalInstanceId": {
"format": "uuid",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"isDedicated": {
"type": "boolean"
},
"isHealthy": {
"type": "boolean"
},
"lastHealthCheck": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"metadata": {
"$ref": "#/components/schemas/InstanceMetadataDto"
},
"name": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"organizationName": {
"nullable": true,
"type": "string"
},
"status": {
"$ref": "#/components/schemas/InstanceStatus"
},
"type": {
"$ref": "#/components/schemas/InstanceType"
},
"updatedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"PasswordPolicySettings": {
"additionalProperties": false,
"description": "Represents password policy configuration.",
"properties": {
"maxAgeDays": {
"format": "int32",
"type": "integer"
},
"minLength": {
"format": "int32",
"type": "integer"
},
"preventReuse": {
"format": "int32",
"type": "integer"
},
"requireDigit": {
"type": "boolean"
},
"requireLowercase": {
"type": "boolean"
},
"requireSpecialChar": {
"type": "boolean"
},
"requireUppercase": {
"type": "boolean"
}
},
"type": "object"
},
"PerformCutoverRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/cross-border/immigration-status/cutover`.",
"properties": {
"actor": {
"description": "Who is performing the cutover (`holder` | `platform`).",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProblemDetails": {
"additionalProperties": {},
"properties": {
"detail": {
"nullable": true,
"type": "string"
},
"instance": {
"nullable": true,
"type": "string"
},
"status": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"title": {
"nullable": true,
"type": "string"
},
"type": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProposeJointVentureRequest": {
"additionalProperties": false,
"properties": {
"counterpartBillingSharePercent": {
"format": "double",
"type": "number"
},
"counterpartOrganizationId": {
"format": "uuid",
"type": "string"
},
"counterpartOrganizationName": {
"nullable": true,
"type": "string"
},
"custodyModel": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"proposingBillingSharePercent": {
"format": "double",
"type": "number"
},
"proposingOrganizationName": {
"nullable": true,
"type": "string"
},
"requireBothParents": {
"type": "boolean"
}
},
"type": "object"
},
"ProvisionSupervisedInstanceCommand": {
"additionalProperties": false,
"properties": {
"ageAssuranceLevel": {
"$ref": "#/components/schemas/AgeAssuranceLevel"
},
"ageAssuranceMethod": {
"nullable": true,
"type": "string"
},
"controlTemplateRef": {
"nullable": true,
"type": "string"
},
"graduationScheduleRef": {
"nullable": true,
"type": "string"
},
"guardianId": {
"format": "uuid",
"type": "string"
},
"supervisedInstanceId": {
"format": "uuid",
"type": "string"
},
"supervisionEndsOn": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ProvisioningStatusDto": {
"additionalProperties": false,
"properties": {
"completedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"currentStep": {
"format": "int32",
"type": "integer"
},
"errorCategory": {
"nullable": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"instanceUrl": {
"nullable": true,
"type": "string"
},
"isRetryable": {
"type": "boolean"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"percentComplete": {
"format": "int32",
"type": "integer"
},
"rollbackSuccessful": {
"nullable": true,
"type": "boolean"
},
"startedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"totalSteps": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"PublicInstanceListResponse": {
"additionalProperties": false,
"properties": {
"instances": {
"items": {
"$ref": "#/components/schemas/PublicInstanceOptionDto"
},
"nullable": true,
"type": "array"
},
"regions": {
"items": {
"$ref": "#/components/schemas/PublicRegionDto"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"PublicInstanceOptionDto": {
"additionalProperties": false,
"properties": {
"displayName": {
"nullable": true,
"type": "string"
},
"id": {
"nullable": true,
"type": "string"
},
"jurisdiction": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PublicRegionDto": {
"additionalProperties": false,
"properties": {
"code": {
"nullable": true,
"type": "string"
},
"displayName": {
"nullable": true,
"type": "string"
},
"instances": {
"items": {
"$ref": "#/components/schemas/PublicRegionInstanceDto"
},
"nullable": true,
"type": "array"
},
"regulatoryFramework": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"PublicRegionInstanceDto": {
"additionalProperties": false,
"properties": {
"displayName": {
"nullable": true,
"type": "string"
},
"instanceId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RaiseRelocationNoticeBody": {
"additionalProperties": false,
"description": "Request body to raise a pre-cutover residency relocation notice for one organisation.",
"properties": {
"destinationRegion": {
"description": "Region the organisation's data will reside in after cutover.",
"nullable": true,
"type": "string"
},
"effectiveAt": {
"description": "When the relocation takes effect (UTC); must be in the future.",
"format": "date-time",
"type": "string"
},
"legalBasis": {
"description": "Legal basis for holding the data in the destination region.",
"nullable": true,
"type": "string"
},
"operationReference": {
"description": "Originating EPIC 88 residency-migration lifecycle operation, when tracked.",
"nullable": true,
"type": "string"
},
"organizationId": {
"description": "Organisation being re-homed.",
"format": "uuid",
"type": "string"
},
"plainLanguageImpact": {
"description": "Plain-language description of what changes for the organisation.",
"nullable": true,
"type": "string"
},
"sourceRegion": {
"description": "Region the organisation's data resides in today.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RaiseVerificationRequestsRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/cross-border/immigration-status/verification-requests`.",
"properties": {
"claimType": {
"description": "The entitlement claim being asked for.",
"nullable": true,
"type": "string"
},
"dueOn": {
"description": "Date a response is needed by.",
"format": "date",
"type": "string"
},
"subjectRefs": {
"description": "The organisation's own references for the people being asked.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"ReassignRegistryRequest": {
"additionalProperties": false,
"description": "Request body for M:Essence.Core.Instance.Api.Controllers.RegistryController.Reassign(Essence.Core.Instance.Api.Controllers.ReassignRegistryRequest,System.Threading.CancellationToken).",
"properties": {
"region": {
"nullable": true,
"type": "string"
},
"userId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"ReceiveMessageRequest": {
"additionalProperties": false,
"description": "Request model for receiving a cross-instance message.",
"properties": {
"maxRetries": {
"description": "Gets or sets the maximum number of retry attempts (default: 3).",
"format": "int32",
"nullable": true,
"type": "integer"
},
"messageId": {
"description": "Gets or sets the unique identifier of the message.",
"nullable": true,
"type": "string"
},
"payload": {
"description": "Gets or sets the encrypted message payload (up to 1 MB per NFR-03.022).",
"nullable": true,
"type": "string"
},
"sourceInstanceId": {
"description": "Gets or sets the source instance ID sending the message.",
"nullable": true,
"type": "string"
},
"targetInstanceId": {
"description": "Gets or sets the target instance ID receiving the message.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ReceiveMessageResponse": {
"additionalProperties": false,
"description": "Response model for message acceptance confirmation.",
"properties": {
"correlationId": {
"description": "Gets or sets the correlation ID for distributed tracing.",
"nullable": true,
"type": "string"
},
"messageId": {
"description": "Gets or sets the unique identifier of the received message.",
"nullable": true,
"type": "string"
},
"receivedAt": {
"description": "Gets or sets the timestamp when the message was received.",
"format": "date-time",
"type": "string"
},
"status": {
"description": "Gets or sets the current status of the message.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RecordSovereignInstanceOperatorRequest": {
"additionalProperties": false,
"properties": {
"operatorLegalJurisdiction": {
"nullable": true,
"type": "string"
},
"operatorOrganizationId": {
"format": "uuid",
"type": "string"
},
"reason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RegisterDrivingEntitlementRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/cross-border/driving-entitlement`. Carries ZK held-entitlement\r\nmetadata only; the owner is taken from the caller's JWT subject and never from this body.",
"properties": {
"categories": {
"description": "Held categories with optional per-category validity windows.",
"items": {
"$ref": "#/components/schemas/DrivingCategoryGrantInput"
},
"nullable": true,
"type": "array"
},
"holderRef": {
"description": "Opaque holder reference (ZK — never a name or licence number).",
"nullable": true,
"type": "string"
},
"issuingJurisdiction": {
"description": "Issuing jurisdiction (ISO 3166 alpha-2).",
"nullable": true,
"type": "string"
},
"licenceExpiry": {
"description": "Licence (whole-document) expiry (ISO date).",
"format": "date",
"type": "string"
},
"restrictionCodes": {
"description": "Harmonised (EU Annex I) restriction codes; empty when unrestricted.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RegisterInstanceCommand": {
"additionalProperties": false,
"properties": {
"endpointUrl": {
"nullable": true,
"type": "string"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"instanceName": {
"nullable": true,
"type": "string"
},
"instanceType": {
"$ref": "#/components/schemas/InstanceType"
},
"region": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RegistrationRequestDto": {
"additionalProperties": false,
"properties": {
"approvalConditions": {
"nullable": true,
"type": "string"
},
"approvalTokenConsumed": {
"type": "boolean"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"expiresAt": {
"format": "date-time",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"isDedicated": {
"nullable": true,
"type": "boolean"
},
"jurisdictionCode": {
"nullable": true,
"type": "string"
},
"justification": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"organizationName": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"rejectionReason": {
"nullable": true,
"type": "string"
},
"requestType": {
"nullable": true,
"type": "string"
},
"requestedByEmail": {
"nullable": true,
"type": "string"
},
"requestedByUserId": {
"format": "uuid",
"type": "string"
},
"requestingInstanceId": {
"format": "uuid",
"type": "string"
},
"requestingInstanceName": {
"nullable": true,
"type": "string"
},
"reviewedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"reviewedByUserId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"slug": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"targetInstanceId": {
"format": "uuid",
"type": "string"
},
"targetInstanceType": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RejectRegistrationRequestBody": {
"additionalProperties": false,
"description": "Request body for rejecting a registration request.",
"properties": {
"reason": {
"description": "Gets or sets the reason for rejection.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RenunciationTeardownCaseDto": {
"additionalProperties": false,
"properties": {
"caseId": {
"format": "uuid",
"type": "string"
},
"completedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"openedAt": {
"format": "date-time",
"type": "string"
},
"readyForReceipt": {
"type": "boolean"
},
"receiptDigest": {
"nullable": true,
"type": "string"
},
"status": {
"nullable": true,
"type": "string"
},
"steps": {
"items": {
"$ref": "#/components/schemas/RenunciationTeardownStepDto"
},
"nullable": true,
"type": "array"
},
"templateId": {
"nullable": true,
"type": "string"
},
"validityCeilingDays": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RenunciationTeardownStepDto": {
"additionalProperties": false,
"properties": {
"blockedReason": {
"nullable": true,
"type": "string"
},
"detail": {
"nullable": true,
"type": "string"
},
"evidenceRef": {
"nullable": true,
"type": "string"
},
"key": {
"nullable": true,
"type": "string"
},
"label": {
"nullable": true,
"type": "string"
},
"obligationCode": {
"nullable": true,
"type": "string"
},
"occurredAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"sequence": {
"format": "int32",
"type": "integer"
},
"status": {
"nullable": true,
"type": "string"
},
"timelineDays": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RenunciationTeardownTemplateDto": {
"additionalProperties": false,
"properties": {
"jurisdiction": {
"nullable": true,
"type": "string"
},
"notifyList": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"steps": {
"items": {
"$ref": "#/components/schemas/RenunciationTeardownStepDto"
},
"nullable": true,
"type": "array"
},
"templateId": {
"nullable": true,
"type": "string"
},
"validityCeilingDays": {
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RequestCrossBorderApprovalBody": {
"additionalProperties": false,
"description": "Request body to raise a new cross-border approval request (S-03.02 write).",
"properties": {
"dataClassification": {
"description": "Highest data classification involved.",
"nullable": true,
"type": "string"
},
"purpose": {
"description": "Human-readable purpose / legal context of the requested transfer.",
"nullable": true,
"type": "string"
},
"recipient": {
"description": "Recipient (receiving instance / organisation) of the requested transfer.",
"nullable": true,
"type": "string"
},
"sourceJurisdiction": {
"description": "Source jurisdiction the data originates from.",
"nullable": true,
"type": "string"
},
"targetJurisdiction": {
"description": "Target jurisdiction the transfer would target.",
"nullable": true,
"type": "string"
},
"territories": {
"description": "Territories covered; empty = whole target jurisdiction.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"RetryFailedMessagesResponse": {
"additionalProperties": false,
"description": "Response model for retry failed messages operation.",
"properties": {
"processedAt": {
"description": "Gets or sets the timestamp when the retry operation was processed.",
"format": "date-time",
"type": "string"
},
"successCount": {
"description": "Gets or sets the number of messages successfully retried and delivered.",
"format": "int32",
"type": "integer"
}
},
"type": "object"
},
"RetryProvisioningRequest": {
"additionalProperties": false,
"description": "Optional body of `POST /api/v1/instances/organization/{id}/retry-provisioning`. An empty\r\nbody is the original call and behaves exactly as before.",
"properties": {
"adminDisplayName": {
"description": "The founding administrator's display name, with Essence.Core.Instance.Api.Controllers.RetryProvisioningRequest.AdminEmail.",
"nullable": true,
"type": "string"
},
"adminEmail": {
"description": "The founding administrator's email (#22453). Read from the onboarding provisioner only\r\n(Essence.Core.Instance.Api.Authorization.OrgProvisionerRetryableAttribute.Scope); ignored from anyone else.",
"nullable": true,
"type": "string"
},
"force": {
"description": "Platform-operator override (#22452): retry a cleanly rolled-back workflow whatever its failure\r\ncategory. Honoured for a cross-instance platform operator only (403 otherwise) and only with a\r\nEssence.Core.Instance.Api.Controllers.RetryProvisioningRequest.Reason; recorded on the workflow.",
"type": "boolean"
},
"reason": {
"description": "Why the override is safe now — e.g. the deploy that fixed the cause. Required with Essence.Core.Instance.Api.Controllers.RetryProvisioningRequest.Force.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ReturningNationalIntakeDto": {
"additionalProperties": false,
"properties": {
"credentials": {
"items": {
"$ref": "#/components/schemas/ForeignCredentialRefDto"
},
"nullable": true,
"type": "array"
},
"creditPreview": {
"$ref": "#/components/schemas/AssuranceCreditPreviewDto"
},
"destinationJurisdiction": {
"nullable": true,
"type": "string"
},
"intakeId": {
"format": "uuid",
"type": "string"
},
"originJurisdiction": {
"nullable": true,
"type": "string"
},
"residency": {
"$ref": "#/components/schemas/InboundResidencyDecisionDto"
}
},
"type": "object"
},
"ReturningNationalIntakeFacts": {
"additionalProperties": false,
"properties": {
"basisIssuerJurisdiction": {
"nullable": true,
"type": "string"
},
"basisOriginLoA": {
"nullable": true,
"type": "string"
},
"basisOriginScheme": {
"nullable": true,
"type": "string"
},
"corridorOriginJurisdiction": {
"nullable": true,
"type": "string"
},
"intakeId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"RevokeCertificateRequest": {
"additionalProperties": false,
"description": "Request model for revoking a certificate.",
"properties": {
"reason": {
"$ref": "#/components/schemas/CertificateRevocationReason"
}
},
"required": [
"reason"
],
"type": "object"
},
"RevokeCorridorAdequacyBody": {
"additionalProperties": false,
"description": "Request body for a matrix-maintenance corridor flip-to-inadequate (FR-03.029a).",
"properties": {
"reason": {
"description": "Operator-supplied reason for the matrix change (required).",
"nullable": true,
"type": "string"
},
"sourceJurisdiction": {
"description": "Source jurisdiction of the corridor losing adequacy.",
"nullable": true,
"type": "string"
},
"targetJurisdiction": {
"description": "Target jurisdiction of the corridor losing adequacy.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RevokeRegistrationRequestBody": {
"additionalProperties": false,
"description": "Request body for revoking a registration.",
"properties": {
"reason": {
"description": "Gets or sets the reason for revocation.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RolloutReasonRequest": {
"additionalProperties": false,
"description": "Body of the halt / abandon actions.",
"properties": {
"reason": {
"description": "Why the operator is acting.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RolloutRegionOutcomeRequest": {
"additionalProperties": false,
"description": "Body of `POST …/rollouts/{id}/regions/{region}/outcome`.",
"properties": {
"detail": {
"description": "What the gate observed; required when unhealthy.",
"nullable": true,
"type": "string"
},
"healthy": {
"description": "Whether the region passed its post-roll health gate.",
"type": "boolean"
}
},
"type": "object"
},
"RoutingDecision": {
"additionalProperties": false,
"properties": {
"confidenceScore": {
"format": "double",
"readOnly": true,
"type": "number"
},
"decidedAt": {
"format": "date-time",
"readOnly": true,
"type": "string"
},
"estimatedLatency": {
"format": "date-span",
"readOnly": true,
"type": "string"
},
"intermediateHops": {
"items": {
"type": "string"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"isDirect": {
"readOnly": true,
"type": "boolean"
},
"isHighConfidence": {
"readOnly": true,
"type": "boolean"
},
"isMultiHop": {
"readOnly": true,
"type": "boolean"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"nullable": true,
"readOnly": true,
"type": "object"
},
"strategy": {
"$ref": "#/components/schemas/RoutingStrategy"
},
"targetEndpoint": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"targetInstanceId": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"totalHops": {
"format": "int32",
"readOnly": true,
"type": "integer"
}
},
"type": "object"
},
"RoutingHealthDto": {
"additionalProperties": false,
"properties": {
"checkedAt": {
"format": "date-time",
"type": "string"
},
"routableInstanceCount": {
"format": "int32",
"type": "integer"
},
"routableRegionCount": {
"format": "int32",
"type": "integer"
},
"status": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"RoutingStrategy": {
"enum": [
"LowestLatency",
"GeographicProximity",
"LoadBalanced",
"RegionAffinity",
"RoundRobin",
"Weighted",
"HomeInstance",
"MultiHop",
"Custom"
],
"type": "string"
},
"SecuritySettings": {
"additionalProperties": false,
"description": "Represents security configuration settings.",
"properties": {
"auditLogRetentionDays": {
"format": "int32",
"type": "integer"
},
"dataResidencyRegion": {
"nullable": true,
"type": "string"
},
"ipAllowList": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"ipAllowListEnabled": {
"type": "boolean"
},
"maxSessionsPerUser": {
"format": "int32",
"type": "integer"
},
"mfaMethods": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"mfaRequired": {
"type": "boolean"
},
"passwordPolicy": {
"$ref": "#/components/schemas/PasswordPolicySettings"
},
"sessionTimeoutMinutes": {
"format": "int32",
"type": "integer"
},
"ssoEnabled": {
"type": "boolean"
},
"ssoEntityId": {
"nullable": true,
"type": "string"
},
"ssoProvider": {
"nullable": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"SelfHostedBootstrapPackage": {
"additionalProperties": false,
"properties": {
"blockers": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"composeEnvironment": {
"additionalProperties": {
"type": "string"
},
"nullable": true,
"type": "object"
},
"deploymentModel": {
"$ref": "#/components/schemas/InstanceDeploymentModel"
},
"prerequisites": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"runbook": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"SendMessageCommand": {
"additionalProperties": false,
"properties": {
"encryptedBody": {
"nullable": true,
"type": "string"
},
"encryptedMetadata": {
"nullable": true,
"type": "string"
},
"encryptedSubject": {
"nullable": true,
"type": "string"
},
"encryptionKeyId": {
"nullable": true,
"type": "string"
},
"expirationDays": {
"format": "int32",
"type": "integer"
},
"recipientId": {
"format": "uuid",
"type": "string"
},
"recipientInstanceId": {
"format": "uuid",
"type": "string"
},
"senderId": {
"format": "uuid",
"type": "string"
},
"senderInstanceId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"SendMessageRequest": {
"additionalProperties": false,
"description": "Request model for sending a cross-instance message. Implements\r\nEssence.Core.Instance.Api.Filters.ICrossInstanceResidencyAddressed so the server-declared\r\n`[EnforceDataResidency]` filter can resolve the send's target jurisdiction.",
"properties": {
"maxRetries": {
"description": "Gets or sets the maximum number of retry attempts (default: 3).",
"format": "int32",
"nullable": true,
"type": "integer"
},
"payload": {
"description": "Gets or sets the encrypted message payload (up to 1 MB per NFR-03.022).",
"nullable": true,
"type": "string"
},
"sourceInstanceId": {
"description": "Gets or sets the source instance ID sending the message.",
"nullable": true,
"type": "string"
},
"targetInstanceId": {
"description": "Gets or sets the target instance ID receiving the message.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SendMessageResponse": {
"additionalProperties": false,
"description": "Response model for send message operation.",
"properties": {
"errorMessage": {
"description": "Gets or sets the error message if delivery failed.",
"nullable": true,
"type": "string"
},
"isFailed": {
"description": "Gets or sets a value indicating whether the message delivery failed permanently.",
"type": "boolean"
},
"isQueued": {
"description": "Gets or sets a value indicating whether the message was queued for later delivery.",
"type": "boolean"
},
"isSuccess": {
"description": "Gets or sets a value indicating whether the message was delivered successfully.",
"type": "boolean"
},
"messageId": {
"description": "Gets or sets the unique identifier of the sent message.",
"nullable": true,
"type": "string"
},
"status": {
"description": "Gets or sets the current delivery status.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SovereignInstanceDto": {
"additionalProperties": false,
"properties": {
"allowedTransferJurisdictions": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"complianceStatus": {
"$ref": "#/components/schemas/ComplianceStatus"
},
"configuration": {
"$ref": "#/components/schemas/InstanceConfigurationDto"
},
"countryCode": {
"nullable": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"dataResidencyEnforced": {
"type": "boolean"
},
"edgeCachingEnabled": {
"type": "boolean"
},
"endpointUrl": {
"nullable": true,
"type": "string"
},
"globalInstanceId": {
"format": "uuid",
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"isHealthy": {
"type": "boolean"
},
"jurisdictionCode": {
"nullable": true,
"type": "string"
},
"jurisdictionName": {
"nullable": true,
"type": "string"
},
"lastHealthCheck": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"metadata": {
"$ref": "#/components/schemas/InstanceMetadataDto"
},
"name": {
"nullable": true,
"type": "string"
},
"regulatoryFramework": {
"nullable": true,
"type": "string"
},
"requireStandardContractualClauses": {
"type": "boolean"
},
"status": {
"$ref": "#/components/schemas/InstanceStatus"
},
"type": {
"$ref": "#/components/schemas/InstanceType"
},
"updatedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"SovereignInstanceOperatingTermsDto": {
"additionalProperties": false,
"properties": {
"operator": {
"$ref": "#/components/schemas/SovereignInstanceOperatorDto"
},
"recorded": {
"type": "boolean"
},
"serviceLevel": {
"$ref": "#/components/schemas/InstanceServiceLevelDto"
},
"sovereignInstanceId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"SovereignInstanceOperatorDto": {
"additionalProperties": false,
"properties": {
"changeReason": {
"nullable": true,
"type": "string"
},
"jurisdictionBasis": {
"nullable": true,
"type": "string"
},
"legalJurisdiction": {
"nullable": true,
"type": "string"
},
"organizationId": {
"format": "uuid",
"type": "string"
},
"recordedAt": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"SovereignRouteResult": {
"additionalProperties": false,
"description": "Result model for an FR-03.024b sovereign route resolution (the success/route case;\r\na rejection is surfaced as `HTTP 422` ProblemDetails instead).",
"properties": {
"outcome": {
"description": "The fallback outcome (`RouteToResolved` or `RouteToDefault`).",
"nullable": true,
"type": "string"
},
"reason": {
"description": "Human-readable explanation of the resolution.",
"nullable": true,
"type": "string"
},
"reasonCode": {
"description": "Machine-readable reason code for the resolution.",
"nullable": true,
"type": "string"
},
"sovereignId": {
"description": "The resolved sovereign instance id to route to.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SponsoredResolutionRequest": {
"additionalProperties": false,
"properties": {
"fundingBankOrganizationId": {
"format": "uuid",
"type": "string"
},
"mode": {
"nullable": true,
"type": "string"
},
"supplierIdentityKey": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SponsoredResolutionResponse": {
"additionalProperties": false,
"description": "AC-19-neutral. No organisation id, no provisioned/linked flag — see the controller remarks. If\r\neither is ever added here, the sponsored path leaks by default.",
"properties": {
"displayState": {
"nullable": true,
"type": "string"
},
"resolutionRef": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"StartCrossRegionRolloutRequest": {
"additionalProperties": false,
"description": "Body of `POST …/rollouts`.",
"properties": {
"fromVersion": {
"description": "Envelope version deployed now, `major.minor`.",
"nullable": true,
"type": "string"
},
"regions": {
"description": "Regions to roll, in order.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"toVersion": {
"description": "Target envelope version, `major.minor`.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"StartVaultRehomeDocument": {
"additionalProperties": false,
"description": "One document in a Essence.Core.Instance.Api.Controllers.StartVaultRehomeRequest.",
"properties": {
"documentId": {
"description": "Opaque document identifier.",
"nullable": true,
"type": "string"
},
"label": {
"description": "User-facing label shown in the per-document progress breakdown.",
"nullable": true,
"type": "string"
}
},
"required": [
"documentId",
"label"
],
"type": "object"
},
"StartVaultRehomeRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/instances/vault-rehome`. Deliberately has no user id:\r\nthe job's owner is taken from the caller's subject claim, so the body cannot be used to open a\r\nre-home against someone else's documents.",
"properties": {
"clientCorrelationId": {
"description": "The initiator's opaque correlation handle, echoed on the relay completion event so the\r\ninitiator can advance its own record off the real completion. Must not carry PII.",
"nullable": true,
"type": "string"
},
"crossesSovereignInstance": {
"description": "Whether the destination vault lives on a different sovereign instance.",
"type": "boolean"
},
"destinationInstanceId": {
"description": "The destination sovereign instance's registered identifier (not its display name) —\r\nthe key the cross-sovereign relay resolves its trusted sync endpoint from. Required when\r\nEssence.Core.Instance.Api.Controllers.StartVaultRehomeRequest.CrossesSovereignInstance is true: without it the job could be started but never\r\nexecuted (debt-2026-08-13-049).",
"nullable": true,
"type": "string"
},
"destinationInstanceName": {
"description": "Destination instance display name; required when Essence.Core.Instance.Api.Controllers.StartVaultRehomeRequest.CrossesSovereignInstance is true.",
"nullable": true,
"type": "string"
},
"destinationVaultName": {
"description": "Display name of the caller's own destination vault.",
"nullable": true,
"type": "string"
},
"documents": {
"description": "The documents to move. Must be non-empty with unique ids.",
"items": {
"$ref": "#/components/schemas/StartVaultRehomeDocument"
},
"nullable": true,
"type": "array"
},
"sourceVaultName": {
"description": "Display name of the shared vault the documents are leaving.",
"nullable": true,
"type": "string"
}
},
"required": [
"destinationVaultName",
"sourceVaultName"
],
"type": "object"
},
"SubjectApprovalRequestBody": {
"additionalProperties": false,
"description": "Request body for a subject-originated cross-border approval request.",
"properties": {
"dataClassification": {
"description": "Highest data classification involved.",
"nullable": true,
"type": "string"
},
"purpose": {
"description": "The subject's stated reason for the transfer.",
"nullable": true,
"type": "string"
},
"recipient": {
"description": "Recipient (receiving instance / organisation) of the requested transfer.",
"nullable": true,
"type": "string"
},
"sourceJurisdiction": {
"description": "Jurisdiction the subject's data resides in today.",
"nullable": true,
"type": "string"
},
"targetJurisdiction": {
"description": "Jurisdiction the subject is asking to transfer to.",
"nullable": true,
"type": "string"
},
"territories": {
"description": "Territories covered; empty = whole target jurisdiction.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"SupervisedInstanceDto": {
"additionalProperties": false,
"properties": {
"ageAssuranceAttributeId": {
"format": "uuid",
"type": "string"
},
"ageAssuranceLevel": {
"$ref": "#/components/schemas/AgeAssuranceLevel"
},
"ageAssuranceMethod": {
"nullable": true,
"type": "string"
},
"batchId": {
"format": "uuid",
"type": "string"
},
"controlTemplateRef": {
"nullable": true,
"type": "string"
},
"graduationScheduleRef": {
"nullable": true,
"type": "string"
},
"guardianId": {
"format": "uuid",
"type": "string"
},
"majorityApproaching": {
"type": "boolean"
},
"provisionedAt": {
"format": "date-time",
"type": "string"
},
"recordId": {
"format": "uuid",
"type": "string"
},
"status": {
"$ref": "#/components/schemas/SupervisionStatus"
},
"supervisedInstanceId": {
"format": "uuid",
"type": "string"
},
"supervisionEndsOn": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupervisedInstanceRosterEntry": {
"additionalProperties": false,
"properties": {
"ageAssuranceLevel": {
"$ref": "#/components/schemas/AgeAssuranceLevel"
},
"ageAssuranceMethod": {
"nullable": true,
"type": "string"
},
"supervisedInstanceId": {
"format": "uuid",
"type": "string"
},
"supervisionEndsOn": {
"format": "date-time",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SupervisionStatus": {
"enum": [
"Supervised",
"MajorityApproaching",
"Transitioning",
"Graduated"
],
"type": "string"
},
"SupplierIdentityKeyResponse": {
"additionalProperties": false,
"description": "The organisation's supplier identity, or absence. Carries the identity and nothing else:\r\nadding lifecycle state or a sponsor here would turn a token-mint lookup into the\r\nsponsorship-probing surface M:Essence.Core.Instance.Api.Controllers.SponsoredResolutionsController.Resolve(Essence.Core.Instance.Api.Controllers.SponsoredResolutionRequest,System.Threading.CancellationToken) is\r\ncareful not to be.",
"properties": {
"supplierIdentityKey": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SuspendDeveloperIdRequest": {
"additionalProperties": false,
"description": "Request payload for suspending a developer ID.",
"properties": {
"reason": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"SuspendInstanceRequest": {
"additionalProperties": false,
"description": "Request model for suspending an instance.",
"properties": {
"reason": {
"description": "Gets or sets the reason for suspension.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"TerminateInstanceRequest": {
"additionalProperties": false,
"description": "Request model for terminating an instance.",
"properties": {
"drain": {
"description": "Gets or sets whether live organisation instances beneath this one are decommissioned with\r\nit. Omitted or `false`: a parent with live children is refused with 409 (FR-03.007a).",
"nullable": true,
"type": "boolean"
},
"reason": {
"description": "Gets or sets why this instance is being decommissioned.",
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"TraefikDynamicConfiguration": {
"additionalProperties": false,
"properties": {
"http": {
"$ref": "#/components/schemas/TraefikHttpConfiguration"
}
},
"type": "object"
},
"TraefikHttpConfiguration": {
"additionalProperties": false,
"properties": {
"routers": {
"additionalProperties": {
"$ref": "#/components/schemas/TraefikRouter"
},
"nullable": true,
"type": "object"
}
},
"type": "object"
},
"TraefikRouter": {
"additionalProperties": false,
"properties": {
"entryPoints": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"middlewares": {
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"rule": {
"nullable": true,
"type": "string"
},
"service": {
"nullable": true,
"type": "string"
},
"tls": {
"$ref": "#/components/schemas/TraefikRouterTls"
}
},
"type": "object"
},
"TraefikRouterTls": {
"additionalProperties": false,
"properties": {
"certResolver": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UpdateConfigurationCommand": {
"additionalProperties": false,
"properties": {
"autoScalingEnabled": {
"type": "boolean"
},
"backupEnabled": {
"type": "boolean"
},
"backupRetentionDays": {
"format": "int32",
"type": "integer"
},
"highAvailabilityEnabled": {
"type": "boolean"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"maxApiRequestsPerHour": {
"format": "int32",
"type": "integer"
},
"maxConnections": {
"format": "int32",
"type": "integer"
},
"maxStorageGb": {
"format": "int64",
"type": "integer"
},
"monitoringEnabled": {
"type": "boolean"
}
},
"type": "object"
},
"UpdateDnsRecordCommand": {
"additionalProperties": false,
"properties": {
"newValue": {
"nullable": true,
"type": "string"
},
"recordId": {
"format": "uuid",
"type": "string"
},
"zoneId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"UpdateDocumentCommand": {
"additionalProperties": false,
"properties": {
"documentId": {
"format": "uuid",
"type": "string"
},
"encryptedMetadata": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"ownerId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"UpdateHealthCheckCommand": {
"additionalProperties": false,
"properties": {
"instanceId": {
"format": "uuid",
"type": "string"
},
"isHealthy": {
"type": "boolean"
},
"statusMessage": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UpdateInstanceEndpointCommand": {
"additionalProperties": false,
"properties": {
"instanceId": {
"format": "uuid",
"type": "string"
},
"newEndpointUrl": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UpdateInstanceHealthCommand": {
"additionalProperties": false,
"properties": {
"healthCheckStatus": {
"nullable": true,
"type": "string"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"isHealthy": {
"type": "boolean"
},
"timestamp": {
"format": "date-time",
"type": "string"
}
},
"type": "object"
},
"UpdateMetadataCommand": {
"additionalProperties": false,
"properties": {
"availabilityZone": {
"nullable": true,
"type": "string"
},
"complianceCertifications": {
"nullable": true,
"type": "string"
},
"dataCenter": {
"nullable": true,
"type": "string"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"jurisdiction": {
"nullable": true,
"type": "string"
},
"region": {
"nullable": true,
"type": "string"
},
"tags": {
"nullable": true,
"type": "string"
},
"version": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UpdateModuleRequest": {
"additionalProperties": false,
"description": "Request model for updating a module's enabled state.",
"properties": {
"enabled": {
"type": "boolean"
}
},
"type": "object"
},
"UpdatePricingPlanRequest": {
"additionalProperties": false,
"properties": {
"basePrice": {
"format": "double",
"nullable": true,
"type": "number"
},
"currency": {
"nullable": true,
"type": "string"
},
"description": {
"nullable": true,
"type": "string"
},
"features": {
"additionalProperties": {},
"nullable": true,
"type": "object"
},
"metadata": {
"additionalProperties": {
"type": "string"
},
"nullable": true,
"type": "object"
},
"name": {
"nullable": true,
"type": "string"
},
"trialDays": {
"format": "int32",
"nullable": true,
"type": "integer"
}
},
"type": "object"
},
"UpdateSovereignInstanceRegionCommand": {
"additionalProperties": false,
"properties": {
"allowedStorageRegions": {
"nullable": true,
"type": "string"
},
"allowedTransferJurisdictions": {
"nullable": true,
"type": "string"
},
"edgeCachingEnabled": {
"type": "boolean"
},
"instanceId": {
"format": "uuid",
"type": "string"
},
"primaryRegion": {
"nullable": true,
"type": "string"
},
"requireStandardContractualClauses": {
"type": "boolean"
}
},
"type": "object"
},
"UpdateVaultCommand": {
"additionalProperties": false,
"properties": {
"description": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"ownerId": {
"format": "uuid",
"type": "string"
},
"vaultId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"UpdateVaultLimitsCommand": {
"additionalProperties": false,
"properties": {
"maxDocuments": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"maxSizeBytes": {
"format": "int64",
"nullable": true,
"type": "integer"
},
"ownerId": {
"format": "uuid",
"type": "string"
},
"vaultId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"UpdateVerificationPolicyRequest": {
"additionalProperties": false,
"description": "Request body for `PUT /api/v1/cross-border/immigration-status/org-policy`.",
"properties": {
"acceptedClaimTypes": {
"description": "Accepted entitlement claims; empty or absent for all.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"acceptedJurisdictions": {
"description": "Accepted issuing jurisdictions; empty or absent for all.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
},
"maxStalenessDays": {
"description": "How long a recorded result may be relied on, in days (1–365).",
"format": "int32",
"type": "integer"
},
"requireCanonicalEVisa": {
"description": "When true, a result resolved against a physical BRP is refused.",
"type": "boolean"
}
},
"type": "object"
},
"UploadDocumentCommand": {
"additionalProperties": false,
"properties": {
"checksum": {
"nullable": true,
"type": "string"
},
"contentType": {
"nullable": true,
"type": "string"
},
"encryptedMetadata": {
"nullable": true,
"type": "string"
},
"encryptionKeyId": {
"nullable": true,
"type": "string"
},
"name": {
"nullable": true,
"type": "string"
},
"ownerId": {
"format": "uuid",
"type": "string"
},
"sizeBytes": {
"format": "int64",
"type": "integer"
},
"storageReference": {
"nullable": true,
"type": "string"
},
"vaultId": {
"format": "uuid",
"type": "string"
}
},
"type": "object"
},
"UserMessage": {
"additionalProperties": false,
"properties": {
"createdAt": {
"format": "date-time",
"type": "string"
},
"createdBy": {
"nullable": true,
"type": "string"
},
"deletedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"deletedBy": {
"nullable": true,
"type": "string"
},
"deliveryConfirmed": {
"readOnly": true,
"type": "boolean"
},
"deliveryConfirmedAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"domainEvents": {
"items": {
"$ref": "#/components/schemas/DomainEvent"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"encryptedBody": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"encryptedMetadata": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"encryptedSubject": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"encryptionKeyId": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"expiresAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"hasDomainEvents": {
"readOnly": true,
"type": "boolean"
},
"id": {
"format": "uuid",
"type": "string"
},
"isDeleted": {
"readOnly": true,
"type": "boolean"
},
"isRead": {
"readOnly": true,
"type": "boolean"
},
"readAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"recipient": {
"$ref": "#/components/schemas/InstanceMember"
},
"recipientId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"recipientInstanceId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"rowVersion": {
"format": "byte",
"nullable": true,
"type": "string"
},
"sender": {
"$ref": "#/components/schemas/InstanceMember"
},
"senderId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"senderInstanceId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"sentAt": {
"format": "date-time",
"readOnly": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"updatedBy": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"UserSummaryResponse": {
"additionalProperties": false,
"description": "Safe, outward-facing projection of an Essence.Core.Instance.Domain.Entities.InstanceMember for user discovery\r\n(profile lookup and search). Deliberately excludes the credential secret\r\n(`PasswordHash`) and login-tracking fields (`LastLoginAt`,\r\n`PasswordChangedAt`, `FailedLoginAttempts`, `LockoutEndAt`) so those can\r\nnever cross an API boundary (debt-2026-06-28-527). Mirrors the safe shape already used by\r\nthe `ListUsers` endpoint.",
"properties": {
"createdAt": {
"description": "When the account was created.",
"format": "date-time",
"type": "string"
},
"email": {
"description": "The member's email address.",
"nullable": true,
"type": "string"
},
"emailVerified": {
"description": "Whether the member's email is verified.",
"type": "boolean"
},
"firstName": {
"description": "The member's first name, if set.",
"nullable": true,
"type": "string"
},
"fullName": {
"description": "The member's display name (first + last, trimmed).",
"nullable": true,
"type": "string"
},
"id": {
"description": "The member's unique identifier.",
"format": "uuid",
"type": "string"
},
"isActive": {
"description": "Whether the account is active.",
"type": "boolean"
},
"lastName": {
"description": "The member's last name, if set.",
"nullable": true,
"type": "string"
},
"roles": {
"description": "The roles assigned to the member.",
"items": {
"type": "string"
},
"nullable": true,
"type": "array"
}
},
"type": "object"
},
"ValidationProblemDetails": {
"additionalProperties": {},
"properties": {
"detail": {
"nullable": true,
"type": "string"
},
"errors": {
"additionalProperties": {
"items": {
"type": "string"
},
"type": "array"
},
"nullable": true,
"type": "object"
},
"instance": {
"nullable": true,
"type": "string"
},
"status": {
"format": "int32",
"nullable": true,
"type": "integer"
},
"title": {
"nullable": true,
"type": "string"
},
"type": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"ValidatorRegistrationRetryResult": {
"additionalProperties": false,
"properties": {
"alreadyRegistered": {
"type": "boolean"
},
"centralValidatorId": {
"format": "uuid",
"nullable": true,
"type": "string"
},
"errorCode": {
"nullable": true,
"type": "string"
},
"errorMessage": {
"nullable": true,
"type": "string"
},
"registrationTxHash": {
"nullable": true,
"type": "string"
},
"skipped": {
"type": "boolean"
},
"success": {
"type": "boolean"
}
},
"type": "object"
},
"VaultDocumentRef": {
"additionalProperties": false,
"properties": {
"checksum": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"contentType": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"createdBy": {
"nullable": true,
"type": "string"
},
"deletedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"deletedBy": {
"nullable": true,
"type": "string"
},
"encryptedMetadata": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"encryptionKeyId": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"id": {
"format": "uuid",
"type": "string"
},
"isDeleted": {
"readOnly": true,
"type": "boolean"
},
"lastAccessedAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"name": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"rowVersion": {
"format": "byte",
"nullable": true,
"type": "string"
},
"sizeBytes": {
"format": "int64",
"readOnly": true,
"type": "integer"
},
"storageReference": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"updatedBy": {
"nullable": true,
"type": "string"
},
"vaultId": {
"format": "uuid",
"readOnly": true,
"type": "string"
}
},
"type": "object"
},
"VaultDocumentRefCursorResult": {
"additionalProperties": false,
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/VaultDocumentRef"
},
"nullable": true,
"type": "array"
},
"nextCursor": {
"nullable": true,
"type": "string"
},
"pageSize": {
"format": "int32",
"type": "integer"
},
"previousCursor": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VaultProvisioningRecord": {
"additionalProperties": false,
"properties": {
"archivedAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"createdBy": {
"nullable": true,
"type": "string"
},
"deletedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"deletedBy": {
"nullable": true,
"type": "string"
},
"description": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"documentCount": {
"format": "int32",
"readOnly": true,
"type": "integer"
},
"domainEvents": {
"items": {
"$ref": "#/components/schemas/DomainEvent"
},
"nullable": true,
"readOnly": true,
"type": "array"
},
"hasDomainEvents": {
"readOnly": true,
"type": "boolean"
},
"id": {
"format": "uuid",
"type": "string"
},
"instanceId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"isActive": {
"readOnly": true,
"type": "boolean"
},
"isDeleted": {
"readOnly": true,
"type": "boolean"
},
"lastAccessedAt": {
"format": "date-time",
"nullable": true,
"readOnly": true,
"type": "string"
},
"maxDocuments": {
"format": "int32",
"readOnly": true,
"type": "integer"
},
"maxSizeBytes": {
"format": "int64",
"readOnly": true,
"type": "integer"
},
"metadata": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"name": {
"nullable": true,
"readOnly": true,
"type": "string"
},
"ownerId": {
"format": "uuid",
"readOnly": true,
"type": "string"
},
"rowVersion": {
"format": "byte",
"nullable": true,
"type": "string"
},
"totalSizeBytes": {
"format": "int64",
"readOnly": true,
"type": "integer"
},
"updatedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"updatedBy": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VaultProvisioningRecordCursorResult": {
"additionalProperties": false,
"properties": {
"hasMore": {
"type": "boolean"
},
"items": {
"items": {
"$ref": "#/components/schemas/VaultProvisioningRecord"
},
"nullable": true,
"type": "array"
},
"nextCursor": {
"nullable": true,
"type": "string"
},
"pageSize": {
"format": "int32",
"type": "integer"
},
"previousCursor": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VaultRehomeDocumentDto": {
"additionalProperties": false,
"properties": {
"documentId": {
"nullable": true,
"type": "string"
},
"errorCategory": {
"nullable": true,
"type": "string"
},
"label": {
"nullable": true,
"type": "string"
},
"state": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VaultRehomeStatusDto": {
"additionalProperties": false,
"properties": {
"clientCorrelationId": {
"nullable": true,
"type": "string"
},
"completedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"completionEmail": {
"nullable": true,
"type": "string"
},
"completionResultHash": {
"nullable": true,
"type": "string"
},
"createdAt": {
"format": "date-time",
"type": "string"
},
"crossesSovereignInstance": {
"type": "boolean"
},
"destinationInstanceName": {
"nullable": true,
"type": "string"
},
"destinationVaultName": {
"nullable": true,
"type": "string"
},
"documents": {
"items": {
"$ref": "#/components/schemas/VaultRehomeDocumentDto"
},
"nullable": true,
"type": "array"
},
"documentsMoved": {
"format": "int32",
"type": "integer"
},
"documentsTotal": {
"format": "int32",
"type": "integer"
},
"errorCategory": {
"nullable": true,
"type": "string"
},
"percentComplete": {
"format": "int32",
"type": "integer"
},
"rehomeId": {
"format": "uuid",
"type": "string"
},
"sourceVaultName": {
"nullable": true,
"type": "string"
},
"startedAt": {
"format": "date-time",
"nullable": true,
"type": "string"
},
"state": {
"nullable": true,
"type": "string"
}
},
"type": "object"
},
"VerifyShareCodeRequest": {
"additionalProperties": false,
"description": "Request body for `POST /api/v1/cross-border/immigration-status/verify`.",
"properties": {
"code": {
"description": "The share code as the verifier typed it.",
"nullable": true,
"type": "string"
}
},
"type": "object"
}
},
"securitySchemes": {
"ApiKey": {
"description": "API Key authentication for service-to-service communication. Contact platform administrators to obtain an API key.",
"in": "header",
"name": "X-API-Key",
"type": "apiKey"
},
"Bearer": {
"bearerFormat": "JWT",
"description": "JWT Authorization header using the Bearer scheme. Enter 'Bearer' [space] and then your token in the text input below. Example: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'",
"scheme": "bearer",
"type": "http"
}
}
},
"info": {
"contact": {
"email": "api@essence.platform",
"name": "Essence Platform Team",
"url": "https://essence.platform/support"
},
"description": "API for managing Essence Platform instances (Global, Sovereign, Organization). Multi-instance architecture with federation support.\n\n## Architecture\n- **Global Instance**: Central instance for cross-organization features\n- **Sovereign Instance**: Self-hosted instances with data sovereignty\n- **Organization Instance**: Dedicated instances for enterprise customers\n\n## Features\n- Instance lifecycle management (creation, configuration, monitoring)\n- Federation between instances with trust relationships\n- User management with multi-instance support\n- Message queuing and synchronization",
"license": {
"name": "Proprietary",
"url": "https://essence.platform/license"
},
"termsOfService": "https://essence.platform/terms",
"title": "Essence Instance Service API",
"version": "v1.0"
},
"openapi": "3.0.1",
"paths": {
"/api/internal/messages": {
"post": {
"operationId": "InternalMessaging_ReceiveMessage",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"maxRetries": 0,
"messageId": "string",
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ReceiveMessageRequest"
}
},
"application/json": {
"example": {
"maxRetries": 0,
"messageId": "string",
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ReceiveMessageRequest"
}
},
"text/json": {
"example": {
"maxRetries": 0,
"messageId": "string",
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ReceiveMessageRequest"
}
}
},
"description": "The incoming message request with encrypted payload."
},
"responses": {
"202": {
"content": {
"application/json": {
"example": {
"correlationId": "string",
"messageId": "string",
"receivedAt": "2026-01-01T00:00:00.0000000+00:00",
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/ReceiveMessageResponse"
}
}
},
"description": "Message accepted for delivery."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request parameters or payload."
},
"429": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Rate limit exceeded (>10K messages/second)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Receives a cross-instance message from another instance.\r\nMessage is authenticated via mTLS through Istio service mesh.\r\nPayloads are bounded to 1 MB per NFR-03.022 (enforced at the\r\nEssence.Core.Instance.Domain.Entities.CrossInstanceMessage aggregate boundary); over-size\r\npayloads are rejected with HTTP 413.",
"tags": [
"InternalMessaging"
]
}
},
"/api/internal/messages/circuit-breaker": {
"get": {
"operationId": "InternalMessaging_GetCircuitBreakerStates",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"checkedAt": "2026-01-01T00:00:00.0000000+00:00",
"circuitBreakers": {}
},
"schema": {
"$ref": "#/components/schemas/CircuitBreakerStatesResponse"
}
}
},
"description": "Circuit breaker states retrieved successfully."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Gets the current circuit breaker states for all target instances.\r\nUseful for monitoring fault isolation and identifying unhealthy target instances.",
"tags": [
"InternalMessaging"
]
}
},
"/api/internal/messages/health": {
"get": {
"operationId": "InternalMessaging_GetHealth",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"averageDeliveryLatency": "string",
"checkedAt": "2026-01-01T00:00:00.0000000+00:00",
"circuitBreakerOpen": false,
"isHealthy": false,
"queueDepth": 0,
"totalMessagesDelivered": 0,
"totalMessagesFailed": 0,
"totalMessagesSent": 0
},
"schema": {
"$ref": "#/components/schemas/MessagingHealthResponse"
}
}
},
"description": "Health check successful."
},
"503": {
"description": "Service unavailable (circuit breakers open or critical issues)."
}
},
"summary": "Gets the health status of the messaging subsystem.\r\nIncludes circuit breaker states, queue depth, and recent delivery statistics.",
"tags": [
"InternalMessaging"
]
}
},
"/api/internal/messages/retry-failed": {
"post": {
"description": "SEC-002/SEC-004 (debt-2026-06-29-325): the retry loop is an expensive, self-targeted\r\noperation, so it is gated to a platform operator (Essence.Core.Instance.Api.Authorization.Policies.PolicyNames.GlobalAdmin) —\r\nmirroring M:Essence.Core.Instance.Api.Controllers.InternalMessagingController.SendMessage(Essence.Core.Instance.Api.Controllers.SendMessageRequest,System.Threading.CancellationToken) — rather than any InstanceServiceAccount identity, and is\r\nbound by the \"essence-strict\" per-subject rate limit (10/min) so it cannot be invoked in a tight\r\nloop to amplify load against the local mesh.",
"operationId": "InternalMessaging_RetryFailedMessages",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"processedAt": "2026-01-01T00:00:00.0000000+00:00",
"successCount": 0
},
"schema": {
"$ref": "#/components/schemas/RetryFailedMessagesResponse"
}
}
},
"description": "Retry operation completed with count of successful retries."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retries all failed messages currently in the queue.\r\nProcesses messages with exponential backoff and respects circuit breaker states.",
"tags": [
"InternalMessaging"
]
}
},
"/api/internal/messages/send": {
"post": {
"operationId": "InternalMessaging_SendMessage",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"maxRetries": 0,
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageRequest"
}
},
"application/json": {
"example": {
"maxRetries": 0,
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageRequest"
}
},
"text/json": {
"example": {
"maxRetries": 0,
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageRequest"
}
}
},
"description": "The outgoing message request with target instance and payload."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"errorMessage": "string",
"isFailed": false,
"isQueued": false,
"isSuccess": false,
"messageId": "string",
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageResponse"
}
}
},
"description": "Message delivered successfully."
},
"202": {
"content": {
"application/json": {
"example": {
"errorMessage": "string",
"isFailed": false,
"isQueued": false,
"isSuccess": false,
"messageId": "string",
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageResponse"
}
}
},
"description": "Message queued for delivery."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request parameters."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - caller is not a platform operator."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Sends a cross-instance message to another instance (admin/testing endpoint).\r\nEncrypts payload client-side before transmission through Istio service mesh with mTLS.",
"tags": [
"InternalMessaging"
]
}
},
"/api/internal/messages/statistics": {
"get": {
"operationId": "InternalMessaging_GetStatistics",
"parameters": [
{
"description": "Optional target instance ID to filter statistics.",
"in": "query",
"name": "targetInstanceId",
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"averageDeliveryLatency": "string",
"circuitBreakerOpen": false,
"instanceId": "string",
"p95DeliveryLatency": "string",
"p99DeliveryLatency": "string",
"retryRate": 0,
"successRate": 0,
"throughputMessagesPerSecond": 0,
"totalMessagesDelivered": 0,
"totalMessagesFailed": 0,
"totalMessagesQueued": 0,
"totalMessagesSent": 0,
"windowEnd": "2026-01-01T00:00:00.0000000+00:00",
"windowStart": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/MessagingStatistics"
}
}
},
"description": "Statistics retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Gets comprehensive messaging statistics for monitoring and diagnostics.\r\nStatistics are aggregated over a rolling 5-minute window.",
"tags": [
"InternalMessaging"
]
}
},
"/api/internal/messages/{messageId}/status": {
"get": {
"operationId": "InternalMessaging_GetMessageStatus",
"parameters": [
{
"description": "The unique identifier of the message to track.",
"in": "path",
"name": "messageId",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"lastUpdatedAt": "2026-01-01T00:00:00.0000000+00:00",
"maxRetries": 0,
"messageId": "string",
"queueDepth": 0,
"retryCount": 0,
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/MessageStatusResponse"
}
}
},
"description": "Message status retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid message ID."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Message not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Gets the delivery status of a previously sent cross-instance message.\r\nProvides real-time tracking of message delivery progress through the routing infrastructure.",
"tags": [
"InternalMessaging"
]
}
},
"/api/v1/Certificates/expiring": {
"get": {
"operationId": "Certificates_GetExpiringCertificates",
"parameters": [
{
"description": "Number of days until expiration (default: 30)",
"in": "query",
"name": "daysUntilExpiration",
"schema": {
"default": 30,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/CertificateDto"
},
"type": "array"
}
}
},
"description": "Expiring certificates retrieved successfully"
},
"500": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Internal server error"
}
},
"summary": "Retrieves certificates that are expiring within a specified number of days.",
"tags": [
"Certificates"
]
}
},
"/api/v1/Certificates/issue": {
"post": {
"operationId": "Certificates_IssueCertificate",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"signingCertificateThumbprint": "string",
"subjectName": "string",
"validityDays": 0
},
"schema": {
"$ref": "#/components/schemas/IssueCertificateRequest"
}
},
"application/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"signingCertificateThumbprint": "string",
"subjectName": "string",
"validityDays": 0
},
"schema": {
"$ref": "#/components/schemas/IssueCertificateRequest"
}
},
"text/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"signingCertificateThumbprint": "string",
"subjectName": "string",
"validityDays": 0
},
"schema": {
"$ref": "#/components/schemas/IssueCertificateRequest"
}
}
},
"description": "Certificate issuance request"
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"issuedAt": "2026-01-01T00:00:00.0000000+00:00",
"thumbprint": "string"
},
"schema": {
"$ref": "#/components/schemas/IssueCertificateResponse"
}
}
},
"description": "Certificate issued successfully"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data"
},
"500": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Internal server error"
}
},
"summary": "Issues a new certificate (intermediate or leaf).",
"tags": [
"Certificates"
]
}
},
"/api/v1/Certificates/{thumbprint}": {
"get": {
"operationId": "Certificates_GetCertificateByThumbprint",
"parameters": [
{
"description": "Certificate thumbprint",
"in": "path",
"name": "thumbprint",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isExpiringSoon": false,
"isHsmBacked": false,
"isValid": false,
"issuedAt": "2026-01-01T00:00:00.0000000+00:00",
"revokedAt": "2026-01-01T00:00:00.0000000+00:00",
"serialNumber": "string",
"subjectName": "string",
"thumbprint": "string"
},
"schema": {
"$ref": "#/components/schemas/CertificateDto"
}
}
},
"description": "Certificate found"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Certificate not found"
},
"500": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Internal server error"
}
},
"summary": "Retrieves a certificate by thumbprint.",
"tags": [
"Certificates"
]
}
},
"/api/v1/Certificates/{thumbprint}/revoke": {
"post": {
"operationId": "Certificates_RevokeCertificate",
"parameters": [
{
"description": "Certificate thumbprint",
"in": "path",
"name": "thumbprint",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"schema": {
"$ref": "#/components/schemas/RevokeCertificateRequest"
}
},
"application/json": {
"schema": {
"$ref": "#/components/schemas/RevokeCertificateRequest"
}
},
"text/json": {
"schema": {
"$ref": "#/components/schemas/RevokeCertificateRequest"
}
}
},
"description": "Revocation request"
},
"responses": {
"204": {
"description": "Certificate revoked successfully"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Certificate not found"
},
"500": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Internal server error"
}
},
"summary": "Revokes a certificate.",
"tags": [
"Certificates"
]
}
},
"/api/v1/admin/organizations": {
"post": {
"operationId": "AdminOrganizations_CreateOrganization",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"orgAdminUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"parentSovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"region": "string",
"slug": "string"
},
"schema": {
"$ref": "#/components/schemas/AdminCreateOrganizationRequest"
}
},
"application/json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"orgAdminUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"parentSovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"region": "string",
"slug": "string"
},
"schema": {
"$ref": "#/components/schemas/AdminCreateOrganizationRequest"
}
},
"text/json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"orgAdminUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"parentSovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"region": "string",
"slug": "string"
},
"schema": {
"$ref": "#/components/schemas/AdminCreateOrganizationRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Creates a non-dedicated (shared-instance) organisation registry entry\r\nand publishes the standard `OrganizationCreatedEvent` bootstrap\r\nfan-out (Vault default vault, Billing B2B trial, TenantConfiguration\r\ndefaults, Compliance profile, ModuleRegistry base modules). The\r\ncaller-supplied Essence.Core.Instance.Api.Controllers.AdminCreateOrganizationRequest.OrgAdminUserId\r\nbecomes the organisation's default-vault owner and B2B trial\r\nsubscriber — grant it the `org-admin` role afterwards via\r\n`POST /api/v1/admin/users/{idOrEmail}/roles` to complete the\r\n\"seed an org-admin member\" fixture (the RBAC role and the\r\nevent-driven bootstrap are separate concerns; this endpoint does not\r\nduplicate the role-grant surface that already exists).",
"tags": [
"AdminOrganizations"
]
}
},
"/api/v1/commercial/countries": {
"get": {
"operationId": "Commercial_ListCountries",
"responses": {
"200": {
"description": "OK"
}
},
"summary": "Lists all supported countries from the reference data table.\r\nUsed by the instance creation wizard for country selection.",
"tags": [
"Commercial"
]
}
},
"/api/v1/commercial/invoices": {
"get": {
"operationId": "Commercial_ListInvoices",
"parameters": [
{
"in": "query",
"name": "organizationId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"502": {
"description": "Bad Gateway"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Lists all invoices for the specified organization.",
"tags": [
"Commercial"
]
}
},
"/api/v1/commercial/licenses": {
"get": {
"operationId": "Commercial_ListLicenses",
"parameters": [
{
"in": "query",
"name": "organizationId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"502": {
"description": "Bad Gateway"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Lists all module licenses for the specified organization.",
"tags": [
"Commercial"
]
}
},
"/api/v1/commercial/partners": {
"get": {
"operationId": "Commercial_ListPartners",
"responses": {
"200": {
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"502": {
"description": "Bad Gateway"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Lists all active partners from the Partner Portal Service.\r\nAvailable to any authenticated user (needed during instance creation wizard).",
"tags": [
"Commercial"
]
}
},
"/api/v1/commercial/pricing-plans": {
"get": {
"operationId": "Commercial_ListPricingPlans",
"responses": {
"200": {
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"502": {
"description": "Bad Gateway"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Lists all active pricing plans from the Billing Service.\r\nAvailable to any authenticated user (needed during instance creation wizard).",
"tags": [
"Commercial"
]
}
},
"/api/v1/commercial/pricing-plans/{id}": {
"put": {
"operationId": "Commercial_UpdatePricingPlan",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"basePrice": 0,
"currency": "string",
"description": "string",
"features": {},
"metadata": {},
"name": "string",
"trialDays": 0
},
"schema": {
"$ref": "#/components/schemas/UpdatePricingPlanRequest"
}
},
"application/json": {
"example": {
"basePrice": 0,
"currency": "string",
"description": "string",
"features": {},
"metadata": {},
"name": "string",
"trialDays": 0
},
"schema": {
"$ref": "#/components/schemas/UpdatePricingPlanRequest"
}
},
"text/json": {
"example": {
"basePrice": 0,
"currency": "string",
"description": "string",
"features": {},
"metadata": {},
"name": "string",
"trialDays": 0
},
"schema": {
"$ref": "#/components/schemas/UpdatePricingPlanRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Updates a pricing plan (Admin only) — e.g. the Free plan's storage quota / base price.\r\nProxies to the Billing service PUT endpoint. Fields omitted from the body are left unchanged;\r\na supplied `features` map replaces the plan's features wholesale.",
"tags": [
"Commercial"
]
}
},
"/api/v1/commercial/subscriptions": {
"get": {
"operationId": "Commercial_ListSubscriptions",
"parameters": [
{
"in": "query",
"name": "organizationId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"502": {
"description": "Bad Gateway"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Lists all subscriptions for the specified organization.",
"tags": [
"Commercial"
]
}
},
"/api/v1/commercial/usage": {
"get": {
"operationId": "Commercial_GetUsage",
"parameters": [
{
"in": "query",
"name": "period",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "subscriptionId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"502": {
"description": "Bad Gateway"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Retrieves usage breakdown for a given billing period.",
"tags": [
"Commercial"
]
}
},
"/api/v1/compliance/assessments": {
"get": {
"operationId": "Compliance_ListAssessments",
"responses": {
"200": {
"description": "OK"
}
},
"tags": [
"Compliance"
]
}
},
"/api/v1/compliance/assessments/{id}": {
"get": {
"operationId": "Compliance_GetAssessmentById",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"tags": [
"Compliance"
]
}
},
"/api/v1/compliance/audit-log": {
"get": {
"description": "\n\r\n Every filter below used to be accepted and then dropped: the call downstream took only\r\n `page` and `pageSize`, so an investigator who narrowed by actor, action or date\r\n got the unfiltered first page back and no indication of it. On an evidential surface that\r\n turns \"no results\" into a statement about the log rather than about the query.\r\n \r\n\n\r\n The owning service does not expose a parameter for every filter this console offers.\r\n Those are named back in `unsupportedFilters` so the surface can say which part of\r\n the question went unasked, instead of presenting an unfiltered page as a filtered one.\r\n ",
"operationId": "Compliance_GetAuditLog",
"parameters": [
{
"in": "query",
"name": "startDate",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "endDate",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "actor",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "actionType",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "resourceType",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "service",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "organizationId",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "search",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "page",
"schema": {
"default": 1,
"format": "int32",
"type": "integer"
}
},
{
"in": "query",
"name": "pageSize",
"schema": {
"default": 20,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK"
}
},
"summary": "One filtered, paged slice of the platform audit log, from the Compliance service that\r\nowns it.",
"tags": [
"Compliance"
]
}
},
"/api/v1/compliance/evidence": {
"get": {
"description": "This endpoint returned 501 until the owning service had a read it could use.\r\nThe earlier note here said the Compliance service exposed no evidence endpoint,\r\nwhich was wrong - EvidenceController existed and served /api/v1/Evidence, and a\r\ngrep for the word \"evidence\" in its route attributes could not find it because\r\nthe routes are [controller]-derived. The conclusion held for a different reason:\r\nthe only read was GET /api/v1/Evidence/control/{controlId}, and this endpoint is\r\nasked for evidence by ASSESSMENT or for everything, so there was no control id to\r\nscope to. Worse, that per-control route had no MediatR handler at all, so it\r\nwould have thrown had anything called it.\r\n \r\nBoth are now fixed: the owning service has the handler and a paged\r\nGET /api/v1/Evidence that accepts an assessment or instance scope, resolving an\r\nassessment to its regulation's controls on its own side.\r\n \r\nAn unreachable owner is still reported as unavailable, never as an empty list.\r\n\"No evidence has been recorded\" is a claim an auditor could rely on, and this\r\nendpoint is only in a position to make it when the owning service actually said so.",
"operationId": "Compliance_GetEvidence",
"parameters": [
{
"in": "query",
"name": "assessmentId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "query",
"name": "page",
"schema": {
"default": 1,
"format": "int32",
"type": "integer"
}
},
{
"in": "query",
"name": "pageSize",
"schema": {
"default": 50,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Collected compliance evidence, optionally scoped to a single assessment.",
"tags": [
"Compliance"
]
}
},
"/api/v1/compliance/overview": {
"get": {
"operationId": "Compliance_GetOverview",
"responses": {
"200": {
"description": "OK"
}
},
"summary": "Returns a placeholder compliance overview. Real scores will be projected\r\nfrom the EPIC 12 assessment repository once it lands.",
"tags": [
"Compliance"
]
}
},
"/api/v1/credential-lockdown/compromised": {
"post": {
"operationId": "CredentialLockdown_FlagCompromised",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"consentRecordRef": "string",
"credentialId": "string",
"flaggedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"issuer": "string",
"relyingPartyRef": "string",
"statusListIndex": 0,
"statusListUrl": "string",
"vaultRef": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/FlagPresentedCredentialCompromisedCommand"
}
},
"application/json": {
"example": {
"consentRecordRef": "string",
"credentialId": "string",
"flaggedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"issuer": "string",
"relyingPartyRef": "string",
"statusListIndex": 0,
"statusListUrl": "string",
"vaultRef": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/FlagPresentedCredentialCompromisedCommand"
}
},
"text/json": {
"example": {
"consentRecordRef": "string",
"credentialId": "string",
"flaggedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"issuer": "string",
"relyingPartyRef": "string",
"statusListIndex": 0,
"statusListUrl": "string",
"vaultRef": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/FlagPresentedCredentialCompromisedCommand"
}
}
},
"description": "The lockdown command."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/CredentialLockdownResponse"
}
}
},
"description": "Credential locked down; events emitted."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request (validation or domain rule violation)."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — user not authenticated."
}
},
"summary": "Flags a presented physical credential compromised (report stolen), locking it\r\ndown and notifying the relying parties it was presented to.",
"tags": [
"CredentialLockdown"
]
}
},
"/api/v1/cross-border/driving-entitlement": {
"get": {
"operationId": "CrossBorder_GetDrivingEntitlement",
"parameters": [
{
"description": "Optional holder id supplied by the SPA; when present it MUST match the caller's own subject\r\n(a mismatch is refused as `403`). The authoritative owner is always the JWT subject.",
"in": "query",
"name": "userId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "The holder's held entitlement, or `null` when none is on file."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The requested holder is not the caller."
}
},
"summary": "Reads the caller's held driving entitlement for cross-border presentation. Returns\r\n`{ data: null }` when the holder has no licence on file (a normal state, not an error).",
"tags": [
"CrossBorder"
]
},
"post": {
"operationId": "CrossBorder_RegisterDrivingEntitlement",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"categories": [],
"holderRef": "string",
"issuingJurisdiction": "string",
"licenceExpiry": "2026-01-01",
"restrictionCodes": []
},
"schema": {
"$ref": "#/components/schemas/RegisterDrivingEntitlementRequest"
}
},
"application/json": {
"example": {
"categories": [],
"holderRef": "string",
"issuingJurisdiction": "string",
"licenceExpiry": "2026-01-01",
"restrictionCodes": []
},
"schema": {
"$ref": "#/components/schemas/RegisterDrivingEntitlementRequest"
}
},
"text/json": {
"example": {
"categories": [],
"holderRef": "string",
"issuingJurisdiction": "string",
"licenceExpiry": "2026-01-01",
"restrictionCodes": []
},
"schema": {
"$ref": "#/components/schemas/RegisterDrivingEntitlementRequest"
}
}
},
"description": "The ZK held-entitlement metadata to register."
},
"responses": {
"200": {
"description": "The registered (or replaced) held entitlement."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request (validation or domain rule violation)."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
}
},
"summary": "Registers or replaces the caller's held driving entitlement from their wallet. The owner is\r\nalways the caller's subject — any `userId` in the body is ignored.",
"tags": [
"CrossBorder"
]
}
},
"/api/v1/cross-border/immigration-status": {
"get": {
"operationId": "ImmigrationStatus_GetStatus",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"brpMask": "string",
"brpRetiredAt": "2026-01-01T00:00:00.0000000+00:00",
"brpValidUntil": "2026-01-01",
"canPerformCutover": false,
"canonicalAt": "2026-01-01T00:00:00.0000000+00:00",
"eVisaCredentialId": "string",
"eVisaValidFrom": "2026-01-01",
"eVisaValidUntil": "2026-01-01",
"shareCodes": [],
"stage": "string",
"statusVersion": 0,
"supersessionReceiptRef": "string",
"transitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"verifications": []
},
"schema": {
"$ref": "#/components/schemas/ImmigrationStatusDto"
}
}
},
"description": "The caller's transition."
},
"204": {
"description": "The caller has never linked an immigration status."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
}
},
"summary": "Reads the caller's own transition, with their issued share codes and the checks made against\r\nthem. Returns `204 No Content` when nothing is linked yet — a normal starting state, not\r\nan error, and the signal the surface uses to show the entry screen.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/console": {
"get": {
"operationId": "ImmigrationStatus_GetConsole",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"requests": [],
"verifications": []
},
"schema": {
"$ref": "#/components/schemas/ImmigrationVerificationConsoleDto"
}
}
},
"description": "The console state."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not acting for an organisation."
}
},
"summary": "The verifying organisation's console read: its acceptance policy, every check it has made\r\n(each flagged when the subject's status has since moved on), and its outstanding requests.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/cutover": {
"post": {
"operationId": "ImmigrationStatus_Cutover",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"actor": "string"
},
"schema": {
"$ref": "#/components/schemas/PerformCutoverRequest"
}
},
"application/json": {
"example": {
"actor": "string"
},
"schema": {
"$ref": "#/components/schemas/PerformCutoverRequest"
}
},
"text/json": {
"example": {
"actor": "string"
},
"schema": {
"$ref": "#/components/schemas/PerformCutoverRequest"
}
}
},
"description": "Who is performing the cutover."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"brpMask": "string",
"brpRetiredAt": "2026-01-01T00:00:00.0000000+00:00",
"brpValidUntil": "2026-01-01",
"canPerformCutover": false,
"canonicalAt": "2026-01-01T00:00:00.0000000+00:00",
"eVisaCredentialId": "string",
"eVisaValidFrom": "2026-01-01",
"eVisaValidUntil": "2026-01-01",
"shareCodes": [],
"stage": "string",
"statusVersion": 0,
"supersessionReceiptRef": "string",
"transitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"verifications": []
},
"schema": {
"$ref": "#/components/schemas/ImmigrationStatusDto"
}
}
},
"description": "The canonical transition, with its supersession receipt reference."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller has never linked an immigration status."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No eVisa is established yet, or the cutover already happened."
}
},
"summary": "Step 3 — the canonical cutover. Retires the BRP, makes the eVisa canonical, supersedes every\r\npreviously issued code, and writes the audited supersession event through the outbox.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/evisa": {
"post": {
"operationId": "ImmigrationStatus_EstablishEVisa",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"credentialId": "string",
"validFrom": "2026-01-01",
"validUntil": "2026-01-01"
},
"schema": {
"$ref": "#/components/schemas/EstablishEVisaRequest"
}
},
"application/json": {
"example": {
"credentialId": "string",
"validFrom": "2026-01-01",
"validUntil": "2026-01-01"
},
"schema": {
"$ref": "#/components/schemas/EstablishEVisaRequest"
}
},
"text/json": {
"example": {
"credentialId": "string",
"validFrom": "2026-01-01",
"validUntil": "2026-01-01"
},
"schema": {
"$ref": "#/components/schemas/EstablishEVisaRequest"
}
}
},
"description": "The credential reference and its validity window."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"brpMask": "string",
"brpRetiredAt": "2026-01-01T00:00:00.0000000+00:00",
"brpValidUntil": "2026-01-01",
"canPerformCutover": false,
"canonicalAt": "2026-01-01T00:00:00.0000000+00:00",
"eVisaCredentialId": "string",
"eVisaValidFrom": "2026-01-01",
"eVisaValidUntil": "2026-01-01",
"shareCodes": [],
"stage": "string",
"statusVersion": 0,
"supersessionReceiptRef": "string",
"transitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"verifications": []
},
"schema": {
"$ref": "#/components/schemas/ImmigrationStatusDto"
}
}
},
"description": "The updated transition, now at the interim stage."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller has never linked an immigration status."
}
},
"summary": "Step 2 seam — records an established eVisa verifiable credential against the caller's linked\r\nstatus. Issuing the credential is EPIC 24 base capability and happens elsewhere.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/link": {
"post": {
"operationId": "ImmigrationStatus_Link",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"brpMask": "string",
"brpValidUntil": "2026-01-01"
},
"schema": {
"$ref": "#/components/schemas/LinkImmigrationStatusRequest"
}
},
"application/json": {
"example": {
"brpMask": "string",
"brpValidUntil": "2026-01-01"
},
"schema": {
"$ref": "#/components/schemas/LinkImmigrationStatusRequest"
}
},
"text/json": {
"example": {
"brpMask": "string",
"brpValidUntil": "2026-01-01"
},
"schema": {
"$ref": "#/components/schemas/LinkImmigrationStatusRequest"
}
}
},
"description": "The BRP mask and the expiry printed on the card."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"brpMask": "string",
"brpRetiredAt": "2026-01-01T00:00:00.0000000+00:00",
"brpValidUntil": "2026-01-01",
"canPerformCutover": false,
"canonicalAt": "2026-01-01T00:00:00.0000000+00:00",
"eVisaCredentialId": "string",
"eVisaValidFrom": "2026-01-01",
"eVisaValidUntil": "2026-01-01",
"shareCodes": [],
"stage": "string",
"statusVersion": 0,
"supersessionReceiptRef": "string",
"transitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"verifications": []
},
"schema": {
"$ref": "#/components/schemas/ImmigrationStatusDto"
}
}
},
"description": "The linked (or already-linked) transition."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request — an unusable mask, or an expired card."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
}
},
"summary": "Step 1 — links an existing BRP-based immigration status. Idempotent: a caller who already has\r\na linked status gets it back rather than a second one.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/org-policy": {
"put": {
"operationId": "ImmigrationStatus_UpdatePolicy",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"acceptedClaimTypes": [],
"acceptedJurisdictions": [],
"maxStalenessDays": 0,
"requireCanonicalEVisa": false
},
"schema": {
"$ref": "#/components/schemas/UpdateVerificationPolicyRequest"
}
},
"application/json": {
"example": {
"acceptedClaimTypes": [],
"acceptedJurisdictions": [],
"maxStalenessDays": 0,
"requireCanonicalEVisa": false
},
"schema": {
"$ref": "#/components/schemas/UpdateVerificationPolicyRequest"
}
},
"text/json": {
"example": {
"acceptedClaimTypes": [],
"acceptedJurisdictions": [],
"maxStalenessDays": 0,
"requireCanonicalEVisa": false
},
"schema": {
"$ref": "#/components/schemas/UpdateVerificationPolicyRequest"
}
}
},
"description": "The policy to apply."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"acceptedClaimTypes": [],
"acceptedJurisdictions": [],
"maxStalenessDays": 0,
"organizationRef": "string",
"requireCanonicalEVisa": false
},
"schema": {
"$ref": "#/components/schemas/ImmigrationVerificationPolicyDto"
}
}
},
"description": "The applied policy."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid policy."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not acting for an organisation."
}
},
"summary": "Replaces the caller organisation's acceptance policy.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/share-codes": {
"post": {
"operationId": "ImmigrationStatus_IssueShareCode",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"claimType": "string",
"recipientLabel": "string",
"validityDays": 0
},
"schema": {
"$ref": "#/components/schemas/IssueShareCodeRequest"
}
},
"application/json": {
"example": {
"claimType": "string",
"recipientLabel": "string",
"validityDays": 0
},
"schema": {
"$ref": "#/components/schemas/IssueShareCodeRequest"
}
},
"text/json": {
"example": {
"claimType": "string",
"recipientLabel": "string",
"validityDays": 0
},
"schema": {
"$ref": "#/components/schemas/IssueShareCodeRequest"
}
}
},
"description": "The claim to prove, who it is for, and how long it should last."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"claimType": "string",
"code": "string",
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"shareCodeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/IssuedShareCodeDto"
}
}
},
"description": "The issued code, returned once."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller has never linked an immigration status."
}
},
"summary": "Step 4 — issues a typed share code proving one entitlement claim. The plaintext code is in\r\nthis response and nowhere else, ever.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/share-codes/{shareCodeId}/revoke": {
"post": {
"operationId": "ImmigrationStatus_RevokeShareCode",
"parameters": [
{
"description": "The code to revoke.",
"in": "path",
"name": "shareCodeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"brpMask": "string",
"brpRetiredAt": "2026-01-01T00:00:00.0000000+00:00",
"brpValidUntil": "2026-01-01",
"canPerformCutover": false,
"canonicalAt": "2026-01-01T00:00:00.0000000+00:00",
"eVisaCredentialId": "string",
"eVisaValidFrom": "2026-01-01",
"eVisaValidUntil": "2026-01-01",
"shareCodes": [],
"stage": "string",
"statusVersion": 0,
"supersessionReceiptRef": "string",
"transitionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"verifications": []
},
"schema": {
"$ref": "#/components/schemas/ImmigrationStatusDto"
}
}
},
"description": "The updated transition, with the code now shown as revoked."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The code does not belong to the caller's status."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller has never linked an immigration status."
}
},
"summary": "Revokes one of the caller's own share codes. Idempotent.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/verification-requests": {
"post": {
"operationId": "ImmigrationStatus_RaiseRequests",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"claimType": "string",
"dueOn": "2026-01-01",
"subjectRefs": []
},
"schema": {
"$ref": "#/components/schemas/RaiseVerificationRequestsRequest"
}
},
"application/json": {
"example": {
"claimType": "string",
"dueOn": "2026-01-01",
"subjectRefs": []
},
"schema": {
"$ref": "#/components/schemas/RaiseVerificationRequestsRequest"
}
},
"text/json": {
"example": {
"claimType": "string",
"dueOn": "2026-01-01",
"subjectRefs": []
},
"schema": {
"$ref": "#/components/schemas/RaiseVerificationRequestsRequest"
}
}
},
"description": "The people to ask, the claim, and the response date."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/ImmigrationVerificationRequestDto"
},
"type": "array"
}
}
},
"description": "The raised requests."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not acting for an organisation."
}
},
"summary": "Raises bulk/invite verification requests — asks several individuals for a share code and\r\nstarts tracking who has responded.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/verification-requests/{requestId}/withdraw": {
"post": {
"operationId": "ImmigrationStatus_WithdrawRequest",
"parameters": [
{
"description": "The request to withdraw.",
"in": "path",
"name": "requestId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"claimType": "string",
"dueOn": "2026-01-01",
"fulfilledAt": "2026-01-01T00:00:00.0000000+00:00",
"fulfilledByVerificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestedAt": "2026-01-01T00:00:00.0000000+00:00",
"status": "string",
"subjectRef": "string"
},
"schema": {
"$ref": "#/components/schemas/ImmigrationVerificationRequestDto"
}
}
},
"description": "The withdrawn request."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request does not belong to the caller's organisation."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not acting for an organisation."
}
},
"summary": "Withdraws one of the caller organisation's outstanding requests.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/immigration-status/verify": {
"post": {
"operationId": "ImmigrationStatus_Verify",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"code": "string"
},
"schema": {
"$ref": "#/components/schemas/VerifyShareCodeRequest"
}
},
"application/json": {
"example": {
"code": "string"
},
"schema": {
"$ref": "#/components/schemas/VerifyShareCodeRequest"
}
},
"text/json": {
"example": {
"code": "string"
},
"schema": {
"$ref": "#/components/schemas/VerifyShareCodeRequest"
}
}
},
"description": "The code as typed."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"basis": "string",
"checkedAt": "2026-01-01T00:00:00.0000000+00:00",
"claimType": "string",
"credentialId": "string",
"entitlementValidUntil": "2026-01-01",
"maxStalenessDays": 0,
"outcome": "string",
"requiresRecheck": false,
"shareCodeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"statusVersion": 0,
"subjectStage": "string",
"verificationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"verifierOrgRef": "string"
},
"schema": {
"$ref": "#/components/schemas/ImmigrationVerificationDto"
}
}
},
"description": "The stamped verification result."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The code is not the right shape."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller is not acting for an organisation."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No share code matches."
}
},
"summary": "The verifier's redemption — enter a share code, get a stamped result. Every redemption\r\nresolves against the live status, so a code minted before the migrant's cutover comes back\r\n`superseded` rather than clean.",
"tags": [
"ImmigrationStatus"
]
}
},
"/api/v1/cross-border/renunciation/cases": {
"post": {
"operationId": "RenunciationTeardown_OpenCase",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"credentialRefs": [],
"jurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/OpenRenunciationTeardownRequest"
}
},
"application/json": {
"example": {
"credentialRefs": [],
"jurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/OpenRenunciationTeardownRequest"
}
},
"text/json": {
"example": {
"credentialRefs": [],
"jurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/OpenRenunciationTeardownRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"caseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"jurisdiction": "string",
"openedAt": "2026-01-01T00:00:00.0000000+00:00",
"readyForReceipt": false,
"receiptDigest": "string",
"status": "string",
"steps": [],
"templateId": "string",
"validityCeilingDays": 0
},
"schema": {
"$ref": "#/components/schemas/RenunciationTeardownCaseDto"
}
}
},
"description": "The teardown timeline."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No jurisdiction supplied."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Opens (or rejoins) the caller's renunciation teardown — the irreversible confirm behind the\r\nfront door's review screen.",
"tags": [
"RenunciationTeardown"
]
}
},
"/api/v1/cross-border/renunciation/cases/current": {
"get": {
"operationId": "RenunciationTeardown_GetCurrent",
"parameters": [
{
"in": "query",
"name": "jurisdiction",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"caseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"jurisdiction": "string",
"openedAt": "2026-01-01T00:00:00.0000000+00:00",
"readyForReceipt": false,
"receiptDigest": "string",
"status": "string",
"steps": [],
"templateId": "string",
"validityCeilingDays": 0
},
"schema": {
"$ref": "#/components/schemas/RenunciationTeardownCaseDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Reads the caller's live teardown for a jurisdiction. Returns `{ data: null }` when none\r\nis in flight — a normal state, not an error.",
"tags": [
"RenunciationTeardown"
]
}
},
"/api/v1/cross-border/renunciation/cases/{caseId}": {
"get": {
"operationId": "RenunciationTeardown_GetCase",
"parameters": [
{
"in": "path",
"name": "caseId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"caseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"jurisdiction": "string",
"openedAt": "2026-01-01T00:00:00.0000000+00:00",
"readyForReceipt": false,
"receiptDigest": "string",
"status": "string",
"steps": [],
"templateId": "string",
"validityCeilingDays": 0
},
"schema": {
"$ref": "#/components/schemas/RenunciationTeardownCaseDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such case for this caller (also returned for another subject's case)."
}
},
"summary": "Reads one of the caller's teardown cases.",
"tags": [
"RenunciationTeardown"
]
}
},
"/api/v1/cross-border/renunciation/cases/{caseId}/abandon": {
"post": {
"operationId": "RenunciationTeardown_Abandon",
"parameters": [
{
"in": "path",
"name": "caseId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"caseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"jurisdiction": "string",
"openedAt": "2026-01-01T00:00:00.0000000+00:00",
"readyForReceipt": false,
"receiptDigest": "string",
"status": "string",
"steps": [],
"templateId": "string",
"validityCeilingDays": 0
},
"schema": {
"$ref": "#/components/schemas/RenunciationTeardownCaseDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Abandons a teardown. Returns the timeline unchanged when something irreversible has already\r\nhappened — there is nothing to abandon back to once a credential has been surrendered.",
"tags": [
"RenunciationTeardown"
]
}
},
"/api/v1/cross-border/renunciation/cases/{caseId}/complete": {
"post": {
"operationId": "RenunciationTeardown_Complete",
"parameters": [
{
"in": "path",
"name": "caseId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"caseId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"jurisdiction": "string",
"openedAt": "2026-01-01T00:00:00.0000000+00:00",
"readyForReceipt": false,
"receiptDigest": "string",
"status": "string",
"steps": [],
"templateId": "string",
"validityCeilingDays": 0
},
"schema": {
"$ref": "#/components/schemas/RenunciationTeardownCaseDto"
}
}
},
"description": "OK"
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Issues the teardown receipt. Returns the timeline unchanged (status still\r\n`InProgress`/`Blocked`, `receiptDigest` null) when a step is outstanding, so\r\nthe caller can see exactly what is holding it up.",
"tags": [
"RenunciationTeardown"
]
}
},
"/api/v1/cross-border/renunciation/template": {
"get": {
"operationId": "RenunciationTeardown_GetTemplate",
"parameters": [
{
"in": "query",
"name": "jurisdiction",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"jurisdiction": "string",
"notifyList": [],
"steps": [],
"templateId": "string",
"validityCeilingDays": 0
},
"schema": {
"$ref": "#/components/schemas/RenunciationTeardownTemplateDto"
}
}
},
"description": "The template."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No jurisdiction supplied, or its configured template is invalid."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
}
},
"summary": "Reads a jurisdiction's teardown template.",
"tags": [
"RenunciationTeardown"
]
}
},
"/api/v1/cross-border/returning-national/intake": {
"post": {
"operationId": "CrossBorder_OpenReturningNationalIntake",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"credentials": [],
"destinationJurisdiction": "string",
"originJurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/OpenReturningNationalIntakeRequest"
}
},
"application/json": {
"example": {
"credentials": [],
"destinationJurisdiction": "string",
"originJurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/OpenReturningNationalIntakeRequest"
}
},
"text/json": {
"example": {
"credentials": [],
"destinationJurisdiction": "string",
"originJurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/OpenReturningNationalIntakeRequest"
}
}
},
"description": "The corridor and the ZK foreign-credential references."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"credentials": [],
"destinationJurisdiction": "string",
"intakeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"originJurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/ReturningNationalIntakeDto"
}
}
},
"description": "The intake was opened."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request, or no submitted credential can be credited."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The corridor has no lawful basis — nothing was recorded."
}
},
"summary": "Opens the caller's inbound returning-national intake — Step 1 of the\r\n`returning-expat-domestic-identity-reestablishment` journey. Captures the foreign\r\ncredential references, resolves the corridor's residency / adequacy / lawful-basis decision,\r\nand previews the foreign-to-domestic assurance credit under the origin jurisdiction's\r\nacceptance policy. The returned `intakeId` is the handle Steps 2 (EPIC 9 bootstrap) and 3\r\n(EPIC 2 vault reconciliation) key on, so the credentials are never re-entered.\r\n \r\n\n\r\nThe response is the DTO bare — no `{ data: … }` envelope. The returning-national\r\nclient unwraps `response.data` (the HTTP body) directly, unlike the cross-border engine\r\nclient above which unwraps `data.data`.\r\n\n\r\nA corridor with no lawful basis is refused (409) and nothing is persisted — a blocked\r\nadequacy posture cannot be walked past into the downstream steps.\r\n",
"tags": [
"CrossBorder"
]
}
},
"/api/v1/developer-ids": {
"get": {
"operationId": "DeveloperIds_ListDeveloperIds",
"parameters": [
{
"description": "Optional status filter (active, suspended, revoked).",
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Developer IDs retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown status filter."
}
},
"summary": "Lists all developer IDs, optionally filtered by status.",
"tags": [
"DeveloperIds"
]
},
"post": {
"operationId": "DeveloperIds_CreateDeveloperId",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"displayName": "string",
"notes": "string",
"ownerEmail": "string",
"slug": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateDeveloperIdRequest"
}
},
"application/json": {
"example": {
"displayName": "string",
"notes": "string",
"ownerEmail": "string",
"slug": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateDeveloperIdRequest"
}
},
"text/json": {
"example": {
"displayName": "string",
"notes": "string",
"ownerEmail": "string",
"slug": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateDeveloperIdRequest"
}
}
},
"description": "The creation request."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"displayName": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"notes": "string",
"ownerEmail": "string",
"slug": "string",
"status": "string",
"suspendedReason": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/DeveloperIdEntry"
}
}
},
"description": "Developer ID created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data, or the slug is already taken."
}
},
"summary": "Creates a new developer ID.",
"tags": [
"DeveloperIds"
]
}
},
"/api/v1/developer-ids/{id}": {
"get": {
"operationId": "DeveloperIds_GetDeveloperIdById",
"parameters": [
{
"description": "The developer ID identifier.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"displayName": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"notes": "string",
"ownerEmail": "string",
"slug": "string",
"status": "string",
"suspendedReason": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/DeveloperIdEntry"
}
}
},
"description": "Developer ID retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Developer ID not found."
}
},
"summary": "Retrieves a single developer ID by its unique identifier.",
"tags": [
"DeveloperIds"
]
}
},
"/api/v1/developer-ids/{id}/revoke": {
"post": {
"operationId": "DeveloperIds_RevokeDeveloperId",
"parameters": [
{
"description": "The developer ID identifier.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Developer ID revoked successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid operation (already revoked)."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Developer ID not found."
}
},
"summary": "Revokes a developer ID permanently.",
"tags": [
"DeveloperIds"
]
}
},
"/api/v1/developer-ids/{id}/suspend": {
"post": {
"operationId": "DeveloperIds_SuspendDeveloperId",
"parameters": [
{
"description": "The developer ID identifier.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/SuspendDeveloperIdRequest"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/SuspendDeveloperIdRequest"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/SuspendDeveloperIdRequest"
}
}
},
"description": "The suspension request containing a reason."
},
"responses": {
"200": {
"description": "Developer ID suspended successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid operation (already suspended or revoked)."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Developer ID not found."
}
},
"summary": "Suspends a developer ID.",
"tags": [
"DeveloperIds"
]
}
},
"/api/v1/discovery/.well-known/instance": {
"get": {
"description": "This endpoint is intentionally Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute\r\nbecause well-known discovery documents are part of RFC 8615 and\r\nmust be reachable before authentication credentials are established.\r\nThe document contains only public, non-PII metadata: instance ID,\r\ninstance type, supported API versions, and the federation trust\r\nroots an external party would need to validate signed envelopes.",
"operationId": "Discovery_GetWellKnownInstance",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"apiVersions": [],
"discoveryEndpoint": "string",
"generatedAt": "2026-01-01T00:00:00.0000000+00:00",
"healthEndpoint": "string",
"instanceId": "string",
"metricsEndpoint": "string",
"readyEndpoint": "string",
"serviceName": "string"
},
"schema": {
"$ref": "#/components/schemas/InstanceDiscoveryDocument"
}
}
},
"description": "Discovery metadata document."
}
},
"summary": "RFC 8615 well-known metadata document for this instance. Returns\r\nthe API surface, supported versions, instance type, and federation\r\ntrust roots so external clients (and federated peers) can perform\r\ninstance discovery without authentication.",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/health": {
"get": {
"description": "Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute — routing happens before authentication, like\r\n `GET /discovery/instances`, and this endpoint uses exactly that list's predicate\r\n (`OnlyHealthy` ⇒ `InstanceStatus.Active`). It returns two counts and a word, both\r\n counts derivable from that public list, so it is not an inventory or liveness oracle: no\r\n instance id, name, status or probe result is exposed. Per-instance health is\r\n `GET /discovery/health/{instanceId}`, which stays caller-scoped.",
"operationId": "Discovery_GetRoutingHealth",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"checkedAt": "2026-01-01T00:00:00.0000000+00:00",
"routableInstanceCount": 0,
"routableRegionCount": 0,
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/RoutingHealthDto"
}
}
},
"description": "At least one sovereign is routable."
},
"503": {
"content": {
"application/json": {
"example": {
"checkedAt": "2026-01-01T00:00:00.0000000+00:00",
"routableInstanceCount": 0,
"routableRegionCount": 0,
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/RoutingHealthDto"
}
}
},
"description": "No sovereign is routable."
}
},
"summary": "Routing health (EPIC 3 api-contracts §Discovery, `AllowAnonymous`): can discovery route\r\na newcomer to a sovereign right now? `200` when at least one sovereign is\r\n`Active`, `503` when none is, with the same body either way (#10344).",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/health/{instanceId}": {
"get": {
"operationId": "Discovery_CheckHealth",
"parameters": [
{
"description": "The unique identifier of the instance to check.",
"in": "path",
"name": "instanceId",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"checkedAt": "2026-01-01T00:00:00.0000000+00:00",
"httpStatusCode": 0,
"isHealthy": false,
"reason": "string",
"responseTime": "string"
},
"schema": {
"$ref": "#/components/schemas/HealthStatus"
}
}
},
"description": "Health check completed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid instance ID."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Performs a comprehensive health check on a specific instance.\r\nValidates database connectivity, cache availability, and dependent services.\r\nResults are cached for 30 seconds to reduce health check overhead.",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/home-realm": {
"post": {
"description": "\n\r\n Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute — discovery runs BEFORE authentication, so the answer\r\n must not be a statement about a person. It is keyed on the DOMAIN only, never the local-part\r\n (#8633). Keyed on the whole address it was an account-existence oracle in the one attribute\r\n that matters most on this platform: an anonymous caller could hash a candidate address, post\r\n it, and be told which sovereign holds that named individual's vault — residency class for a\r\n named person, to an unauthenticated stranger. Hashing did not help, because the attacker\r\n chooses the input.\r\n \r\n\n\r\n An unknown domain, a domain whose users span regions, and a request with no domain are one\r\n answer: the default-region realm, indistinguishable from a real default-region domain\r\n (NFR-09.020). No per-account branch is taken, in body or in timing, because no per-account\r\n state is consulted. Where the realm is therefore not disclosed the sign-in surface presents\r\n every configured IdP rather than a region-filtered subset (FR-09.036), so the user is not\r\n stranded at a door they cannot open.\r\n ",
"operationId": "Discovery_DiscoverHomeRealm",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"domain": "string"
},
"schema": {
"$ref": "#/components/schemas/HomeRealmDiscoveryRequest"
}
},
"application/json": {
"example": {
"domain": "string"
},
"schema": {
"$ref": "#/components/schemas/HomeRealmDiscoveryRequest"
}
},
"text/json": {
"example": {
"domain": "string"
},
"schema": {
"$ref": "#/components/schemas/HomeRealmDiscoveryRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"authorizeUrl": "string",
"isDefaultRealm": false,
"realmToken": "string",
"region": "string"
},
"schema": {
"$ref": "#/components/schemas/HomeRealmDiscoveryResponse"
}
}
},
"description": "The resolved home realm + opaque redirect descriptor."
}
},
"summary": "Home-realm discovery broker (EPIC 9 FR-09.032 / EPIC 3 FR-03.058). Resolves a sign-in\r\naddress's domain to the authoritative home realm from the Global Registry and returns\r\nwhere the broker should redirect to complete authentication (the completing sovereign's OIDC\r\nauthorize endpoint) plus an opaque short-TTL realm descriptor.",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/instances": {
"get": {
"description": "Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute — instance choice happens BEFORE\r\n authentication. The response is public routing metadata ONLY (opaque id,\r\n jurisdiction code, display name); it never exposes health, status, compliance,\r\n data-residency, validator, or CDN detail — those stay on the admin-gated\r\n instance-management endpoints. Availability = `InstanceStatus.Active`,\r\n reusing the exact predicate the admin sovereign list applies for\r\n `onlyHealthy` (so an instance that is not serving is never advertised).\r\n Global was previously included on the grounds that \"the SPA is served FROM the\r\n Global instance, so if this endpoint is reachable, Global is by definition\r\n available\". That is true about AVAILABILITY and irrelevant to the question asked:\r\n reachability of the front door is not a licence to place a vault behind it.",
"operationId": "Discovery_GetAvailableInstances",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"instances": [],
"regions": []
},
"schema": {
"$ref": "#/components/schemas/PublicInstanceListResponse"
}
}
},
"description": "The available instances (Global + Active sovereigns)."
}
},
"summary": "Available SOVEREIGN instances for the pre-auth Register / sign-in surface: every\r\nsovereign currently in `Active` status. Lets the frontend instance selector\r\nscope itself to the sovereigns that are actually served instead of shipping a\r\nhardcoded list.\r\n \r\nGlobal is deliberately NOT returned. No vault data is ever global, so GLOBAL\r\nis not a jurisdiction a vault can live in and must not be offered as one. This\r\nendpoint answers \"where may my vault live?\", and Global is the router, not an\r\nanswer to that question.",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/latency": {
"get": {
"operationId": "Discovery_MeasureLatency",
"parameters": [
{
"description": "The HTTP/HTTPS endpoint URL to measure latency.",
"in": "query",
"name": "endpoint",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"endpoint": "string",
"isReachable": false,
"latency": "string",
"measuredAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/LatencyMeasurementResult"
}
}
},
"description": "Latency measured successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid endpoint URL."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Measures the round-trip network latency to a specific instance endpoint.\r\nUsed for routing decisions and performance monitoring.\r\nProbes the instance's liveness path with a 5-second timeout, where the liveness probe\r\nresolver says that instance is probed (#16678).",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/optimal": {
"post": {
"description": "The authoritative contract (api-contracts.md §1 Discovery) specifies\r\n`POST /api/v1/discovery/optimal` (\"GeoIP optimal instance\"); the implementation had\r\nonly ever exposed this capability as `GET /api/v1/discovery/sovereign`\r\n(debt-2026-08-13-039). Both bindings resolve through the same\r\n`ISovereignFallbackRouter`, so they cannot diverge: the POST carries the GeoIP inputs\r\nin a body (the shape the contract was written against and the natural carrier for a\r\nlookup result), the GET keeps them on the query string for existing callers.",
"operationId": "Discovery_ResolveOptimalInstance",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"confidence": 0,
"countryCode": "string"
},
"schema": {
"$ref": "#/components/schemas/OptimalInstanceRequest"
}
},
"application/json": {
"example": {
"confidence": 0,
"countryCode": "string"
},
"schema": {
"$ref": "#/components/schemas/OptimalInstanceRequest"
}
},
"text/json": {
"example": {
"confidence": 0,
"countryCode": "string"
},
"schema": {
"$ref": "#/components/schemas/OptimalInstanceRequest"
}
}
},
"description": "The upstream GeoIP lookup outcome. A null body, or one with no\r\n `countryCode`, models a GeoIP-unresolvable lookup."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"outcome": "string",
"reason": "string",
"reasonCode": "string",
"sovereignId": "string"
},
"schema": {
"$ref": "#/components/schemas/SovereignRouteResult"
}
}
},
"description": "An adequate instance was resolved (directly or via the default)."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid country code or confidence."
},
"422": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No adequate sovereign for the request (FR-03.024b `no_adequate_sovereign`)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Resolves the optimal instance for a client from its GeoIP position — the contract binding\r\nof the FR-03.024b resolution also served by M:Essence.Core.Instance.Api.Controllers.DiscoveryController.ResolveSovereign(System.String,System.Nullable{System.Int32},System.Threading.CancellationToken).",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/org-realm": {
"post": {
"description": "Microsoft.AspNetCore.Authorization.AllowAnonymousAttribute — runs before authentication. A host that does not bind\r\n to a known org returns `404` uniformly (an unbound / unentitled custom domain and a\r\n disabled org are indistinguishable — FR-03.060), so it is not an entitlement/config oracle.",
"operationId": "Discovery_DiscoverOrgRealm",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"host": "string"
},
"schema": {
"$ref": "#/components/schemas/OrgRealmDiscoveryRequest"
}
},
"application/json": {
"example": {
"host": "string"
},
"schema": {
"$ref": "#/components/schemas/OrgRealmDiscoveryRequest"
}
},
"text/json": {
"example": {
"host": "string"
},
"schema": {
"$ref": "#/components/schemas/OrgRealmDiscoveryRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"authorizeUrl": "string",
"isDefaultRealm": false,
"realmToken": "string",
"region": "string"
},
"schema": {
"$ref": "#/components/schemas/HomeRealmDiscoveryResponse"
}
}
},
"description": "The resolved org realm + signed redirect descriptor."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The host does not resolve to a known org (uniform)."
}
},
"summary": "Org home-realm discovery (EPIC 3 FR-03.059/060). Resolves an org-branded host — the default\r\n`{orgid}.{region}.onessence.digital` scheme or a license-gated custom domain — to its\r\nOrganisation Instance from the Global Registry, and returns where to route/redirect the org\r\nsign-in plus a signed realm descriptor. Used by the edge/gateway to route the org host.",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/org-realm/organization": {
"get": {
"description": "\n\r\n Why this is not on M:Essence.Core.Instance.Api.Controllers.DiscoveryController.DiscoverOrgRealm(Essence.Core.Instance.Application.DTOs.OrgRealmDiscoveryRequest,Essence.Core.Instance.Application.Registry.IOrgRealmResolver,Essence.Core.Instance.Application.Registry.IRealmRedirectSigner,System.Threading.CancellationToken). The anonymous realm-discovery\r\n response deliberately carries no organisation id. That omission IS the protection: adding\r\n it would hand any visitor a host→organisation directory, harvestable by pointing the\r\n endpoint at every domain somebody is merely curious about. A caller that legitimately needs\r\n the id — the org portal, resolving which organisation's branding to serve a sign-in page —\r\n is a service, not a browser, so it asks here instead, under\r\n Essence.Core.Instance.Api.Authorization.Policies.PolicyNames.InstanceServiceAccount.\r\n \r\n\n\r\n Bare `[Authorize]` would not have been enough. The class-level attribute admits\r\n any authenticated principal, which includes every end-user bearer token on the platform —\r\n so the directory would have been open to any signed-in user rather than to nobody. The\r\n policy narrows it to the service-account and GlobalAdmin roles.\r\n \r\n\n\r\n Uniform on failure, like its anonymous sibling. An unknown host, a malformed host, a\r\n host whose region label disagrees with the instance, and an organisation whose white-label\r\n entitlement has lapsed all return `200` with a null id — the resolver's own\r\n `Unresolved`, unmodified. A 404 for \"no such host\" and a 200 for \"found\" would make\r\n this an existence oracle for anything holding a service token; the single shape does not.\r\n ",
"operationId": "Discovery_ResolveOrgHostOrganization",
"parameters": [
{
"description": "The sign-in host, e.g. `meridian.gb.onessence.digital`.",
"in": "query",
"name": "host",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/OrgHostOrganizationResponse"
}
}
},
"description": "Answered. `organizationId` is null when the host binds to no live, entitled\r\norganisation — deliberately a 200 rather than a 404."
}
},
"summary": "Resolves an org sign-in host to the organisation behind it, for FIRST-PARTY SERVICES ONLY\r\n(#4788).",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/route": {
"post": {
"operationId": "Discovery_ComputeRoute",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ComputeRouteRequest"
}
},
"application/json": {
"example": {
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ComputeRouteRequest"
}
},
"text/json": {
"example": {
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ComputeRouteRequest"
}
}
},
"description": "Route computation request containing source and target instance IDs."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"confidenceScore": 0,
"decidedAt": "2026-01-01T00:00:00.0000000+00:00",
"estimatedLatency": "string",
"intermediateHops": [],
"isDirect": false,
"isHighConfidence": false,
"isMultiHop": false,
"metadata": {},
"targetEndpoint": "string",
"targetInstanceId": "string",
"totalHops": 0
},
"schema": {
"$ref": "#/components/schemas/RoutingDecision"
}
}
},
"description": "Route computed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request parameters."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No route found between instances."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Computes the optimal route between a source instance and a target instance.\r\nMay return a direct route or a multi-hop route through intermediate instances based on latency.",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/sovereign": {
"get": {
"operationId": "Discovery_ResolveSovereign",
"parameters": [
{
"description": "Optional ISO 3166-1 alpha-2 client country from GeoIP2.",
"in": "query",
"name": "countryCode",
"schema": {
"type": "string"
}
},
{
"description": "Optional GeoIP country-confidence (0–100); defaults to 0.",
"in": "query",
"name": "confidence",
"schema": {
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"outcome": "string",
"reason": "string",
"reasonCode": "string",
"sovereignId": "string"
},
"schema": {
"$ref": "#/components/schemas/SovereignRouteResult"
}
}
},
"description": "An adequate sovereign was resolved (directly or via the default)."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid country code or confidence."
},
"422": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No adequate sovereign for the request (FR-03.024b `no_adequate_sovereign`)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Resolves the sovereign a request should be routed to under the FR-03.024b\r\nGeoIP-unresolvable / no-adequate-sovereign fallback rule. The GeoIP country and\r\nconfidence are supplied as query parameters (produced upstream by the GeoIP2\r\nlookup); omitting countryCode models a GeoIP-unresolvable\r\nlookup. When no adequate sovereign can be resolved and the configured fallback\r\nmode rejects (or the default sovereign is itself inadequate) the endpoint returns\r\n`HTTP 422 no_adequate_sovereign`.",
"tags": [
"Discovery"
]
}
},
"/api/v1/discovery/users/{userId}": {
"get": {
"operationId": "Discovery_DiscoverInstance",
"parameters": [
{
"description": "The unique identifier of the user requesting discovery.",
"in": "path",
"name": "userId",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Optional client latitude for geo-location based routing.",
"in": "query",
"name": "latitude",
"schema": {
"format": "double",
"type": "number"
}
},
{
"description": "Optional client longitude for geo-location based routing.",
"in": "query",
"name": "longitude",
"schema": {
"format": "double",
"type": "number"
}
},
{
"description": "Optional region hint. A user is always discovered to their home region: neither the home instance nor a fallback is ever taken from another region, whatever is requested (#17922).",
"in": "query",
"name": "requestedRegion",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"discoveredAt": "2026-01-01T00:00:00.0000000+00:00",
"endpoint": "string",
"errorMessage": "string",
"instanceId": "string",
"isHealthy": false,
"latency": "string",
"region": "string"
},
"schema": {
"$ref": "#/components/schemas/DiscoveryResult"
}
}
},
"description": "Instance discovered successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request parameters."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No suitable instance found for user."
},
"500": {
"description": "Internal server error."
},
"503": {
"description": "Service Unavailable"
}
},
"summary": "Discovers the optimal instance for a user based on geo-location, health, and routing preferences.\r\nResults are cached for 5 minutes to support high throughput (1M queries/second).",
"tags": [
"Discovery"
]
}
},
"/api/v1/dns/zones": {
"get": {
"operationId": "Dns_ListDnsZones",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/DnsZoneDto"
},
"type": "array"
}
}
},
"description": "DNS zones retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists all DNS zones.",
"tags": [
"Dns"
]
},
"post": {
"operationId": "Dns_CreateDnsZone",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"ownerInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ownerInstanceType": "string",
"parentZoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"provider": "string",
"providerConfiguration": "string",
"zoneName": "string",
"zoneType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateDnsZoneCommand"
}
},
"application/json": {
"example": {
"ownerInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ownerInstanceType": "string",
"parentZoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"provider": "string",
"providerConfiguration": "string",
"zoneName": "string",
"zoneType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateDnsZoneCommand"
}
},
"text/json": {
"example": {
"ownerInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ownerInstanceType": "string",
"parentZoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"provider": "string",
"providerConfiguration": "string",
"zoneName": "string",
"zoneType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateDnsZoneCommand"
}
}
},
"description": "The create DNS zone command."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "DNS zone created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Creates a new DNS zone for an instance.",
"tags": [
"Dns"
]
}
},
"/api/v1/dns/zones/by-name/{name}": {
"get": {
"operationId": "Dns_GetDnsZoneByName",
"parameters": [
{
"description": "The DNS zone name (FQDN).",
"in": "path",
"name": "name",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"ownerInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ownerInstanceType": "string",
"parentZoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"provider": "string",
"records": [],
"status": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"zoneType": "string"
},
"schema": {
"$ref": "#/components/schemas/DnsZoneDto"
}
}
},
"description": "DNS zone retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "DNS zone not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a DNS zone by its fully qualified domain name.",
"tags": [
"Dns"
]
}
},
"/api/v1/dns/zones/{id}": {
"get": {
"operationId": "Dns_GetDnsZoneById",
"parameters": [
{
"description": "The DNS zone ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"ownerInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ownerInstanceType": "string",
"parentZoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"provider": "string",
"records": [],
"status": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"zoneType": "string"
},
"schema": {
"$ref": "#/components/schemas/DnsZoneDto"
}
}
},
"description": "DNS zone retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "DNS zone not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a specific DNS zone by ID, including its records.",
"tags": [
"Dns"
]
}
},
"/api/v1/dns/zones/{id}/records": {
"post": {
"operationId": "Dns_CreateDnsRecord",
"parameters": [
{
"description": "The DNS zone ID to add the record to.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"healthCheckEnabled": false,
"healthCheckEndpoint": "string",
"name": "string",
"priority": 0,
"ttl": 0,
"type": "string",
"value": "string",
"weight": 0,
"zoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/CreateDnsRecordCommand"
}
},
"application/json": {
"example": {
"healthCheckEnabled": false,
"healthCheckEndpoint": "string",
"name": "string",
"priority": 0,
"ttl": 0,
"type": "string",
"value": "string",
"weight": 0,
"zoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/CreateDnsRecordCommand"
}
},
"text/json": {
"example": {
"healthCheckEnabled": false,
"healthCheckEndpoint": "string",
"name": "string",
"priority": 0,
"ttl": 0,
"type": "string",
"value": "string",
"weight": 0,
"zoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/CreateDnsRecordCommand"
}
}
},
"description": "The create DNS record command."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "DNS record created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "DNS zone not found."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The zone already holds a record with this name and type."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Creates a new DNS record within a zone.",
"tags": [
"Dns"
]
}
},
"/api/v1/dns/zones/{id}/records/{recordId}": {
"delete": {
"operationId": "Dns_DeleteDnsRecord",
"parameters": [
{
"description": "The DNS zone ID containing the record.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The DNS record ID to delete.",
"in": "path",
"name": "recordId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "DNS record deleted successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "DNS zone or record not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Deletes a DNS record from a zone.",
"tags": [
"Dns"
]
},
"put": {
"operationId": "Dns_UpdateDnsRecord",
"parameters": [
{
"description": "The DNS zone ID containing the record.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The DNS record ID to update.",
"in": "path",
"name": "recordId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"newValue": "string",
"recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"zoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateDnsRecordCommand"
}
},
"application/json": {
"example": {
"newValue": "string",
"recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"zoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateDnsRecordCommand"
}
},
"text/json": {
"example": {
"newValue": "string",
"recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"zoneId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateDnsRecordCommand"
}
}
},
"description": "The update DNS record command."
},
"responses": {
"200": {
"description": "DNS record updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "DNS zone or record not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates an existing DNS record within a zone.",
"tags": [
"Dns"
]
}
},
"/api/v1/dns/zones/{id}/verify": {
"post": {
"operationId": "Dns_VerifyDnsRecords",
"parameters": [
{
"description": "The DNS zone ID to verify.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "DNS records verification completed."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "DNS zone not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Verifies the health of all DNS records in a zone by querying the DNS provider.",
"tags": [
"Dns"
]
}
},
"/api/v1/documents": {
"post": {
"operationId": "Documents_UploadDocument",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"checksum": "string",
"contentType": "string",
"encryptedMetadata": "string",
"encryptionKeyId": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sizeBytes": 0,
"storageReference": "string",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UploadDocumentCommand"
}
},
"application/json": {
"example": {
"checksum": "string",
"contentType": "string",
"encryptedMetadata": "string",
"encryptionKeyId": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sizeBytes": 0,
"storageReference": "string",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UploadDocumentCommand"
}
},
"text/json": {
"example": {
"checksum": "string",
"contentType": "string",
"encryptedMetadata": "string",
"encryptionKeyId": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sizeBytes": 0,
"storageReference": "string",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UploadDocumentCommand"
}
}
},
"description": "The upload document command."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Document uploaded successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or vault capacity exceeded."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault not found, or the caller is not the owner (existence is not\r\n disclosed to non-owners — debt-2026-06-02-1365)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Uploads an encrypted document to a vault.\r\nDocument content must be encrypted client-side before upload.",
"tags": [
"Documents"
]
}
},
"/api/v1/documents/vault/{vaultId}": {
"get": {
"operationId": "Documents_ListVaultDocuments",
"parameters": [
{
"description": "The vault ID.",
"in": "path",
"name": "vaultId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Whether to include soft-deleted documents (default: false).",
"in": "query",
"name": "includeDeleted",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"description": "Opaque continuation cursor from a prior page's NextCursor, or null for the first slice.",
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"description": "Requested slice size; clamped to [1, 500] (DAT-006).",
"in": "query",
"name": "pageSize",
"schema": {
"default": 100,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"hasMore": false,
"items": [],
"nextCursor": "string",
"pageSize": 0,
"previousCursor": "string"
},
"schema": {
"$ref": "#/components/schemas/VaultDocumentRefCursorResult"
}
}
},
"description": "Documents retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault not found, or the caller is not the owner (existence is not\r\n disclosed to non-owners — debt-2026-06-02-1365)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists a bounded, keyset-paginated slice of the documents in a vault (DAT-006).\r\nAccess is granted only to the vault owner.",
"tags": [
"Documents"
]
}
},
"/api/v1/documents/vault/{vaultId}/search": {
"get": {
"operationId": "Documents_SearchDocuments",
"parameters": [
{
"description": "The vault ID.",
"in": "path",
"name": "vaultId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The name prefix to match against document names.",
"in": "query",
"name": "searchTerm",
"schema": {
"type": "string"
}
},
{
"description": "Opaque continuation cursor from a prior page's NextCursor, or null for the first slice.",
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"description": "Requested slice size; clamped to [1, 500] (DAT-006).",
"in": "query",
"name": "pageSize",
"schema": {
"default": 100,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"hasMore": false,
"items": [],
"nextCursor": "string",
"pageSize": 0,
"previousCursor": "string"
},
"schema": {
"$ref": "#/components/schemas/VaultDocumentRefCursorResult"
}
}
},
"description": "Documents retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault not found, or the caller is not the owner (existence is not\r\n disclosed to non-owners — debt-2026-06-02-1365)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Searches for documents by name prefix within a vault, returning a bounded,\r\nkeyset-paginated slice (DAT-006). Access is granted only to the vault owner.",
"tags": [
"Documents"
]
}
},
"/api/v1/documents/{id}": {
"delete": {
"operationId": "Documents_DeleteDocument",
"parameters": [
{
"description": "The document ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Document deleted successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user does not own the vault containing this document."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Document or vault not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Deletes a document from a vault (soft delete).\r\nDeleted documents can be restored within the retention period.",
"tags": [
"Documents"
]
},
"get": {
"operationId": "Documents_GetDocumentById",
"parameters": [
{
"description": "The document ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"checksum": "string",
"contentType": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"createdBy": "string",
"deletedAt": "2026-01-01T00:00:00.0000000+00:00",
"deletedBy": "string",
"encryptedMetadata": "string",
"encryptionKeyId": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDeleted": false,
"lastAccessedAt": "2026-01-01T00:00:00.0000000+00:00",
"name": "string",
"rowVersion": "string",
"sizeBytes": 0,
"storageReference": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedBy": "string",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/VaultDocumentRef"
}
}
},
"description": "Document retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Document not found, or the caller does not own it (existence is not\r\n disclosed to non-owners — debt-2026-06-02-1390)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a document by its unique identifier.\r\nAccess is granted only to the vault owner.",
"tags": [
"Documents"
]
},
"put": {
"operationId": "Documents_UpdateDocument",
"parameters": [
{
"description": "The document ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"encryptedMetadata": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateDocumentCommand"
}
},
"application/json": {
"example": {
"documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"encryptedMetadata": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateDocumentCommand"
}
},
"text/json": {
"example": {
"documentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"encryptedMetadata": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateDocumentCommand"
}
}
},
"description": "The update document command."
},
"responses": {
"204": {
"description": "Document updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user does not own the vault containing this document."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Document or vault not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates document name and encrypted metadata.",
"tags": [
"Documents"
]
}
},
"/api/v1/edge/routes/{region}": {
"get": {
"description": "\n\r\n Why `[AllowAnonymous]` and a pre-shared secret rather than a JWT (SEC-002). The\r\n caller is Traefik's HTTP provider, which can attach static headers to its poll and cannot\r\n obtain, cache, or refresh a bearer token. The endpoint is nonetheless NOT public: the table\r\n enumerates customers' branded hostnames, so serving it openly would disclose which\r\n organisations are on the white-label SKU. It is therefore gated on a pre-shared secret\r\n compared in constant time (SEC-005), and the service fails closed in every environment —\r\n an unconfigured secret answers 503 rather than serving the table, so a misconfigured box\r\n cannot silently publish the customer list. There is no Development exception: the fleet runs\r\n as Development (#9480), so one would serve the list anonymously in production (#12083).\r\n \r\n\n\r\n A wrong or absent secret answers 404, not 401: a 401 would confirm the endpoint exists\r\n and is worth attacking, and this surface has no legitimate interactive caller to help.\r\n ",
"operationId": "EdgeRoutes_GetRoutes",
"parameters": [
{
"description": "Region code (e.g. \"gb\", \"de\", \"ae\").",
"in": "path",
"name": "region",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TraefikDynamicConfiguration"
}
}
},
"description": "The dynamic configuration (possibly with zero routers)."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The secret was absent or wrong, or the region is malformed."
},
"503": {
"description": "No secret is configured on this host."
}
},
"summary": "Returns the Traefik dynamic configuration for every verified, entitled custom domain homed in\r\nthe given region.",
"tags": [
"EdgeRoutes"
]
}
},
"/api/v1/global-instances": {
"get": {
"operationId": "GlobalInstances_GetGlobalInstance",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"activatedAt": "2026-01-01T00:00:00.0000000+00:00",
"connectedOrganizationInstances": [],
"connectedSovereignInstances": [],
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"createdBy": "string",
"deletedAt": "2026-01-01T00:00:00.0000000+00:00",
"deletedBy": "string",
"domainEvents": [],
"endpointUrl": "string",
"hasDomainEvents": false,
"healthCheckStatus": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDeleted": false,
"isHealthy": false,
"lastHealthCheck": "2026-01-01T00:00:00.0000000+00:00",
"name": "string",
"provisionedAt": "2026-01-01T00:00:00.0000000+00:00",
"rowVersion": "string",
"suspensionReason": "string",
"terminatedAt": "2026-01-01T00:00:00.0000000+00:00",
"terminationReason": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedBy": "string"
},
"schema": {
"$ref": "#/components/schemas/GlobalInstance"
}
}
},
"description": "Global instance retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the current global instance.",
"tags": [
"GlobalInstances"
]
},
"post": {
"description": "The only action on `POST /instances/global` (#14190). The cross-type facade\r\nEssence.Core.Instance.Api.Controllers.InstanceLifecycleController used to declare the same template, which made\r\nevery create an `AmbiguousMatchException`. This action now returns the facade's response — the\r\nEssence.Core.Instance.Application.DTOs.CreateInstanceResponseDto body and a `Location` on the facade's\r\ntype-agnostic read, `GET /instances/{id}` — which is a superset of the bare\r\n`{ id }` this action returned before.",
"operationId": "GlobalInstances_CreateGlobalInstance",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"dataCenter": "string",
"endpointUrl": "string",
"highAvailabilityEnabled": false,
"jurisdiction": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateGlobalInstanceCommand"
}
},
"application/json": {
"example": {
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"dataCenter": "string",
"endpointUrl": "string",
"highAvailabilityEnabled": false,
"jurisdiction": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateGlobalInstanceCommand"
}
},
"text/json": {
"example": {
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"dataCenter": "string",
"endpointUrl": "string",
"highAvailabilityEnabled": false,
"jurisdiction": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateGlobalInstanceCommand"
}
}
},
"description": "The create global instance command."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"location": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateInstanceResponseDto"
}
}
},
"description": "Global instance created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Creates a new global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/rollouts": {
"get": {
"operationId": "CrossRegionRollouts_List",
"parameters": [
{
"description": "How many to return (1..100, default 20).",
"in": "query",
"name": "limit",
"schema": {
"default": 20,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
},
"type": "array"
}
}
},
"description": "The rollouts (empty when none has ever run)."
}
},
"summary": "Lists the most recent rolling releases, newest first.",
"tags": [
"CrossRegionRollouts"
]
},
"post": {
"operationId": "CrossRegionRollouts_Start",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"fromVersion": "string",
"regions": [],
"toVersion": "string"
},
"schema": {
"$ref": "#/components/schemas/StartCrossRegionRolloutRequest"
}
},
"application/json": {
"example": {
"fromVersion": "string",
"regions": [],
"toVersion": "string"
},
"schema": {
"$ref": "#/components/schemas/StartCrossRegionRolloutRequest"
}
},
"text/json": {
"example": {
"fromVersion": "string",
"regions": [],
"toVersion": "string"
},
"schema": {
"$ref": "#/components/schemas/StartCrossRegionRolloutRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Started."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Malformed request."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Another rollout is still live."
},
"422": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The envelope step is a multi-major jump (FR-03.047)."
}
},
"summary": "Opens and starts a rolling release across the given regions, in order.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/global-instances/rollouts/{rolloutId}": {
"get": {
"operationId": "CrossRegionRollouts_Get",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "The rollout."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
}
},
"summary": "Reads one rolling release.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/global-instances/rollouts/{rolloutId}/abandon": {
"post": {
"operationId": "CrossRegionRollouts_Abandon",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Abandoned."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The rollout has already completed or been abandoned."
}
},
"summary": "Abandons a live rollout, rolling back to its from-version.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/global-instances/rollouts/{rolloutId}/halt": {
"post": {
"operationId": "CrossRegionRollouts_Halt",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Halted (`RolloutHaltedManual`)."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The rollout is not in progress."
}
},
"summary": "Halts an in-progress rollout by hand.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/global-instances/rollouts/{rolloutId}/regions/{region}/outcome": {
"post": {
"operationId": "CrossRegionRollouts_RecordOutcome",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "region",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"detail": "string",
"healthy": false
},
"schema": {
"$ref": "#/components/schemas/RolloutRegionOutcomeRequest"
}
},
"application/json": {
"example": {
"detail": "string",
"healthy": false
},
"schema": {
"$ref": "#/components/schemas/RolloutRegionOutcomeRequest"
}
},
"text/json": {
"example": {
"detail": "string",
"healthy": false
},
"schema": {
"$ref": "#/components/schemas/RolloutRegionOutcomeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Recorded; the body shows the resulting state."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The rollout is not in progress, or the region is not the next to roll."
}
},
"summary": "Reports a region's post-roll health outcome — the automatic guard. Healthy rolls the region;\r\nunhealthy halts the rollout into `RolloutHaltedAuto`.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/global-instances/rollouts/{rolloutId}/resume": {
"post": {
"operationId": "CrossRegionRollouts_Resume",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Resumed (`InProgress`)."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The rollout is not halted."
}
},
"summary": "Resumes a halted rollout (auto or manual).",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/global-instances/{id}": {
"delete": {
"operationId": "GlobalInstances_TerminateGlobalInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance terminated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The instance still has live organisation instances (FR-03.007a)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Terminates the global instance (irreversible operation).",
"tags": [
"GlobalInstances"
]
},
"get": {
"operationId": "GlobalInstances_GetGlobalInstanceById",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"activatedAt": "2026-01-01T00:00:00.0000000+00:00",
"connectedOrganizationInstances": [],
"connectedSovereignInstances": [],
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"createdBy": "string",
"deletedAt": "2026-01-01T00:00:00.0000000+00:00",
"deletedBy": "string",
"domainEvents": [],
"endpointUrl": "string",
"hasDomainEvents": false,
"healthCheckStatus": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDeleted": false,
"isHealthy": false,
"lastHealthCheck": "2026-01-01T00:00:00.0000000+00:00",
"name": "string",
"provisionedAt": "2026-01-01T00:00:00.0000000+00:00",
"rowVersion": "string",
"suspensionReason": "string",
"terminatedAt": "2026-01-01T00:00:00.0000000+00:00",
"terminationReason": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedBy": "string"
},
"schema": {
"$ref": "#/components/schemas/GlobalInstance"
}
}
},
"description": "Global instance retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a global instance by ID.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/configuration": {
"put": {
"operationId": "GlobalInstances_UpdateConfiguration",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"autoScalingEnabled": false,
"backupEnabled": false,
"backupRetentionDays": 0,
"highAvailabilityEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateConfigurationCommand"
}
},
"application/json": {
"example": {
"autoScalingEnabled": false,
"backupEnabled": false,
"backupRetentionDays": 0,
"highAvailabilityEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateConfigurationCommand"
}
},
"text/json": {
"example": {
"autoScalingEnabled": false,
"backupEnabled": false,
"backupRetentionDays": 0,
"highAvailabilityEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateConfigurationCommand"
}
}
},
"description": "The update configuration command."
},
"responses": {
"204": {
"description": "Configuration updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the global instance configuration.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/health": {
"post": {
"operationId": "GlobalInstances_UpdateHealthCheck",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
},
"application/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
},
"text/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
}
},
"description": "The update health check command."
},
"responses": {
"204": {
"description": "Health status updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the health status of the global instance.",
"tags": [
"GlobalInstances"
]
},
"put": {
"operationId": "GlobalInstances_UpdateHealthCheck",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
},
"application/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
},
"text/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
}
},
"description": "The update health check command."
},
"responses": {
"204": {
"description": "Health status updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the health status of the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/maintenance/begin": {
"post": {
"operationId": "GlobalInstances_BeginMaintenance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Maintenance mode started successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Begins maintenance mode for the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/maintenance/complete": {
"post": {
"operationId": "GlobalInstances_CompleteMaintenance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Maintenance mode completed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Completes maintenance mode for the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/metadata": {
"put": {
"operationId": "GlobalInstances_UpdateMetadata",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"availabilityZone": "string",
"complianceCertifications": "string",
"dataCenter": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"jurisdiction": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateMetadataCommand"
}
},
"application/json": {
"example": {
"availabilityZone": "string",
"complianceCertifications": "string",
"dataCenter": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"jurisdiction": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateMetadataCommand"
}
},
"text/json": {
"example": {
"availabilityZone": "string",
"complianceCertifications": "string",
"dataCenter": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"jurisdiction": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateMetadataCommand"
}
}
},
"description": "The update metadata command."
},
"responses": {
"204": {
"description": "Metadata updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the global instance metadata.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/organization-instances": {
"get": {
"operationId": "GlobalInstances_GetConnectedOrganizationInstances",
"parameters": [
{
"description": "The global instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
}
}
},
"description": "Organization instances retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves connected organization instance IDs.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/provision": {
"post": {
"operationId": "GlobalInstances_ProvisionGlobalInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance provisioned successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Provisions the global instance (transitions from Provisioning to Active status).",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/resume": {
"post": {
"operationId": "GlobalInstances_ResumeGlobalInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance resumed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Resumes the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/sovereign-instances": {
"get": {
"operationId": "GlobalInstances_GetConnectedSovereignInstances",
"parameters": [
{
"description": "The global instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
}
}
},
"description": "Sovereign instances retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves connected sovereign instance IDs.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/global-instances/{id}/suspend": {
"post": {
"operationId": "GlobalInstances_SuspendGlobalInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance suspended successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Suspends the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances": {
"get": {
"operationId": "InstanceLifecycle_GetAllInstances",
"parameters": [
{
"description": "Optional instance type filter.",
"in": "query",
"name": "instanceType",
"schema": {
"$ref": "#/components/schemas/InstanceType"
}
},
{
"description": "Optional status filter.",
"in": "query",
"name": "status",
"schema": {
"$ref": "#/components/schemas/InstanceStatus"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/InstanceListDto"
},
"type": "array"
}
}
},
"description": "Instances retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves all instances with optional filtering.",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/global": {
"get": {
"operationId": "GlobalInstances_GetGlobalInstance",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"activatedAt": "2026-01-01T00:00:00.0000000+00:00",
"connectedOrganizationInstances": [],
"connectedSovereignInstances": [],
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"createdBy": "string",
"deletedAt": "2026-01-01T00:00:00.0000000+00:00",
"deletedBy": "string",
"domainEvents": [],
"endpointUrl": "string",
"hasDomainEvents": false,
"healthCheckStatus": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDeleted": false,
"isHealthy": false,
"lastHealthCheck": "2026-01-01T00:00:00.0000000+00:00",
"name": "string",
"provisionedAt": "2026-01-01T00:00:00.0000000+00:00",
"rowVersion": "string",
"suspensionReason": "string",
"terminatedAt": "2026-01-01T00:00:00.0000000+00:00",
"terminationReason": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedBy": "string"
},
"schema": {
"$ref": "#/components/schemas/GlobalInstance"
}
}
},
"description": "Global instance retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the current global instance.",
"tags": [
"GlobalInstances"
]
},
"post": {
"description": "The only action on `POST /instances/global` (#14190). The cross-type facade\r\nEssence.Core.Instance.Api.Controllers.InstanceLifecycleController used to declare the same template, which made\r\nevery create an `AmbiguousMatchException`. This action now returns the facade's response — the\r\nEssence.Core.Instance.Application.DTOs.CreateInstanceResponseDto body and a `Location` on the facade's\r\ntype-agnostic read, `GET /instances/{id}` — which is a superset of the bare\r\n`{ id }` this action returned before.",
"operationId": "GlobalInstances_CreateGlobalInstance",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"dataCenter": "string",
"endpointUrl": "string",
"highAvailabilityEnabled": false,
"jurisdiction": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateGlobalInstanceCommand"
}
},
"application/json": {
"example": {
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"dataCenter": "string",
"endpointUrl": "string",
"highAvailabilityEnabled": false,
"jurisdiction": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateGlobalInstanceCommand"
}
},
"text/json": {
"example": {
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"dataCenter": "string",
"endpointUrl": "string",
"highAvailabilityEnabled": false,
"jurisdiction": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateGlobalInstanceCommand"
}
}
},
"description": "The create global instance command."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"location": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateInstanceResponseDto"
}
}
},
"description": "Global instance created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Creates a new global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/rollouts": {
"get": {
"operationId": "CrossRegionRollouts_List",
"parameters": [
{
"description": "How many to return (1..100, default 20).",
"in": "query",
"name": "limit",
"schema": {
"default": 20,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
},
"type": "array"
}
}
},
"description": "The rollouts (empty when none has ever run)."
}
},
"summary": "Lists the most recent rolling releases, newest first.",
"tags": [
"CrossRegionRollouts"
]
},
"post": {
"operationId": "CrossRegionRollouts_Start",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"fromVersion": "string",
"regions": [],
"toVersion": "string"
},
"schema": {
"$ref": "#/components/schemas/StartCrossRegionRolloutRequest"
}
},
"application/json": {
"example": {
"fromVersion": "string",
"regions": [],
"toVersion": "string"
},
"schema": {
"$ref": "#/components/schemas/StartCrossRegionRolloutRequest"
}
},
"text/json": {
"example": {
"fromVersion": "string",
"regions": [],
"toVersion": "string"
},
"schema": {
"$ref": "#/components/schemas/StartCrossRegionRolloutRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Started."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Malformed request."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Another rollout is still live."
},
"422": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The envelope step is a multi-major jump (FR-03.047)."
}
},
"summary": "Opens and starts a rolling release across the given regions, in order.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/instances/global/rollouts/{rolloutId}": {
"get": {
"operationId": "CrossRegionRollouts_Get",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "The rollout."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
}
},
"summary": "Reads one rolling release.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/instances/global/rollouts/{rolloutId}/abandon": {
"post": {
"operationId": "CrossRegionRollouts_Abandon",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Abandoned."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The rollout has already completed or been abandoned."
}
},
"summary": "Abandons a live rollout, rolling back to its from-version.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/instances/global/rollouts/{rolloutId}/halt": {
"post": {
"operationId": "CrossRegionRollouts_Halt",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RolloutReasonRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Halted (`RolloutHaltedManual`)."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The rollout is not in progress."
}
},
"summary": "Halts an in-progress rollout by hand.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/instances/global/rollouts/{rolloutId}/regions/{region}/outcome": {
"post": {
"operationId": "CrossRegionRollouts_RecordOutcome",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "region",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"detail": "string",
"healthy": false
},
"schema": {
"$ref": "#/components/schemas/RolloutRegionOutcomeRequest"
}
},
"application/json": {
"example": {
"detail": "string",
"healthy": false
},
"schema": {
"$ref": "#/components/schemas/RolloutRegionOutcomeRequest"
}
},
"text/json": {
"example": {
"detail": "string",
"healthy": false
},
"schema": {
"$ref": "#/components/schemas/RolloutRegionOutcomeRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Recorded; the body shows the resulting state."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The rollout is not in progress, or the region is not the next to roll."
}
},
"summary": "Reports a region's post-roll health outcome — the automatic guard. Healthy rolls the region;\r\nunhealthy halts the rollout into `RolloutHaltedAuto`.",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/instances/global/rollouts/{rolloutId}/resume": {
"post": {
"operationId": "CrossRegionRollouts_Resume",
"parameters": [
{
"in": "path",
"name": "rolloutId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"endedAt": "2026-01-01T00:00:00.0000000+00:00",
"fromVersion": "string",
"haltReason": "string",
"haltedAutomatically": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"nextRegion": "string",
"orderedRegions": [],
"rolledRegions": [],
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string",
"toVersion": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CrossRegionRolloutDto"
}
}
},
"description": "Resumed (`InProgress`)."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No rollout has that id."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The rollout is not halted."
}
},
"summary": "Resumes a halted rollout (auto or manual).",
"tags": [
"CrossRegionRollouts"
]
}
},
"/api/v1/instances/global/{id}": {
"delete": {
"operationId": "GlobalInstances_TerminateGlobalInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance terminated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The instance still has live organisation instances (FR-03.007a)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Terminates the global instance (irreversible operation).",
"tags": [
"GlobalInstances"
]
},
"get": {
"operationId": "GlobalInstances_GetGlobalInstanceById",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"activatedAt": "2026-01-01T00:00:00.0000000+00:00",
"connectedOrganizationInstances": [],
"connectedSovereignInstances": [],
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"createdBy": "string",
"deletedAt": "2026-01-01T00:00:00.0000000+00:00",
"deletedBy": "string",
"domainEvents": [],
"endpointUrl": "string",
"hasDomainEvents": false,
"healthCheckStatus": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDeleted": false,
"isHealthy": false,
"lastHealthCheck": "2026-01-01T00:00:00.0000000+00:00",
"name": "string",
"provisionedAt": "2026-01-01T00:00:00.0000000+00:00",
"rowVersion": "string",
"suspensionReason": "string",
"terminatedAt": "2026-01-01T00:00:00.0000000+00:00",
"terminationReason": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedBy": "string"
},
"schema": {
"$ref": "#/components/schemas/GlobalInstance"
}
}
},
"description": "Global instance retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a global instance by ID.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/configuration": {
"put": {
"operationId": "GlobalInstances_UpdateConfiguration",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"autoScalingEnabled": false,
"backupEnabled": false,
"backupRetentionDays": 0,
"highAvailabilityEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateConfigurationCommand"
}
},
"application/json": {
"example": {
"autoScalingEnabled": false,
"backupEnabled": false,
"backupRetentionDays": 0,
"highAvailabilityEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateConfigurationCommand"
}
},
"text/json": {
"example": {
"autoScalingEnabled": false,
"backupEnabled": false,
"backupRetentionDays": 0,
"highAvailabilityEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateConfigurationCommand"
}
}
},
"description": "The update configuration command."
},
"responses": {
"204": {
"description": "Configuration updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the global instance configuration.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/health": {
"post": {
"operationId": "GlobalInstances_UpdateHealthCheck",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
},
"application/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
},
"text/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
}
},
"description": "The update health check command."
},
"responses": {
"204": {
"description": "Health status updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the health status of the global instance.",
"tags": [
"GlobalInstances"
]
},
"put": {
"operationId": "GlobalInstances_UpdateHealthCheck",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
},
"application/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
},
"text/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"statusMessage": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateHealthCheckCommand"
}
}
},
"description": "The update health check command."
},
"responses": {
"204": {
"description": "Health status updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the health status of the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/maintenance/begin": {
"post": {
"operationId": "GlobalInstances_BeginMaintenance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Maintenance mode started successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Begins maintenance mode for the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/maintenance/complete": {
"post": {
"operationId": "GlobalInstances_CompleteMaintenance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Maintenance mode completed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Completes maintenance mode for the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/metadata": {
"put": {
"operationId": "GlobalInstances_UpdateMetadata",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"availabilityZone": "string",
"complianceCertifications": "string",
"dataCenter": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"jurisdiction": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateMetadataCommand"
}
},
"application/json": {
"example": {
"availabilityZone": "string",
"complianceCertifications": "string",
"dataCenter": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"jurisdiction": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateMetadataCommand"
}
},
"text/json": {
"example": {
"availabilityZone": "string",
"complianceCertifications": "string",
"dataCenter": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"jurisdiction": "string",
"region": "string",
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateMetadataCommand"
}
}
},
"description": "The update metadata command."
},
"responses": {
"204": {
"description": "Metadata updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the global instance metadata.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/organization-instances": {
"get": {
"operationId": "GlobalInstances_GetConnectedOrganizationInstances",
"parameters": [
{
"description": "The global instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
}
}
},
"description": "Organization instances retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves connected organization instance IDs.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/provision": {
"post": {
"operationId": "GlobalInstances_ProvisionGlobalInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance provisioned successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Provisions the global instance (transitions from Provisioning to Active status).",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/resume": {
"post": {
"operationId": "GlobalInstances_ResumeGlobalInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance resumed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Resumes the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/sovereign-instances": {
"get": {
"operationId": "GlobalInstances_GetConnectedSovereignInstances",
"parameters": [
{
"description": "The global instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"format": "uuid",
"type": "string"
},
"type": "array"
}
}
},
"description": "Sovereign instances retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves connected sovereign instance IDs.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/global/{id}/suspend": {
"post": {
"operationId": "GlobalInstances_SuspendGlobalInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance suspended successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Suspends the global instance.",
"tags": [
"GlobalInstances"
]
}
},
"/api/v1/instances/hierarchy": {
"get": {
"description": "This endpoint materializes the whole fleet into a single in-memory tree, so it is\r\nbounded by Essence.Core.Instance.Application.Configuration.InstanceHierarchyOptions.MaxFleetSize (default 5000 total\r\ninstances). When the live fleet exceeds that bound the endpoint trips a circuit\r\nbreaker and returns HTTP 413, directing callers to the paginated instance-listing\r\nendpoints (`GET /api/v1/instances`) instead of returning an unbounded tree\r\n(debt-2026-06-13-1238).",
"operationId": "InstanceLifecycle_GetInstanceHierarchy",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {},
"type": "array"
}
}
},
"description": "Hierarchy retrieved successfully."
},
"413": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Fleet size exceeds the maximum this endpoint can materialize; use the paginated endpoints."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the full instance hierarchy tree (Global -> Sovereign -> Organization).",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/materialisations": {
"get": {
"operationId": "DedicatedMaterialisations_Queue",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/DedicatedMaterialisationQueueItem"
},
"type": "array"
}
}
},
"description": "The queue. Oldest first because a customer is waiting on each one, and the longest wait is\r\nthe customer closest to asking where their instance is."
}
},
"summary": "The environments waiting to be built, oldest first.",
"tags": [
"DedicatedMaterialisations"
]
}
},
"/api/v1/instances/materialisations/{requestId}/complete": {
"post": {
"operationId": "DedicatedMaterialisations_Complete",
"parameters": [
{
"in": "path",
"name": "requestId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"databaseConnectionString": "string",
"endpointUrl": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteMaterialisationRequest"
}
},
"application/json": {
"example": {
"databaseConnectionString": "string",
"endpointUrl": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteMaterialisationRequest"
}
},
"text/json": {
"example": {
"databaseConnectionString": "string",
"endpointUrl": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteMaterialisationRequest"
}
}
}
},
"responses": {
"204": {
"description": "Recorded; the instance is now Active."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Refused — no database named, no endpoint, or the request is already completed. A dedicated\r\ninstance whose database nobody named is the state this workstream exists to end; accepting a\r\nblank would recreate it with a human's signature on it."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such request."
}
},
"summary": "Report the environment you built. This is what makes the instance Active.",
"tags": [
"DedicatedMaterialisations"
]
}
},
"/api/v1/instances/materialisations/{requestId}/fail": {
"post": {
"description": "\n\r\n The queue needs an exit that is not success. Without one an unbuildable environment — no\r\n capacity in the region until Q4, a platform not yet onboarded — sits Awaiting forever: the\r\n customer waits on a build that will never happen, and the operator has nowhere to put what\r\n they learned.\r\n \r\n\n\r\n This does NOT cancel the organisation's subscription. The instance and its saga are\r\n marked Failed with `rollbackSuccessful: false` — the platform's existing vocabulary for\r\n \"an operator must reconcile the orphaned resources\" — and the exposure is logged with the\r\n artifact ids. Auto-cancelling would be a commercial decision this endpoint has no standing to\r\n make: \"no capacity until Q4\" may be a customer who is happy to wait.\r\n ",
"operationId": "DedicatedMaterialisations_Fail",
"parameters": [
{
"in": "path",
"name": "requestId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/FailMaterialisationRequest"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/FailMaterialisationRequest"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/FailMaterialisationRequest"
}
}
}
},
"responses": {
"204": {
"description": "Recorded. The organisation's billing is untouched and needs a decision."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No reason given, or the request is already resolved."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such request."
}
},
"summary": "Report that the environment cannot be built.",
"tags": [
"DedicatedMaterialisations"
]
}
},
"/api/v1/instances/organization": {
"get": {
"operationId": "OrganizationInstances_ListOrganizationInstances",
"parameters": [
{
"description": "Optional sovereign instance ID to filter by.",
"in": "query",
"name": "sovereignInstanceId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Optional region filter.",
"in": "query",
"name": "region",
"schema": {
"type": "string"
}
},
{
"description": "Page number (1-based, defaults to 1). Applies to the unfiltered admin path.",
"in": "query",
"name": "page",
"schema": {
"default": 1,
"format": "int32",
"type": "integer"
}
},
{
"description": "Items per page (defaults to 50, capped at 100).",
"in": "query",
"name": "pageSize",
"schema": {
"default": 50,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/OrganizationInstanceDto"
},
"type": "array"
}
}
},
"description": "Organization instances retrieved successfully."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists organization instances with optional filtering by sovereign instance or region.\r\nWhen sovereignInstanceId is provided, returns organization instances connected to that sovereign.\r\nOtherwise, returns all organization instances.",
"tags": [
"OrganizationInstances"
]
},
"post": {
"operationId": "OrganizationInstances_CreateOrganizationInstance",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"commercialModel": "string",
"complianceCertifications": "string",
"cpuCores": 0,
"createdByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"creatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"customDomain": "string",
"customFieldsEnabled": false,
"customWorkflowsEnabled": false,
"dataCenter": "string",
"databaseSku": "string",
"dealRegistrationId": "string",
"deploymentRegion": "string",
"endpointUrl": "string",
"faviconUrl": "string",
"founderUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"highAvailabilityEnabled": false,
"infrastructureProvider": "string",
"instanceLicenceSubscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instancePricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceSkuCode": "string",
"integrationsEnabled": false,
"isDedicated": false,
"isPendingClaim": false,
"logoUrl": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"memoryGb": 0,
"monitoringEnabled": false,
"name": "string",
"operatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationDisplayName": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"parentSovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryColor": "string",
"region": "string",
"requestedModuleIds": [],
"secondaryColor": "string",
"serviceEndpointOverrides": {},
"slug": "string",
"storageGb": 0,
"tags": "string",
"version": "string",
"whiteLabelEnabled": false
},
"schema": {
"$ref": "#/components/schemas/CreateOrganizationInstanceCommand"
}
},
"application/json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"commercialModel": "string",
"complianceCertifications": "string",
"cpuCores": 0,
"createdByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"creatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"customDomain": "string",
"customFieldsEnabled": false,
"customWorkflowsEnabled": false,
"dataCenter": "string",
"databaseSku": "string",
"dealRegistrationId": "string",
"deploymentRegion": "string",
"endpointUrl": "string",
"faviconUrl": "string",
"founderUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"highAvailabilityEnabled": false,
"infrastructureProvider": "string",
"instanceLicenceSubscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instancePricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceSkuCode": "string",
"integrationsEnabled": false,
"isDedicated": false,
"isPendingClaim": false,
"logoUrl": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"memoryGb": 0,
"monitoringEnabled": false,
"name": "string",
"operatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationDisplayName": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"parentSovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryColor": "string",
"region": "string",
"requestedModuleIds": [],
"secondaryColor": "string",
"serviceEndpointOverrides": {},
"slug": "string",
"storageGb": 0,
"tags": "string",
"version": "string",
"whiteLabelEnabled": false
},
"schema": {
"$ref": "#/components/schemas/CreateOrganizationInstanceCommand"
}
},
"text/json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"commercialModel": "string",
"complianceCertifications": "string",
"cpuCores": 0,
"createdByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"creatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"customDomain": "string",
"customFieldsEnabled": false,
"customWorkflowsEnabled": false,
"dataCenter": "string",
"databaseSku": "string",
"dealRegistrationId": "string",
"deploymentRegion": "string",
"endpointUrl": "string",
"faviconUrl": "string",
"founderUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"highAvailabilityEnabled": false,
"infrastructureProvider": "string",
"instanceLicenceSubscriptionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instancePricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceSkuCode": "string",
"integrationsEnabled": false,
"isDedicated": false,
"isPendingClaim": false,
"logoUrl": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"memoryGb": 0,
"monitoringEnabled": false,
"name": "string",
"operatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationDisplayName": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"parentSovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"partnerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"pricingPlanId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryColor": "string",
"region": "string",
"requestedModuleIds": [],
"secondaryColor": "string",
"serviceEndpointOverrides": {},
"slug": "string",
"storageGb": 0,
"tags": "string",
"version": "string",
"whiteLabelEnabled": false
},
"schema": {
"$ref": "#/components/schemas/CreateOrganizationInstanceCommand"
}
}
},
"description": "The create organization instance command."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Organization instance created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Parent sovereign or global instance not found."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Creates a new organization instance within the multi-instance hierarchy.",
"tags": [
"OrganizationInstances"
]
}
},
"/api/v1/instances/organization/{id}": {
"get": {
"operationId": "OrganizationInstances_GetOrganizationInstanceById",
"parameters": [
{
"description": "The organization instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"customDomain": "string",
"customDomainEnabled": false,
"endpointUrl": "string",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDedicated": false,
"isHealthy": false,
"lastHealthCheck": "2026-01-01T00:00:00.0000000+00:00",
"name": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/OrganizationInstanceDto"
}
}
},
"description": "Organization instance retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Organization instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a specific organization instance by ID.",
"tags": [
"OrganizationInstances"
]
}
},
"/api/v1/instances/organization/{id}/bootstrap-package": {
"get": {
"operationId": "OrganizationInstances_GetBootstrapPackage",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"blockers": [],
"composeEnvironment": {},
"prerequisites": [],
"runbook": []
},
"schema": {
"$ref": "#/components/schemas/SelfHostedBootstrapPackage"
}
}
},
"description": "The package."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Essence operates this instance, or its deployment model was never recorded — either way there\r\nis no package to give."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Organization instance not found."
}
},
"summary": "Retrieves the bootstrap package for a self-hosted organisation instance (Phase 4.4) —\r\nthe runbook, prerequisites, and `docker-compose.org-instance.yml` environment template\r\nthe organisation needs to stand its own instance up.\r\n \r\n\n\r\nSelf-hosted is the one tenancy where Essence builds nothing. Without this the customer has a\r\nregistry row and no way to use it.\r\n\nThe package carries no credential, by construction — see\r\nEssence.Core.Instance.Domain.Services.SelfHostedBootstrapPackageBuilder. That is what makes it safe to serve to the\r\norganisation's administrator before the claim: credential issuance stays claim-gated\r\n(Phase 1 A3), and the runbook's own step 8 is \"complete your claim\".\r\n",
"tags": [
"OrganizationInstances"
]
}
},
"/api/v1/instances/organization/{id}/custom-domain": {
"delete": {
"operationId": "OrganizationInstances_UnbindCustomDomain",
"parameters": [
{
"description": "The organisation instance id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"boundAt": "2026-01-01T00:00:00.0000000+00:00",
"customDomain": "string",
"enabled": false,
"lastVerificationMessage": "string",
"organizationInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"verificationRecordName": "string",
"verificationRecordValue": "string",
"verifiedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CustomDomainBindingDto"
}
}
},
"description": "The binding was removed (idempotent when nothing was bound)."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such organisation instance."
}
},
"summary": "Removes the custom-domain binding, verified or not (EPIC 3 FR-03.060).",
"tags": [
"OrganizationInstances"
]
},
"get": {
"operationId": "OrganizationInstances_GetCustomDomain",
"parameters": [
{
"description": "The organisation instance id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"boundAt": "2026-01-01T00:00:00.0000000+00:00",
"customDomain": "string",
"enabled": false,
"lastVerificationMessage": "string",
"organizationInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"verificationRecordName": "string",
"verificationRecordValue": "string",
"verifiedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CustomDomainBindingDto"
}
}
},
"description": "The binding state (which may be `None`)."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such organisation instance."
}
},
"summary": "Reads the current custom-domain binding, including the DNS challenge still to be published\r\n(EPIC 3 FR-03.060).",
"tags": [
"OrganizationInstances"
]
},
"post": {
"operationId": "OrganizationInstances_BindCustomDomain",
"parameters": [
{
"description": "The organisation instance id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"customDomain": "string"
},
"schema": {
"$ref": "#/components/schemas/BindCustomDomainRequest"
}
},
"application/json": {
"example": {
"customDomain": "string"
},
"schema": {
"$ref": "#/components/schemas/BindCustomDomainRequest"
}
},
"text/json": {
"example": {
"customDomain": "string"
},
"schema": {
"$ref": "#/components/schemas/BindCustomDomainRequest"
}
}
},
"description": "The domain to claim."
},
"responses": {
"202": {
"content": {
"application/json": {
"example": {
"boundAt": "2026-01-01T00:00:00.0000000+00:00",
"customDomain": "string",
"enabled": false,
"lastVerificationMessage": "string",
"organizationInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"verificationRecordName": "string",
"verificationRecordValue": "string",
"verifiedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CustomDomainBindingDto"
}
}
},
"description": "Claim accepted; publish the returned TXT record, then verify."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The host is malformed, an IP literal, platform-reserved, or already bound elsewhere."
},
"402": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The organisation lacks the white-label add-on."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such organisation instance."
}
},
"summary": "Claims a custom login domain and issues its DNS-ownership challenge (EPIC 3 FR-03.060).\r\n \r\n\n\r\nThe binding does not resolve until M:Essence.Core.Instance.Api.Controllers.OrganizationInstancesController.VerifyCustomDomain(System.Guid,System.Threading.CancellationToken) succeeds — the\r\nresponse carries the exact TXT record name and value the organisation must publish.\r\n",
"tags": [
"OrganizationInstances"
]
}
},
"/api/v1/instances/organization/{id}/custom-domain/verify": {
"post": {
"operationId": "OrganizationInstances_VerifyCustomDomain",
"parameters": [
{
"description": "The organisation instance id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"boundAt": "2026-01-01T00:00:00.0000000+00:00",
"customDomain": "string",
"enabled": false,
"lastVerificationMessage": "string",
"organizationInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"verificationRecordName": "string",
"verificationRecordValue": "string",
"verifiedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/CustomDomainBindingDto"
}
}
},
"description": "Ownership proven; the domain now resolves."
},
"402": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The organisation's white-label add-on lapsed since the claim."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such organisation instance."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The TXT record is absent or does not match the issued challenge."
},
"503": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "DNS could not be queried; ownership is unknown, retry shortly."
}
},
"summary": "Re-checks the published DNS TXT record and, on success, brings the custom domain live\r\n(EPIC 3 FR-03.060).",
"tags": [
"OrganizationInstances"
]
}
},
"/api/v1/instances/organization/{id}/provisioning-status": {
"get": {
"operationId": "OrganizationInstances_GetProvisioningStatus",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"currentStep": 0,
"errorCategory": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceUrl": "string",
"isRetryable": false,
"jurisdiction": "string",
"percentComplete": 0,
"rollbackSuccessful": false,
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"status": "string",
"totalSteps": 0
},
"schema": {
"$ref": "#/components/schemas/ProvisioningStatusDto"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Retrieves the provisioning status for an organization instance.\r\nReturns a sanitised Essence.Core.Instance.Application.DTOs.ProvisioningStatusDto — SubscriptionId,\r\nLicenseId, InvoiceId, raw step JSON, and error stack frames are NOT\r\nreturned (STRIDE info-disclosure mitigation, debt-2026-05-17-086).",
"tags": [
"OrganizationInstances"
]
}
},
"/api/v1/instances/organization/{id}/retry-provisioning": {
"post": {
"description": "\n\r\n The onboarding provisioner may call it (Essence.Core.Instance.Api.Authorization.OrgProvisionerRetryableAttribute,\r\n #22452) to re-drive a rolled-back instance it created rather than create a second one, and only\r\n it may name the founding administrator in the body (#22453).\r\n \r\n\n\r\n A platform operator may force it (`{\"force\":true,\"reason\":\"…\"}`) for a cleanly\r\n rolled-back failure whose category is not retryable, once its cause is fixed — the recovery for\r\n organisations stranded by a failure that was classed Permanent. Recorded on the workflow.\r\n ",
"operationId": "OrganizationInstances_RetryProvisioning",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"force": false,
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RetryProvisioningRequest"
}
},
"application/json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"force": false,
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RetryProvisioningRequest"
}
},
"text/json": {
"example": {
"adminDisplayName": "string",
"adminEmail": "string",
"force": false,
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RetryProvisioningRequest"
}
}
}
},
"responses": {
"202": {
"description": "Retry accepted; a fresh provisioning attempt was enqueued."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A forced retry without a reason."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A forced retry by anyone but a cross-instance platform operator."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The instance or its provisioning workflow was not found."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The provisioning is not in a retryable state."
}
},
"summary": "Re-drives a failed organization-instance provisioning — the S-03.03 retry affordance\r\n(reqf-2026-06-14-265 / reqf-2026-06-20-239) the organization dashboard invokes when\r\nEssence.Core.Instance.Application.DTOs.ProvisioningStatusDto.IsRetryable is true. Eligibility is re-evaluated\r\nserver-side (a cleanly rolled-back Transient/Dependency failure); the read-model flag is\r\nadvisory only. On success a fresh provisioning job is enqueued onto the same background\r\npipeline the initial create used.",
"tags": [
"OrganizationInstances"
]
}
},
"/api/v1/instances/page": {
"get": {
"operationId": "InstanceLifecycle_GetInstancesPage",
"parameters": [
{
"description": "The instance type to page over (required).",
"in": "query",
"name": "instanceType",
"schema": {
"$ref": "#/components/schemas/InstanceType"
}
},
{
"description": "Optional status filter.",
"in": "query",
"name": "status",
"schema": {
"$ref": "#/components/schemas/InstanceStatus"
}
},
{
"description": "Opaque continuation token from a prior response's NextCursor, or null for the first page.",
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"description": "Requested slice size (clamped server-side).",
"in": "query",
"name": "pageSize",
"schema": {
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"hasMore": false,
"items": [],
"nextCursor": "string",
"pageSize": 0,
"previousCursor": "string"
},
"schema": {
"$ref": "#/components/schemas/InstanceListDtoCursorResult"
}
}
},
"description": "Instance page retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a bounded, keyset-paginated slice of instances of a single type (DAT-006).\r\nPreferred over the unbounded M:Essence.Core.Instance.Api.Controllers.InstanceLifecycleController.GetAllInstances(System.Nullable{Essence.Core.Instance.Domain.Enums.InstanceType},System.Nullable{Essence.Core.Instance.Domain.Enums.InstanceStatus},System.Threading.CancellationToken) for client-facing listing of a\r\nfleet that can grow without bound (debt-2026-06-13-1244, debt-2026-06-13-1251).",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/region/{region}": {
"get": {
"operationId": "InstanceLifecycle_GetInstancesByRegion",
"parameters": [
{
"description": "The region to filter by.",
"in": "path",
"name": "region",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "Optional instance type filter.",
"in": "query",
"name": "instanceType",
"schema": {
"$ref": "#/components/schemas/InstanceType"
}
},
{
"description": "Optional status filter.",
"in": "query",
"name": "status",
"schema": {
"$ref": "#/components/schemas/InstanceStatus"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/InstanceListDto"
},
"type": "array"
}
}
},
"description": "Instances retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid region parameter."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves instances in a specific region.",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/region/{region}/page": {
"get": {
"operationId": "InstanceLifecycle_GetInstancesByRegionPage",
"parameters": [
{
"description": "The region to filter by (case-insensitive, required).",
"in": "path",
"name": "region",
"required": true,
"schema": {
"type": "string"
}
},
{
"description": "The instance type to page over (required).",
"in": "query",
"name": "instanceType",
"schema": {
"$ref": "#/components/schemas/InstanceType"
}
},
{
"description": "Optional status filter.",
"in": "query",
"name": "status",
"schema": {
"$ref": "#/components/schemas/InstanceStatus"
}
},
{
"description": "Opaque continuation token from a prior response's NextCursor, or null for the first page.",
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"description": "Requested slice size (clamped server-side).",
"in": "query",
"name": "pageSize",
"schema": {
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"hasMore": false,
"items": [],
"nextCursor": "string",
"pageSize": 0,
"previousCursor": "string"
},
"schema": {
"$ref": "#/components/schemas/InstanceListDtoCursorResult"
}
}
},
"description": "Instance region page retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid region parameter."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a bounded, keyset-paginated slice of instances of a single type within a region\r\n(DAT-006). The region-filtered counterpart of `GET /instances/page`; the bounded\r\nhot-path replacement for the unbounded `GET /instances/region/{region}` on\r\nregion-scoped fleets that can grow without bound (debt-2026-06-21-1062). Paginate each\r\ntype separately — a single keyset cursor cannot span the three aggregate tables.",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/registry/reassign": {
"post": {
"operationId": "Registry_Reassign",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"region": "string",
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/ReassignRegistryRequest"
}
},
"application/json": {
"example": {
"region": "string",
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/ReassignRegistryRequest"
}
},
"text/json": {
"example": {
"region": "string",
"userId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/ReassignRegistryRequest"
}
}
}
},
"responses": {
"200": {
"description": "OK"
}
},
"summary": "UPDATE: re-point the user's mapping at the Sovereign serving the new region (re-home).",
"tags": [
"Registry"
]
}
},
"/api/v1/instances/registry/{userId}": {
"delete": {
"operationId": "Registry_Remove",
"parameters": [
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
},
"summary": "DELETE: drop the user's mapping once their data has been erased from the Sovereign.",
"tags": [
"Registry"
]
},
"get": {
"operationId": "Registry_GetUserHomeInstance",
"parameters": [
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
},
"summary": "Where does this user's data live? Returns the home instance mapping, or 404 if unmapped.",
"tags": [
"Registry"
]
}
},
"/api/v1/instances/returning-national-intakes/{intakeId}/subjects/{userId}": {
"get": {
"operationId": "ReturningNationalIntakeFacts_GetForSubject",
"parameters": [
{
"in": "path",
"name": "intakeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "userId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"basisIssuerJurisdiction": "string",
"basisOriginLoA": "string",
"basisOriginScheme": "string",
"corridorOriginJurisdiction": "string",
"intakeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/ReturningNationalIntakeFacts"
}
},
"text/json": {
"example": {
"basisIssuerJurisdiction": "string",
"basisOriginLoA": "string",
"basisOriginScheme": "string",
"corridorOriginJurisdiction": "string",
"intakeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/ReturningNationalIntakeFacts"
}
},
"text/plain": {
"example": {
"basisIssuerJurisdiction": "string",
"basisOriginLoA": "string",
"basisOriginScheme": "string",
"corridorOriginJurisdiction": "string",
"intakeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/ReturningNationalIntakeFacts"
}
}
},
"description": "The intake's recorded corridor origin and basis credential facts."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such intake for that subject."
}
},
"summary": "Reads the recorded facts of an intake the given subject opened.",
"tags": [
"ReturningNationalIntakeFacts"
]
}
},
"/api/v1/instances/search": {
"get": {
"operationId": "InstanceLifecycle_SearchInstances",
"parameters": [
{
"description": "Optional instance type filter.",
"in": "query",
"name": "instanceType",
"schema": {
"$ref": "#/components/schemas/InstanceType"
}
},
{
"description": "Optional status filter.",
"in": "query",
"name": "status",
"schema": {
"$ref": "#/components/schemas/InstanceStatus"
}
},
{
"description": "Optional case-insensitive substring matched against the instance name.",
"in": "query",
"name": "query",
"schema": {
"type": "string"
}
},
{
"description": "Opaque continuation token from a prior response's NextCursor, or null for the first page.",
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"description": "Requested slice size (clamped server-side to 1..500, default 50).",
"in": "query",
"name": "pageSize",
"schema": {
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"hasMore": false,
"items": [],
"nextCursor": "string",
"pageSize": 0,
"previousCursor": "string"
},
"schema": {
"$ref": "#/components/schemas/InstanceListDtoCursorResult"
}
}
},
"description": "Instance search results retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The supplied cursor is malformed."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Searches instances of every type (Global, Sovereign, Organization) and returns a\r\nbounded, cursor-paginated slice (DAT-006). This is the cross-type counterpart to\r\nM:Essence.Core.Instance.Api.Controllers.InstanceLifecycleController.GetInstancesPage(Essence.Core.Instance.Domain.Enums.InstanceType,System.Nullable{Essence.Core.Instance.Domain.Enums.InstanceStatus},System.String,System.Int32,System.Threading.CancellationToken) (which pages a single required type): the admin\r\n\"Instance Management\" fleet view needs all types at once, filtered by an optional\r\nfree-text name query, instanceType, and\r\nstatus. Distinct route segment `search` so the request no\r\nlonger falls through to M:Essence.Core.Instance.Api.Controllers.InstanceLifecycleController.GetInstanceById(System.Guid,System.Threading.CancellationToken)'s `{id:guid}` template and\r\n400s on a non-GUID segment (debt-2026-06-28-087).",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/sovereign": {
"get": {
"operationId": "SovereignInstances_GetSovereignInstances",
"parameters": [
{
"description": "Optional sovereign region filter: an ISO 3166-1 alpha-2 code (e.g. GB, DE, AE). A cloud region is refused with 400 (EPIC 107 FR-HMF.010/012).",
"in": "query",
"name": "region",
"schema": {
"type": "string"
}
},
{
"description": "Optional jurisdiction code filter (e.g., EU, US, UK).",
"in": "query",
"name": "jurisdictionCode",
"schema": {
"type": "string"
}
},
{
"description": "If true, only returns instances with Active status.",
"in": "query",
"name": "onlyHealthy",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SovereignInstanceDto"
},
"type": "array"
}
}
},
"description": "Sovereign instances retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"errors": {},
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ValidationProblemDetails"
}
}
},
"description": "The region is not a sovereign region (ISO 3166-1 alpha-2)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves sovereign instances with optional filtering by region and/or jurisdiction.",
"tags": [
"SovereignInstances"
]
},
"post": {
"operationId": "SovereignInstances_CreateSovereignInstance",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"allowedStorageRegions": "string",
"allowedTransferJurisdictions": "string",
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"countryCode": "string",
"dataCenter": "string",
"edgeCachingEnabled": false,
"endpointUrl": "string",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"highAvailabilityEnabled": false,
"jurisdictionCode": "string",
"jurisdictionName": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"primaryRegion": "string",
"region": "string",
"regulatoryFramework": "string",
"requireStandardContractualClauses": false,
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateSovereignInstanceCommand"
}
},
"application/json": {
"example": {
"allowedStorageRegions": "string",
"allowedTransferJurisdictions": "string",
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"countryCode": "string",
"dataCenter": "string",
"edgeCachingEnabled": false,
"endpointUrl": "string",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"highAvailabilityEnabled": false,
"jurisdictionCode": "string",
"jurisdictionName": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"primaryRegion": "string",
"region": "string",
"regulatoryFramework": "string",
"requireStandardContractualClauses": false,
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateSovereignInstanceCommand"
}
},
"text/json": {
"example": {
"allowedStorageRegions": "string",
"allowedTransferJurisdictions": "string",
"autoScalingEnabled": false,
"availabilityZone": "string",
"backupEnabled": false,
"backupRetentionDays": 0,
"complianceCertifications": "string",
"countryCode": "string",
"dataCenter": "string",
"edgeCachingEnabled": false,
"endpointUrl": "string",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"highAvailabilityEnabled": false,
"jurisdictionCode": "string",
"jurisdictionName": "string",
"maxApiRequestsPerHour": 0,
"maxConnections": 0,
"maxStorageGb": 0,
"monitoringEnabled": false,
"name": "string",
"primaryRegion": "string",
"region": "string",
"regulatoryFramework": "string",
"requireStandardContractualClauses": false,
"tags": "string",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateSovereignInstanceCommand"
}
}
},
"description": "The create sovereign instance command."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Sovereign instance created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Global instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Creates a new sovereign instance with jurisdiction-specific configuration.",
"tags": [
"SovereignInstances"
]
}
},
"/api/v1/instances/sovereign/{id}": {
"get": {
"operationId": "SovereignInstances_GetSovereignInstanceById",
"parameters": [
{
"description": "The sovereign instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"allowedTransferJurisdictions": [],
"countryCode": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"dataResidencyEnforced": false,
"edgeCachingEnabled": false,
"endpointUrl": "string",
"globalInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"jurisdictionCode": "string",
"jurisdictionName": "string",
"lastHealthCheck": "2026-01-01T00:00:00.0000000+00:00",
"name": "string",
"regulatoryFramework": "string",
"requireStandardContractualClauses": false,
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/SovereignInstanceDto"
}
}
},
"description": "Sovereign instance retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Sovereign instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a specific sovereign instance by ID.",
"tags": [
"SovereignInstances"
]
}
},
"/api/v1/instances/sovereign/{id}/activate": {
"post": {
"operationId": "SovereignInstances_ActivateSovereignInstance",
"parameters": [
{
"description": "The sovereign instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validatorAddress": "string",
"validatorPublicKeyBase64": "string"
},
"schema": {
"$ref": "#/components/schemas/ActivateSovereignInstanceCommand"
}
},
"application/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validatorAddress": "string",
"validatorPublicKeyBase64": "string"
},
"schema": {
"$ref": "#/components/schemas/ActivateSovereignInstanceCommand"
}
},
"text/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"validatorAddress": "string",
"validatorPublicKeyBase64": "string"
},
"schema": {
"$ref": "#/components/schemas/ActivateSovereignInstanceCommand"
}
}
},
"description": "Optional validator bootstrap material."
},
"responses": {
"200": {
"description": "Sovereign instance activated (or already active)."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Sovereign instance not found."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Cannot activate (e.g. validator not registered and no material supplied)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Activates a sovereign instance, transitioning it from Provisioning to Active.\r\nIdempotent: an already-Active instance returns 200. Activation is guarded on validator\r\nregistration; supply validator material in the body to bootstrap a single-validator\r\nchain when none is registered yet.",
"tags": [
"SovereignInstances"
]
}
},
"/api/v1/instances/sovereign/{id}/operating-terms": {
"get": {
"operationId": "SovereignInstanceOperatingTerms_Get",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"recorded": false,
"sovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/SovereignInstanceOperatingTermsDto"
}
}
},
"description": "The terms, or `recorded: false` when no operator is recorded."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such sovereign instance."
}
},
"summary": "Reads the instance's operator and service level.",
"tags": [
"SovereignInstanceOperatingTerms"
]
}
},
"/api/v1/instances/sovereign/{id}/operating-terms/operator": {
"put": {
"operationId": "SovereignInstanceOperatingTerms_RecordOperator",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"operatorLegalJurisdiction": "string",
"operatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RecordSovereignInstanceOperatorRequest"
}
},
"application/json": {
"example": {
"operatorLegalJurisdiction": "string",
"operatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RecordSovereignInstanceOperatorRequest"
}
},
"text/json": {
"example": {
"operatorLegalJurisdiction": "string",
"operatorOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RecordSovereignInstanceOperatorRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"recorded": false,
"sovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/SovereignInstanceOperatingTermsDto"
}
}
},
"description": "The terms as now recorded."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not an ISO 3166-1 alpha-2 jurisdiction, no operator, or a change with no reason."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such sovereign instance."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Another administrator changed the terms first."
}
},
"summary": "Records the instance's operator, or changes it. A change needs a `reason`, and a change\r\nof operator clears the service level the previous operator committed to.",
"tags": [
"SovereignInstanceOperatingTerms"
]
}
},
"/api/v1/instances/sovereign/{id}/operating-terms/service-level": {
"put": {
"operationId": "SovereignInstanceOperatingTerms_DeclareServiceLevel",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"availabilityTargetBasisPoints": 0,
"criticalIncidentResponseMinutes": 0,
"supportCoverage": "string"
},
"schema": {
"$ref": "#/components/schemas/DeclareInstanceServiceLevelRequest"
}
},
"application/json": {
"example": {
"availabilityTargetBasisPoints": 0,
"criticalIncidentResponseMinutes": 0,
"supportCoverage": "string"
},
"schema": {
"$ref": "#/components/schemas/DeclareInstanceServiceLevelRequest"
}
},
"text/json": {
"example": {
"availabilityTargetBasisPoints": 0,
"criticalIncidentResponseMinutes": 0,
"supportCoverage": "string"
},
"schema": {
"$ref": "#/components/schemas/DeclareInstanceServiceLevelRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"recorded": false,
"sovereignInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/SovereignInstanceOperatingTermsDto"
}
}
},
"description": "The terms as now recorded."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "A value outside the accepted ranges, or an unknown coverage."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such sovereign instance."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No operator is recorded, or another administrator changed the terms first."
}
},
"summary": "Declares the current operator's service level for the instance.",
"tags": [
"SovereignInstanceOperatingTerms"
]
}
},
"/api/v1/instances/sovereign/{id}/organization-instances": {
"get": {
"operationId": "SovereignInstances_ListOrganizationsBySovereign",
"parameters": [
{
"description": "The sovereign instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/OrganizationInstanceDto"
},
"type": "array"
}
}
},
"description": "Organization instances retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists all organization instances connected to this sovereign instance.",
"tags": [
"SovereignInstances"
]
}
},
"/api/v1/instances/sovereign/{id}/organization-instances/{orgId}": {
"delete": {
"operationId": "SovereignInstances_DisconnectOrganizationFromSovereign",
"parameters": [
{
"description": "The sovereign instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The organization instance ID to disconnect.",
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Organization instance disconnected successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Sovereign or organization instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Disconnects an organization instance from this sovereign instance.\r\nRemoves the sovereign-to-organization relationship.",
"tags": [
"SovereignInstances"
]
},
"post": {
"operationId": "SovereignInstances_ConnectOrganizationToSovereign",
"parameters": [
{
"description": "The sovereign instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The organization instance ID to connect.",
"in": "path",
"name": "orgId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Organization instance connected successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Sovereign or organization instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Connects an organization instance to this sovereign instance.\r\nEstablishes a sovereign-to-organization relationship.",
"tags": [
"SovereignInstances"
]
}
},
"/api/v1/instances/sovereign/{id}/region": {
"put": {
"operationId": "SovereignInstances_UpdateSovereignInstanceRegion",
"parameters": [
{
"description": "The sovereign instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"allowedStorageRegions": "string",
"allowedTransferJurisdictions": "string",
"edgeCachingEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryRegion": "string",
"requireStandardContractualClauses": false
},
"schema": {
"$ref": "#/components/schemas/UpdateSovereignInstanceRegionCommand"
}
},
"application/json": {
"example": {
"allowedStorageRegions": "string",
"allowedTransferJurisdictions": "string",
"edgeCachingEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryRegion": "string",
"requireStandardContractualClauses": false
},
"schema": {
"$ref": "#/components/schemas/UpdateSovereignInstanceRegionCommand"
}
},
"text/json": {
"example": {
"allowedStorageRegions": "string",
"allowedTransferJurisdictions": "string",
"edgeCachingEnabled": false,
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryRegion": "string",
"requireStandardContractualClauses": false
},
"schema": {
"$ref": "#/components/schemas/UpdateSovereignInstanceRegionCommand"
}
}
},
"description": "The update region command."
},
"responses": {
"200": {
"description": "Data residency rules updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Sovereign instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the data residency rules for a sovereign instance.",
"tags": [
"SovereignInstances"
]
}
},
"/api/v1/instances/sovereign/{id}/validator-registration/retry": {
"post": {
"operationId": "SovereignInstances_RetryValidatorRegistration",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"alreadyRegistered": false,
"centralValidatorId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"errorCode": "string",
"errorMessage": "string",
"registrationTxHash": "string",
"skipped": false,
"success": false
},
"schema": {
"$ref": "#/components/schemas/ValidatorRegistrationRetryResult"
}
}
},
"description": "Retry succeeded or converged to the desired state."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid sovereign instance ID."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Sovereign instance not found."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Validator-set rejected the retry (e.g. conflicting registration)."
},
"503": {
"description": "Validator-set API unreachable after retries."
}
},
"summary": "Retries a failed validator-registration step for an existing\r\nsovereign instance. Operators invoke this when the Tier F-6\r\nstep 9 registration exhausted its retry budget during initial\r\nprovisioning and the sovereign is stuck in\r\nEssence.Core.Instance.Domain.Enums.InstanceStatus.Provisioning\r\nstatus with `ValidatorRegistered = false`.\r\n \r\nReuses the previously-generated Ed25519 keypair so the central\r\nvalidator-set recognises the retry as idempotent.",
"tags": [
"SovereignInstances"
]
}
},
"/api/v1/instances/sponsored-resolutions": {
"post": {
"operationId": "SponsoredResolutions_Resolve",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"fundingBankOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"mode": "string",
"supplierIdentityKey": "string"
},
"schema": {
"$ref": "#/components/schemas/SponsoredResolutionRequest"
}
},
"application/json": {
"example": {
"fundingBankOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"mode": "string",
"supplierIdentityKey": "string"
},
"schema": {
"$ref": "#/components/schemas/SponsoredResolutionRequest"
}
},
"text/json": {
"example": {
"fundingBankOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"mode": "string",
"supplierIdentityKey": "string"
},
"schema": {
"$ref": "#/components/schemas/SponsoredResolutionRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"displayState": "string",
"resolutionRef": "string"
},
"schema": {
"$ref": "#/components/schemas/SponsoredResolutionResponse"
}
},
"text/json": {
"example": {
"displayState": "string",
"resolutionRef": "string"
},
"schema": {
"$ref": "#/components/schemas/SponsoredResolutionResponse"
}
},
"text/plain": {
"example": {
"displayState": "string",
"resolutionRef": "string"
},
"schema": {
"$ref": "#/components/schemas/SponsoredResolutionResponse"
}
}
},
"description": "Resolved. The body cannot tell you which branch was taken."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
},
"text/plain": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "Idempotently resolves a sponsored organisation's identity.",
"tags": [
"SponsoredResolutions"
]
}
},
"/api/v1/instances/sponsored-resolutions/by-organization/{organizationId}": {
"get": {
"description": "Not an AC-19 surface. AC-19 stops a SPONSOR learning whether the supplier it\r\n invited already existed; this route answers \"which identity is THIS organisation\",\r\n a fact the organisation already knows about itself. It is service-account only, it\r\n requires an organisation id as INPUT — which a sponsor is never given, precisely\r\n because M:Essence.Core.Instance.Api.Controllers.SponsoredResolutionsController.Resolve(Essence.Core.Instance.Api.Controllers.SponsoredResolutionRequest,System.Threading.CancellationToken) withholds it — and it returns no lifecycle state, no\r\n sponsor and no sponsorship count, so it cannot be used to probe either.",
"operationId": "SponsoredResolutions_GetByOrganization",
"parameters": [
{
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"supplierIdentityKey": "string"
},
"schema": {
"$ref": "#/components/schemas/SupplierIdentityKeyResponse"
}
},
"text/json": {
"example": {
"supplierIdentityKey": "string"
},
"schema": {
"$ref": "#/components/schemas/SupplierIdentityKeyResponse"
}
},
"text/plain": {
"example": {
"supplierIdentityKey": "string"
},
"schema": {
"$ref": "#/components/schemas/SupplierIdentityKeyResponse"
}
}
},
"description": "Resolved. `supplierIdentityKey` is null when the organisation has no live\r\nsponsored identity — the ordinary case, and deliberately a 200 rather than a 404 so\r\nthe caller cannot distinguish \"no identity\" from \"no such organisation\"."
}
},
"summary": "Resolves the supplier identity an organisation was invited under, for the token\r\nauthority (EPIC 9) to stamp on that organisation's access tokens.",
"tags": [
"SponsoredResolutions"
]
}
},
"/api/v1/instances/supervised": {
"get": {
"operationId": "SupervisedInstances_GetByGuardian",
"parameters": [
{
"description": "Days ahead of a supervision-end date that count as \"approaching\" (default 90).",
"in": "query",
"name": "majorityApproachingWindowDays",
"schema": {
"default": 90,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/SupervisedInstanceDto"
},
"type": "array"
}
}
},
"description": "Roster returned (empty when the caller supervises no minors)."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated, or the token carries no subject."
}
},
"summary": "Lists the supervised instances provisioned under the authenticated guardian — the\r\nroster that powers the supervised-accounts console, with each minor's graduation status\r\nand a majority-approaching transition flag.\r\n \r\n\n\r\nThe roster is strictly caller-scoped: the guardian is read from the bearer token's subject\r\nclaim, never from the request, so a guardian can never enumerate another guardian's minors\r\n(IDOR) — the same contract the sibling roster\r\n`GET /api/v1/family/wards` (`Vault/.../FamilyWardsController`) states, and the\r\nsame reason `POST /api/v1/consent/guardian-grant` refuses a body-supplied grantor.\r\nA guardian who supervises nobody gets `200 []`; an empty roster is not an error\r\n(#6442 — a request-supplied guardian id made the no-query-string call bind\r\nSystem.Guid.Empty and the repository's non-empty guard turned it into a 500).\r\n",
"tags": [
"SupervisedInstances"
]
},
"post": {
"operationId": "SupervisedInstances_Provision",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"ageAssuranceMethod": "string",
"controlTemplateRef": "string",
"graduationScheduleRef": "string",
"guardianId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supervisedInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supervisionEndsOn": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/ProvisionSupervisedInstanceCommand"
}
},
"application/json": {
"example": {
"ageAssuranceMethod": "string",
"controlTemplateRef": "string",
"graduationScheduleRef": "string",
"guardianId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supervisedInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supervisionEndsOn": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/ProvisionSupervisedInstanceCommand"
}
},
"text/json": {
"example": {
"ageAssuranceMethod": "string",
"controlTemplateRef": "string",
"graduationScheduleRef": "string",
"guardianId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supervisedInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supervisionEndsOn": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/ProvisionSupervisedInstanceCommand"
}
}
},
"description": "The provisioning command."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"ageAssuranceAttributeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"ageAssuranceMethod": "string",
"batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"controlTemplateRef": "string",
"graduationScheduleRef": "string",
"guardianId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"majorityApproaching": false,
"provisionedAt": "2026-01-01T00:00:00.0000000+00:00",
"recordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supervisedInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"supervisionEndsOn": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/SupervisedInstanceDto"
}
}
},
"description": "Supervised instance provisioned; audit event emitted."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request (validation or domain rule violation)."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
}
},
"summary": "Provisions a single supervised (minor) instance under a guardian with a durable\r\nage-assurance attribute (the wizard's Step-2 seam).",
"tags": [
"SupervisedInstances"
]
}
},
"/api/v1/instances/supervised/batch": {
"post": {
"operationId": "SupervisedInstances_ProvisionBatch",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"controlTemplateRef": "string",
"graduationScheduleRef": "string",
"guardianId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"roster": []
},
"schema": {
"$ref": "#/components/schemas/BatchProvisionSupervisedInstancesCommand"
}
},
"application/json": {
"example": {
"controlTemplateRef": "string",
"graduationScheduleRef": "string",
"guardianId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"roster": []
},
"schema": {
"$ref": "#/components/schemas/BatchProvisionSupervisedInstancesCommand"
}
},
"text/json": {
"example": {
"controlTemplateRef": "string",
"graduationScheduleRef": "string",
"guardianId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"roster": []
},
"schema": {
"$ref": "#/components/schemas/BatchProvisionSupervisedInstancesCommand"
}
}
},
"description": "The batch provisioning command (guardian + template + roster)."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"batchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"controlTemplateRef": "string",
"instances": [],
"provisionedCount": 0
},
"schema": {
"$ref": "#/components/schemas/BatchProvisionSupervisedInstancesResultDto"
}
}
},
"description": "Cohort provisioned atomically; audit events emitted."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request (validation or a roster entry already provisioned)."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized — caller not authenticated."
}
},
"summary": "Batch-provisions a whole cohort of supervised instances under one guardian with\r\none control template applied across every child, in a single atomic call\r\n(debt-2026-07-09-038). Either the whole roster is provisioned or none is.",
"tags": [
"SupervisedInstances"
]
}
},
"/api/v1/instances/type/{type}": {
"get": {
"operationId": "InstanceLifecycle_GetInstancesByType",
"parameters": [
{
"description": "The instance type: `Global`, `Sovereign` or `Organization`.",
"in": "path",
"name": "type",
"required": true,
"schema": {
"$ref": "#/components/schemas/InstanceType"
}
},
{
"description": "Optional status filter.",
"in": "query",
"name": "status",
"schema": {
"$ref": "#/components/schemas/InstanceStatus"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/InstanceListDto"
},
"type": "array"
}
}
},
"description": "Instances retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unknown instance type."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves instances of one type (EPIC 3 api-contracts §Instance, `GET /instances/type/{type}`,\r\n#10344). The type-keyed sibling of `GET /instances/region/{region}`, with the same\r\npolicy, shape and (unbounded) listing; `GET /instances/page?instanceType=` is the\r\nkeyset-paginated form (DAT-006).",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/vault-rehome": {
"post": {
"operationId": "VaultRehome_StartRehome",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"clientCorrelationId": "string",
"crossesSovereignInstance": false,
"destinationInstanceId": "string",
"destinationInstanceName": "string",
"destinationVaultName": "string",
"documents": [],
"sourceVaultName": "string"
},
"schema": {
"$ref": "#/components/schemas/StartVaultRehomeRequest"
}
},
"application/json": {
"example": {
"clientCorrelationId": "string",
"crossesSovereignInstance": false,
"destinationInstanceId": "string",
"destinationInstanceName": "string",
"destinationVaultName": "string",
"documents": [],
"sourceVaultName": "string"
},
"schema": {
"$ref": "#/components/schemas/StartVaultRehomeRequest"
}
},
"text/json": {
"example": {
"clientCorrelationId": "string",
"crossesSovereignInstance": false,
"destinationInstanceId": "string",
"destinationInstanceName": "string",
"destinationVaultName": "string",
"documents": [],
"sourceVaultName": "string"
},
"schema": {
"$ref": "#/components/schemas/StartVaultRehomeRequest"
}
}
},
"description": "The re-home request: vault display names and the document set."
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"clientCorrelationId": "string",
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"completionEmail": "string",
"completionResultHash": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"crossesSovereignInstance": false,
"destinationInstanceName": "string",
"destinationVaultName": "string",
"documents": [],
"documentsMoved": 0,
"documentsTotal": 0,
"errorCategory": "string",
"percentComplete": 0,
"rehomeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sourceVaultName": "string",
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string"
},
"schema": {
"$ref": "#/components/schemas/VaultRehomeStatusDto"
}
}
},
"description": "The re-home job was created and started; body is its status."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The request is invalid (no documents, duplicate document ids, missing names)."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The caller has no resolvable subject claim."
}
},
"summary": "Starts a vault re-home for the authenticated caller — the INITIATION seam the\r\nfamily-separation-shared-vault-split journey needs (debt-2026-08-12-040). Builds the re-home\r\nset for the receiving party and moves the job to `Moving`; the returned status is the\r\nsame shape `GET /status` subsequently serves, so the surface can render progress\r\nimmediately without a second round trip.\r\n \r\n\n\r\nOwnership is taken from the caller's subject claim and never from the request body, so a\r\ncaller cannot open a re-home job against another person's documents. The optional\r\n`clientCorrelationId` is the initiator's own opaque handle (for the family journey, the\r\nEPIC 30 `{splitId}:{itemId}` reference); it is echoed on the relay completion event so\r\nthe initiator advances its record off the real completion. It must not carry PII.\r\n",
"tags": [
"VaultRehome"
]
}
},
"/api/v1/instances/vault-rehome/{id}/documents/{documentId}/retry": {
"post": {
"operationId": "VaultRehome_RetryDocument",
"parameters": [
{
"description": "The re-home job id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The opaque id of the failed document to retry.",
"in": "path",
"name": "documentId",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"clientCorrelationId": "string",
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"completionEmail": "string",
"completionResultHash": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"crossesSovereignInstance": false,
"destinationInstanceName": "string",
"destinationVaultName": "string",
"documents": [],
"documentsMoved": 0,
"documentsTotal": 0,
"errorCategory": "string",
"percentComplete": 0,
"rehomeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sourceVaultName": "string",
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string"
},
"schema": {
"$ref": "#/components/schemas/VaultRehomeStatusDto"
}
}
},
"description": "The updated re-home status after re-queuing the document."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No such job (or not owned by the caller), or no such document in the job."
}
},
"summary": "Safely retries a single failed document within the re-home job. Re-queues ONLY the named\r\nfailed document — an already-moved document is never re-run. Returns the re-opened status.",
"tags": [
"VaultRehome"
]
}
},
"/api/v1/instances/vault-rehome/{id}/status": {
"get": {
"operationId": "VaultRehome_GetStatus",
"parameters": [
{
"description": "The re-home job id.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"clientCorrelationId": "string",
"completedAt": "2026-01-01T00:00:00.0000000+00:00",
"completionEmail": "string",
"completionResultHash": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"crossesSovereignInstance": false,
"destinationInstanceName": "string",
"destinationVaultName": "string",
"documents": [],
"documentsMoved": 0,
"documentsTotal": 0,
"errorCategory": "string",
"percentComplete": 0,
"rehomeId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sourceVaultName": "string",
"startedAt": "2026-01-01T00:00:00.0000000+00:00",
"state": "string"
},
"schema": {
"$ref": "#/components/schemas/VaultRehomeStatusDto"
}
}
},
"description": "The re-home status."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "No re-home job exists for the id, or it is not owned by the caller."
}
},
"summary": "Gets the sanitised status of a vault re-home job — the \"your documents are moving to your own\r\nvault\" progress + confirmation surface, including the distinct `Partial` terminal state\r\nand the per-document breakdown.",
"tags": [
"VaultRehome"
]
}
},
"/api/v1/instances/{id}": {
"get": {
"operationId": "InstanceLifecycle_GetInstanceById",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Instance retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a specific instance by ID.",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/{id}/activate": {
"post": {
"operationId": "InstanceLifecycle_ActivateInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Instance activated successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Activates an instance by setting its status to Active.",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/{id}/health": {
"put": {
"operationId": "InstanceLifecycle_UpdateInstanceHealth",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"healthCheckStatus": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"timestamp": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/UpdateInstanceHealthCommand"
}
},
"application/json": {
"example": {
"healthCheckStatus": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"timestamp": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/UpdateInstanceHealthCommand"
}
},
"text/json": {
"example": {
"healthCheckStatus": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isHealthy": false,
"timestamp": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/UpdateInstanceHealthCommand"
}
}
},
"description": "The health update command."
},
"responses": {
"204": {
"description": "Health status updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the health status of an instance.",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/{id}/suspend": {
"post": {
"operationId": "InstanceLifecycle_SuspendInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/SuspendInstanceRequest"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/SuspendInstanceRequest"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/SuspendInstanceRequest"
}
}
},
"description": "The suspension request containing the reason."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Instance suspended successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Suspends an instance with an optional reason.",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/instances/{id}/terminate": {
"post": {
"operationId": "InstanceLifecycle_TerminateInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"drain": false,
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/TerminateInstanceRequest"
}
},
"application/json": {
"example": {
"drain": false,
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/TerminateInstanceRequest"
}
},
"text/json": {
"example": {
"drain": false,
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/TerminateInstanceRequest"
}
}
},
"description": "Optional body carrying the operator's reason (DD-069)."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Instance terminated successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "The instance still has live organisation instances and no drain was requested (FR-03.007a)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Terminates an instance (soft delete).",
"tags": [
"InstanceLifecycle"
]
}
},
"/api/v1/internal/messages": {
"post": {
"operationId": "InternalMessaging_ReceiveMessage",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"maxRetries": 0,
"messageId": "string",
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ReceiveMessageRequest"
}
},
"application/json": {
"example": {
"maxRetries": 0,
"messageId": "string",
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ReceiveMessageRequest"
}
},
"text/json": {
"example": {
"maxRetries": 0,
"messageId": "string",
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/ReceiveMessageRequest"
}
}
},
"description": "The incoming message request with encrypted payload."
},
"responses": {
"202": {
"content": {
"application/json": {
"example": {
"correlationId": "string",
"messageId": "string",
"receivedAt": "2026-01-01T00:00:00.0000000+00:00",
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/ReceiveMessageResponse"
}
}
},
"description": "Message accepted for delivery."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request parameters or payload."
},
"429": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Rate limit exceeded (>10K messages/second)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Receives a cross-instance message from another instance.\r\nMessage is authenticated via mTLS through Istio service mesh.\r\nPayloads are bounded to 1 MB per NFR-03.022 (enforced at the\r\nEssence.Core.Instance.Domain.Entities.CrossInstanceMessage aggregate boundary); over-size\r\npayloads are rejected with HTTP 413.",
"tags": [
"InternalMessaging"
]
}
},
"/api/v1/internal/messages/circuit-breaker": {
"get": {
"operationId": "InternalMessaging_GetCircuitBreakerStates",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"checkedAt": "2026-01-01T00:00:00.0000000+00:00",
"circuitBreakers": {}
},
"schema": {
"$ref": "#/components/schemas/CircuitBreakerStatesResponse"
}
}
},
"description": "Circuit breaker states retrieved successfully."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Gets the current circuit breaker states for all target instances.\r\nUseful for monitoring fault isolation and identifying unhealthy target instances.",
"tags": [
"InternalMessaging"
]
}
},
"/api/v1/internal/messages/health": {
"get": {
"operationId": "InternalMessaging_GetHealth",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"averageDeliveryLatency": "string",
"checkedAt": "2026-01-01T00:00:00.0000000+00:00",
"circuitBreakerOpen": false,
"isHealthy": false,
"queueDepth": 0,
"totalMessagesDelivered": 0,
"totalMessagesFailed": 0,
"totalMessagesSent": 0
},
"schema": {
"$ref": "#/components/schemas/MessagingHealthResponse"
}
}
},
"description": "Health check successful."
},
"503": {
"description": "Service unavailable (circuit breakers open or critical issues)."
}
},
"summary": "Gets the health status of the messaging subsystem.\r\nIncludes circuit breaker states, queue depth, and recent delivery statistics.",
"tags": [
"InternalMessaging"
]
}
},
"/api/v1/internal/messages/retry-failed": {
"post": {
"description": "SEC-002/SEC-004 (debt-2026-06-29-325): the retry loop is an expensive, self-targeted\r\noperation, so it is gated to a platform operator (Essence.Core.Instance.Api.Authorization.Policies.PolicyNames.GlobalAdmin) —\r\nmirroring M:Essence.Core.Instance.Api.Controllers.InternalMessagingController.SendMessage(Essence.Core.Instance.Api.Controllers.SendMessageRequest,System.Threading.CancellationToken) — rather than any InstanceServiceAccount identity, and is\r\nbound by the \"essence-strict\" per-subject rate limit (10/min) so it cannot be invoked in a tight\r\nloop to amplify load against the local mesh.",
"operationId": "InternalMessaging_RetryFailedMessages",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"processedAt": "2026-01-01T00:00:00.0000000+00:00",
"successCount": 0
},
"schema": {
"$ref": "#/components/schemas/RetryFailedMessagesResponse"
}
}
},
"description": "Retry operation completed with count of successful retries."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retries all failed messages currently in the queue.\r\nProcesses messages with exponential backoff and respects circuit breaker states.",
"tags": [
"InternalMessaging"
]
}
},
"/api/v1/internal/messages/send": {
"post": {
"operationId": "InternalMessaging_SendMessage",
"parameters": [
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"maxRetries": 0,
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageRequest"
}
},
"application/json": {
"example": {
"maxRetries": 0,
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageRequest"
}
},
"text/json": {
"example": {
"maxRetries": 0,
"payload": "string",
"sourceInstanceId": "string",
"targetInstanceId": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageRequest"
}
}
},
"description": "The outgoing message request with target instance and payload."
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"errorMessage": "string",
"isFailed": false,
"isQueued": false,
"isSuccess": false,
"messageId": "string",
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageResponse"
}
}
},
"description": "Message delivered successfully."
},
"202": {
"content": {
"application/json": {
"example": {
"errorMessage": "string",
"isFailed": false,
"isQueued": false,
"isSuccess": false,
"messageId": "string",
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/SendMessageResponse"
}
}
},
"description": "Message queued for delivery."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request parameters."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - caller is not a platform operator."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Sends a cross-instance message to another instance (admin/testing endpoint).\r\nEncrypts payload client-side before transmission through Istio service mesh with mTLS.",
"tags": [
"InternalMessaging"
]
}
},
"/api/v1/internal/messages/statistics": {
"get": {
"operationId": "InternalMessaging_GetStatistics",
"parameters": [
{
"description": "Optional target instance ID to filter statistics.",
"in": "query",
"name": "targetInstanceId",
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"averageDeliveryLatency": "string",
"circuitBreakerOpen": false,
"instanceId": "string",
"p95DeliveryLatency": "string",
"p99DeliveryLatency": "string",
"retryRate": 0,
"successRate": 0,
"throughputMessagesPerSecond": 0,
"totalMessagesDelivered": 0,
"totalMessagesFailed": 0,
"totalMessagesQueued": 0,
"totalMessagesSent": 0,
"windowEnd": "2026-01-01T00:00:00.0000000+00:00",
"windowStart": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/MessagingStatistics"
}
}
},
"description": "Statistics retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Gets comprehensive messaging statistics for monitoring and diagnostics.\r\nStatistics are aggregated over a rolling 5-minute window.",
"tags": [
"InternalMessaging"
]
}
},
"/api/v1/internal/messages/{messageId}/status": {
"get": {
"operationId": "InternalMessaging_GetMessageStatus",
"parameters": [
{
"description": "The unique identifier of the message to track.",
"in": "path",
"name": "messageId",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "header",
"name": "X-Api-Version",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"lastUpdatedAt": "2026-01-01T00:00:00.0000000+00:00",
"maxRetries": 0,
"messageId": "string",
"queueDepth": 0,
"retryCount": 0,
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/MessageStatusResponse"
}
}
},
"description": "Message status retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid message ID."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Message not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Gets the delivery status of a previously sent cross-instance message.\r\nProvides real-time tracking of message delivery progress through the routing infrastructure.",
"tags": [
"InternalMessaging"
]
}
},
"/api/v1/joint-ventures": {
"get": {
"operationId": "JointVentures_List",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/JointVentureDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Every joint venture the caller's organisation is a party to — the ones it proposed and the\r\nones awaiting its answer.",
"tags": [
"JointVentures"
]
},
"post": {
"operationId": "JointVentures_Propose",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"counterpartBillingSharePercent": 0,
"counterpartOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"counterpartOrganizationName": "string",
"custodyModel": "string",
"name": "string",
"proposingBillingSharePercent": 0,
"proposingOrganizationName": "string",
"requireBothParents": false
},
"schema": {
"$ref": "#/components/schemas/ProposeJointVentureRequest"
}
},
"application/json": {
"example": {
"counterpartBillingSharePercent": 0,
"counterpartOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"counterpartOrganizationName": "string",
"custodyModel": "string",
"name": "string",
"proposingBillingSharePercent": 0,
"proposingOrganizationName": "string",
"requireBothParents": false
},
"schema": {
"$ref": "#/components/schemas/ProposeJointVentureRequest"
}
},
"text/json": {
"example": {
"counterpartBillingSharePercent": 0,
"counterpartOrganizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"counterpartOrganizationName": "string",
"custodyModel": "string",
"name": "string",
"proposingBillingSharePercent": 0,
"proposingOrganizationName": "string",
"requireBothParents": false
},
"schema": {
"$ref": "#/components/schemas/ProposeJointVentureRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"example": {
"approvalQuorum": {},
"custodyModel": "string",
"declineReason": "string",
"dualControlScope": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"proposedAt": "2026-01-01T00:00:00.0000000+00:00",
"respondedAt": "2026-01-01T00:00:00.0000000+00:00",
"sponsors": [],
"status": "string",
"windDownCopyToBothParents": false,
"windDownDestructionRequiresBothParents": false
},
"schema": {
"$ref": "#/components/schemas/JointVentureDto"
}
}
},
"description": "Created"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Proposes a joint venture to a counterpart parent. The agreement is recorded and is NOT\r\nbinding until the counterpart approves it; nothing is provisioned here.",
"tags": [
"JointVentures"
]
}
},
"/api/v1/joint-ventures/acting-organisation": {
"get": {
"description": "The co-provisioning surface needs its own parent's organisation id to build the agreement —\r\nthe billing split and the approval quorum are both keyed by it. It cannot read the claim\r\nitself (the SPA holds no decoded token, deliberately), and it must not invent or guess one:\r\na fabricated sponsor id would key a quorum to an organisation that does not exist, and the\r\nresulting agreement would look complete and bind nobody. So the server says who the caller\r\nis, and a surface that cannot get an answer says so rather than rendering a blank parent.",
"operationId": "JointVentures_GetActingOrganisation",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/ActingOrganizationDto"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "The organisation the caller acts for, as this service resolves it from their token.",
"tags": [
"JointVentures"
]
}
},
"/api/v1/joint-ventures/{jointVentureId}": {
"get": {
"operationId": "JointVentures_Get",
"parameters": [
{
"in": "path",
"name": "jointVentureId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"approvalQuorum": {},
"custodyModel": "string",
"declineReason": "string",
"dualControlScope": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"proposedAt": "2026-01-01T00:00:00.0000000+00:00",
"respondedAt": "2026-01-01T00:00:00.0000000+00:00",
"sponsors": [],
"status": "string",
"windDownCopyToBothParents": false,
"windDownDestructionRequiresBothParents": false
},
"schema": {
"$ref": "#/components/schemas/JointVentureDto"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Reads one agreement. Refused to any caller that is not a party to it.",
"tags": [
"JointVentures"
]
}
},
"/api/v1/joint-ventures/{jointVentureId}/approve": {
"post": {
"operationId": "JointVentures_Approve",
"parameters": [
{
"in": "path",
"name": "jointVentureId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"approvalQuorum": {},
"custodyModel": "string",
"declineReason": "string",
"dualControlScope": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"proposedAt": "2026-01-01T00:00:00.0000000+00:00",
"respondedAt": "2026-01-01T00:00:00.0000000+00:00",
"sponsors": [],
"status": "string",
"windDownCopyToBothParents": false,
"windDownDestructionRequiresBothParents": false
},
"schema": {
"$ref": "#/components/schemas/JointVentureDto"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "The counterpart parent accepts co-ownership on these terms. Refused for the proposing\r\nparent, under every custody model.",
"tags": [
"JointVentures"
]
}
},
"/api/v1/joint-ventures/{jointVentureId}/decline": {
"post": {
"operationId": "JointVentures_Decline",
"parameters": [
{
"in": "path",
"name": "jointVentureId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/DeclineJointVentureRequest"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/DeclineJointVentureRequest"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/DeclineJointVentureRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"approvalQuorum": {},
"custodyModel": "string",
"declineReason": "string",
"dualControlScope": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"proposedAt": "2026-01-01T00:00:00.0000000+00:00",
"respondedAt": "2026-01-01T00:00:00.0000000+00:00",
"sponsors": [],
"status": "string",
"windDownCopyToBothParents": false,
"windDownDestructionRequiresBothParents": false
},
"schema": {
"$ref": "#/components/schemas/JointVentureDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "The counterpart parent refuses the terms, and says why.",
"tags": [
"JointVentures"
]
}
},
"/api/v1/joint-ventures/{jointVentureId}/withdraw": {
"post": {
"operationId": "JointVentures_Withdraw",
"parameters": [
{
"in": "path",
"name": "jointVentureId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"approvalQuorum": {},
"custodyModel": "string",
"declineReason": "string",
"dualControlScope": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"name": "string",
"proposedAt": "2026-01-01T00:00:00.0000000+00:00",
"respondedAt": "2026-01-01T00:00:00.0000000+00:00",
"sponsors": [],
"status": "string",
"windDownCopyToBothParents": false,
"windDownDestructionRequiresBothParents": false
},
"schema": {
"$ref": "#/components/schemas/JointVentureDto"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "The proposing parent withdraws before the counterpart has responded.",
"tags": [
"JointVentures"
]
}
},
"/api/v1/messages": {
"post": {
"operationId": "Messages_SendMessage",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"encryptedBody": "string",
"encryptedMetadata": "string",
"encryptedSubject": "string",
"encryptionKeyId": "string",
"expirationDays": 0,
"recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"recipientInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"senderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"senderInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/SendMessageCommand"
}
},
"application/json": {
"example": {
"encryptedBody": "string",
"encryptedMetadata": "string",
"encryptedSubject": "string",
"encryptionKeyId": "string",
"expirationDays": 0,
"recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"recipientInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"senderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"senderInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/SendMessageCommand"
}
},
"text/json": {
"example": {
"encryptedBody": "string",
"encryptedMetadata": "string",
"encryptedSubject": "string",
"encryptionKeyId": "string",
"expirationDays": 0,
"recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"recipientInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"senderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"senderInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/SendMessageCommand"
}
}
},
"description": "The send message command."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Message sent successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or business rule violation (e.g., self-messaging, inactive recipient)."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Recipient user not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Sends an encrypted message to another user (same or different instance).\r\nMessage subject and body must be encrypted client-side before sending.",
"tags": [
"Messages"
]
}
},
"/api/v1/messages/inbox": {
"get": {
"operationId": "Messages_GetInboxMessages",
"parameters": [
{
"description": "Whether to include read messages (default: true).",
"in": "query",
"name": "includeRead",
"schema": {
"default": true,
"type": "boolean"
}
},
{
"description": "Number of messages to skip for pagination (default: 0).",
"in": "query",
"name": "skip",
"schema": {
"default": 0,
"format": "int32",
"type": "integer"
}
},
{
"description": "Number of messages to retrieve (default: 50, max: 100).",
"in": "query",
"name": "take",
"schema": {
"default": 50,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/UserMessage"
},
"type": "array"
}
}
},
"description": "Inbox messages retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the authenticated user's inbox messages with optional filtering and pagination.",
"tags": [
"Messages"
]
}
},
"/api/v1/messages/inbox/unread-count": {
"get": {
"operationId": "Messages_GetUnreadCount",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"format": "int32",
"type": "integer"
}
}
},
"description": "Unread count retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the count of unread messages for the authenticated user.\r\nUseful for notification badges and inbox summaries.",
"tags": [
"Messages"
]
}
},
"/api/v1/messages/sent": {
"get": {
"operationId": "Messages_GetSentMessages",
"parameters": [
{
"description": "Number of messages to skip for pagination (default: 0).",
"in": "query",
"name": "skip",
"schema": {
"default": 0,
"format": "int32",
"type": "integer"
}
},
{
"description": "Number of messages to retrieve (default: 50, max: 100).",
"in": "query",
"name": "take",
"schema": {
"default": 50,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/UserMessage"
},
"type": "array"
}
}
},
"description": "Sent messages retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the authenticated user's sent messages with pagination.",
"tags": [
"Messages"
]
}
},
"/api/v1/messages/{id}": {
"get": {
"operationId": "Messages_GetMessageById",
"parameters": [
{
"description": "The message ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"createdBy": "string",
"deletedAt": "2026-01-01T00:00:00.0000000+00:00",
"deletedBy": "string",
"deliveryConfirmed": false,
"deliveryConfirmedAt": "2026-01-01T00:00:00.0000000+00:00",
"domainEvents": [],
"encryptedBody": "string",
"encryptedMetadata": "string",
"encryptedSubject": "string",
"encryptionKeyId": "string",
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"hasDomainEvents": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDeleted": false,
"isRead": false,
"readAt": "2026-01-01T00:00:00.0000000+00:00",
"recipientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"recipientInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"rowVersion": "string",
"senderId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"senderInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"sentAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedBy": "string"
},
"schema": {
"$ref": "#/components/schemas/UserMessage"
}
}
},
"description": "Message retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user is not the sender or recipient of this message."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Message not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a single message by its unique identifier.\r\nAccess is granted only to the sender or recipient of the message.",
"tags": [
"Messages"
]
}
},
"/api/v1/messages/{id}/read": {
"post": {
"operationId": "Messages_MarkMessageAsRead",
"parameters": [
{
"description": "The message ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Message marked as read successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Message is expired or already marked as read."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user is not the recipient of this message."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Message not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Marks a message as read by the authenticated recipient.\r\nUpdates the message status and records the read timestamp.\r\nIdempotent: safe to call multiple times.",
"tags": [
"Messages"
]
}
},
"/api/v1/monitoring/alerts": {
"get": {
"operationId": "Monitoring_GetAlerts",
"parameters": [
{
"description": "Alert status filter (active, acknowledged, resolved, suppressed).",
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Alerts retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves alerts filtered by status.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/alerts/{id}/{action}": {
"post": {
"operationId": "Monitoring_PerformAlertAction",
"parameters": [
{
"description": "The alert ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The action to perform (acknowledge, resolve, suppress).",
"in": "path",
"name": "action",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string",
"suppressedUntil": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/AlertActionRequest"
}
},
"application/json": {
"example": {
"reason": "string",
"suppressedUntil": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/AlertActionRequest"
}
},
"text/json": {
"example": {
"reason": "string",
"suppressedUntil": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/AlertActionRequest"
}
}
},
"description": "Required for `suppress`: the reason and the expiry."
},
"responses": {
"200": {
"description": "Action performed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid action specified."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Performs an action on an alert (acknowledge, resolve, suppress).",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/dashboard": {
"get": {
"operationId": "Monitoring_GetDashboard",
"responses": {
"200": {
"description": "Dashboard data retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the monitoring dashboard data including instance health, metrics, alerts, and connectivity.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/health": {
"get": {
"operationId": "Monitoring_GetHealth",
"responses": {
"200": {
"description": "Health data retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves health status for all registered instances.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/incidents": {
"get": {
"operationId": "Monitoring_GetIncidents",
"parameters": [
{
"description": "Incident status filter (open, investigating, root-cause, resolved).",
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Incidents retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves incidents filtered by status.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/incidents/{id}/{action}": {
"post": {
"description": "\n\r\n NOT WIRED, and reported as such. The incident BOARD reads from the Security service, which\r\n owns the incident aggregate (Essence.Core.Instance.Application.Services.Monitoring.IIncidentQueryService); this endpoint used to\r\n validate the id against the six invented seed incidents and then write a status into\r\n Essence.Core.Instance.Application.Services.IMonitoringActionStateStore.IncidentStatusOverrides — a dictionary that has\r\n no reader anywhere in the platform. So a real incident id 404'd, and a seed id (which no\r\n longer appears on the board at all) answered `{ success: true, status: \"resolved\" }`\r\n while changing nothing an operator or auditor would ever see again.\r\n \r\n\n\r\n A 200 that reports a lifecycle transition which did not happen is the worst available\r\n answer on an incident surface: it is the response an operator relies on to believe an\r\n incident is being handled. 501 says the console cannot yet drive the lifecycle, which is\r\n true, and leaves the Security service's own record uncontradicted.\r\n \r\n\n\r\n Wiring it (debt-2026-08-13-007) means calling the owner's\r\n `PUT /api/v1/incidents/{id}`, whose verbs are `StartInvestigation` /\r\n `Contain` / `Resolve`. Two mismatches must be settled first, and neither is a\r\n decision this endpoint can take on its own: `Resolve` REQUIRES a root cause that the\r\n admin console never collects, and the console's `root-cause` verb corresponds to no\r\n owner action (while the owner's `Contain` has no console button).\r\n ",
"operationId": "Monitoring_PerformIncidentAction",
"parameters": [
{
"description": "The incident ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The action to perform (investigate, contain, resolve).",
"in": "path",
"name": "action",
"required": true,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"rootCause": "string"
},
"schema": {
"$ref": "#/components/schemas/IncidentActionRequest"
}
},
"application/json": {
"example": {
"rootCause": "string"
},
"schema": {
"$ref": "#/components/schemas/IncidentActionRequest"
}
},
"text/json": {
"example": {
"rootCause": "string"
},
"schema": {
"$ref": "#/components/schemas/IncidentActionRequest"
}
}
},
"description": "Carries the root cause, which the owner requires to resolve."
},
"responses": {
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid action specified."
},
"501": {
"description": "Recognised action; the console cannot write incident state yet."
}
},
"summary": "Performs an action on an incident (investigate, root-cause, resolve).",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/license-status": {
"get": {
"operationId": "Monitoring_GetLicenseStatus",
"responses": {
"200": {
"description": "License status retrieved successfully."
}
},
"summary": "Retrieves the current air-gapped offline-license status (FR-03.034a / D-61,\r\ndebt-2026-05-31-081, uxf-2026-05-31-085). Drives the platform admin-console\r\n\"prominent warning\" banner — audience Sovereign/Platform Admin — surfacing\r\nthe grace/expired state that fails closed for NEW provisioning while\r\nexisting workloads continue. This is a cheap read of the validator's\r\ncached status (refreshed by the periodic\r\n`AirGappedLicenseValidationHostedService` tick), not a re-verification\r\nof the signed license artifact. Reports `NotApplicable`\r\n(`shouldWarn: false`) for a connected, non-air-gapped deployment.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/metrics": {
"get": {
"operationId": "Monitoring_GetMetrics",
"parameters": [
{
"description": "Start date for the metric range.",
"in": "query",
"name": "startDate",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"description": "End date for the metric range.",
"in": "query",
"name": "endDate",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"description": "Metric name (e.g., cpu, memory, requests, latency).",
"in": "query",
"name": "metric",
"schema": {
"type": "string"
}
},
{
"description": "Metric aggregation type (e.g., instance, service).",
"in": "query",
"name": "type",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Metrics retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves metric data points for the specified time range and metric type.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/self-health": {
"get": {
"operationId": "Monitoring_GetSelfHealth",
"responses": {
"200": {
"description": "Self-health measured."
},
"503": {
"description": "Prometheus is unreachable."
}
},
"summary": "The monitoring stack's health as reported by Prometheus and Alertmanager themselves.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/services": {
"get": {
"operationId": "Monitoring_GetServices",
"responses": {
"200": {
"description": "Measured per-service health."
},
"503": {
"description": "Prometheus is unreachable, so nothing here is knowable."
}
},
"summary": "Per-service golden signals — error rate, request rate, p50/p95/p99 latency and 30-day\r\nscrape uptime — measured from Prometheus.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/monitoring/slas": {
"get": {
"operationId": "Monitoring_GetSlas",
"responses": {
"200": {
"description": "SLA data retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves SLA entries for all monitored services.",
"tags": [
"Monitoring"
]
}
},
"/api/v1/organization/modules": {
"get": {
"deprecated": true,
"operationId": "Organization_ListModules",
"parameters": [
{
"in": "query",
"name": "instanceId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
}
},
"summary": "DEPRECATED — EPIC 26 owns per-organisation module assignment. Use\r\n `GET /api/v1/orgs/{orgId}/modules` (and `…/modules/catalogue`) on the\r\n Module Registry instead. See Essence.Core.Instance.Api.Controllers.OrganizationModuleOwnership for the\r\n ruling, its evidence and what to do if you are reviving this tier.\r\n \n\r\n Lists all available modules and their enabled/disabled state. Reads from the\r\n `InstanceModuleAssignment` table, falls back to static data if empty. Still\r\n functional: deprecated is not retired, deliberately (#10521).\r\n ",
"tags": [
"Organization"
]
}
},
"/api/v1/organization/modules/{moduleId}": {
"put": {
"deprecated": true,
"operationId": "Organization_UpdateModule",
"parameters": [
{
"in": "path",
"name": "moduleId",
"required": true,
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "instanceId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"enabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateModuleRequest"
}
},
"application/json": {
"example": {
"enabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateModuleRequest"
}
},
"text/json": {
"example": {
"enabled": false
},
"schema": {
"$ref": "#/components/schemas/UpdateModuleRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"category": "string",
"description": "string",
"enabled": false,
"installedAt": "2026-01-01T00:00:00.0000000+00:00",
"moduleId": "string",
"name": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"version": "string"
},
"schema": {
"$ref": "#/components/schemas/ModuleEntry"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "DEPRECATED — EPIC 26 owns per-organisation module assignment. Use\r\n `POST /api/v1/orgs/{orgId}/modules/{moduleId}/activate` and\r\n `…/deactivate` on the Module Registry instead. See\r\n Essence.Core.Instance.Api.Controllers.OrganizationModuleOwnership for the ruling, its evidence and what to\r\n do if you are reviving this tier.\r\n \n\r\n Enables or disables a module. Updates `InstanceModuleAssignment` if found,\r\n otherwise falls back to in-memory. Still functional: deprecated is not retired,\r\n deliberately (#10521).\r\n ",
"tags": [
"Organization"
]
}
},
"/api/v1/organization/security": {
"get": {
"operationId": "Organization_GetSecuritySettings",
"parameters": [
{
"in": "query",
"name": "instanceId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"auditLogRetentionDays": 0,
"dataResidencyRegion": "string",
"ipAllowList": [],
"ipAllowListEnabled": false,
"maxSessionsPerUser": 0,
"mfaMethods": [],
"mfaRequired": false,
"sessionTimeoutMinutes": 0,
"ssoEnabled": false,
"ssoEntityId": "string",
"ssoProvider": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/SecuritySettings"
}
}
},
"description": "Security settings retrieved successfully."
}
},
"summary": "Retrieves the security settings for the caller's instance.",
"tags": [
"Organization"
]
},
"put": {
"operationId": "Organization_UpdateSecuritySettings",
"parameters": [
{
"in": "query",
"name": "instanceId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"auditLogRetentionDays": 0,
"dataResidencyRegion": "string",
"ipAllowList": [],
"ipAllowListEnabled": false,
"maxSessionsPerUser": 0,
"mfaMethods": [],
"mfaRequired": false,
"sessionTimeoutMinutes": 0,
"ssoEnabled": false,
"ssoEntityId": "string",
"ssoProvider": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/SecuritySettings"
}
},
"application/json": {
"example": {
"auditLogRetentionDays": 0,
"dataResidencyRegion": "string",
"ipAllowList": [],
"ipAllowListEnabled": false,
"maxSessionsPerUser": 0,
"mfaMethods": [],
"mfaRequired": false,
"sessionTimeoutMinutes": 0,
"ssoEnabled": false,
"ssoEntityId": "string",
"ssoProvider": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/SecuritySettings"
}
},
"text/json": {
"example": {
"auditLogRetentionDays": 0,
"dataResidencyRegion": "string",
"ipAllowList": [],
"ipAllowListEnabled": false,
"maxSessionsPerUser": 0,
"mfaMethods": [],
"mfaRequired": false,
"sessionTimeoutMinutes": 0,
"ssoEnabled": false,
"ssoEntityId": "string",
"ssoProvider": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/SecuritySettings"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"auditLogRetentionDays": 0,
"dataResidencyRegion": "string",
"ipAllowList": [],
"ipAllowListEnabled": false,
"maxSessionsPerUser": 0,
"mfaMethods": [],
"mfaRequired": false,
"sessionTimeoutMinutes": 0,
"ssoEnabled": false,
"ssoEntityId": "string",
"ssoProvider": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/SecuritySettings"
}
}
},
"description": "Security settings updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
}
},
"summary": "Updates the security settings for the caller's instance.",
"tags": [
"Organization"
]
}
},
"/api/v1/organization/settings": {
"get": {
"operationId": "Organization_GetSettings",
"parameters": [
{
"in": "query",
"name": "instanceId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"billingEmail": "string",
"country": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"domain": "string",
"employeeCount": "string",
"industry": "string",
"locale": "string",
"logoUrl": "string",
"name": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryContactEmail": "string",
"primaryContactName": "string",
"slug": "string",
"timezone": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/OrgSettings"
}
}
},
"description": "Settings retrieved successfully."
}
},
"summary": "Retrieves the organization settings for the caller's instance.",
"tags": [
"Organization"
]
},
"put": {
"operationId": "Organization_UpdateSettings",
"parameters": [
{
"in": "query",
"name": "instanceId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"billingEmail": "string",
"country": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"domain": "string",
"employeeCount": "string",
"industry": "string",
"locale": "string",
"logoUrl": "string",
"name": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryContactEmail": "string",
"primaryContactName": "string",
"slug": "string",
"timezone": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/OrgSettings"
}
},
"application/json": {
"example": {
"billingEmail": "string",
"country": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"domain": "string",
"employeeCount": "string",
"industry": "string",
"locale": "string",
"logoUrl": "string",
"name": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryContactEmail": "string",
"primaryContactName": "string",
"slug": "string",
"timezone": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/OrgSettings"
}
},
"text/json": {
"example": {
"billingEmail": "string",
"country": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"domain": "string",
"employeeCount": "string",
"industry": "string",
"locale": "string",
"logoUrl": "string",
"name": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryContactEmail": "string",
"primaryContactName": "string",
"slug": "string",
"timezone": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/OrgSettings"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"billingEmail": "string",
"country": "string",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"domain": "string",
"employeeCount": "string",
"industry": "string",
"locale": "string",
"logoUrl": "string",
"name": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"primaryContactEmail": "string",
"primaryContactName": "string",
"slug": "string",
"timezone": "string",
"updatedAt": "2026-01-01T00:00:00.0000000+00:00"
},
"schema": {
"$ref": "#/components/schemas/OrgSettings"
}
}
},
"description": "Settings updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
}
},
"summary": "Updates the organization settings for the caller's instance.",
"tags": [
"Organization"
]
}
},
"/api/v1/organizations/{organizationId}/residency/evidence": {
"get": {
"operationId": "OrgResidency_GetEvidencePackage",
"parameters": [
{
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"generatedAt": "2026-01-01T00:00:00.0000000+00:00",
"notices": []
},
"schema": {
"$ref": "#/components/schemas/OrgResidencyEvidencePackageDto"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Reads the organisation's own residency evidence package — its status plus the full\r\nrelocation-notice and acknowledgement history. This is the artefact\r\nEssence.Core.Instance.Contracts.DTOs.OrgResidencyStatusDto.EvidencePackageUrl points at, and it is readable by the\r\nsame org administrator that can read the status (unlike the operator-scoped S-03.01 export).",
"tags": [
"OrgResidency"
]
}
},
"/api/v1/organizations/{organizationId}/residency/notices": {
"get": {
"operationId": "OrgResidency_GetNotices",
"parameters": [
{
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/OrgResidencyRelocationNoticeDto"
},
"type": "array"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
}
},
"summary": "Reads the organisation's pre-cutover relocation notices, newest-first, each with the\r\norganisation's recorded response.",
"tags": [
"OrgResidency"
]
}
},
"/api/v1/organizations/{organizationId}/residency/notices/{noticeId}/acknowledge": {
"post": {
"description": "Recording an objection does not itself halt the cutover: whether an organisation's approval\r\nis binding, or whether notification plus an audited operator override suffices, is the open\r\nproduct decision (Tension T1). The write exists so that whichever way that lands, the\r\norganisation's position is attributable and captured before the effective date. A notice may\r\nbe answered once — a replacement would overwrite that evidence.",
"operationId": "OrgResidency_AcknowledgeNotice",
"parameters": [
{
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"in": "path",
"name": "noticeId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"comment": "string",
"response": "string"
},
"schema": {
"$ref": "#/components/schemas/AcknowledgeRelocationNoticeBody"
}
},
"application/json": {
"example": {
"comment": "string",
"response": "string"
},
"schema": {
"$ref": "#/components/schemas/AcknowledgeRelocationNoticeBody"
}
},
"text/json": {
"example": {
"comment": "string",
"response": "string"
},
"schema": {
"$ref": "#/components/schemas/AcknowledgeRelocationNoticeBody"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"destinationRegion": "string",
"effectiveAt": "2026-01-01T00:00:00.0000000+00:00",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legalBasis": "string",
"operationReference": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"plainLanguageImpact": "string",
"raisedAt": "2026-01-01T00:00:00.0000000+00:00",
"raisedBy": "string",
"respondedAt": "2026-01-01T00:00:00.0000000+00:00",
"respondedBy": "string",
"response": "string",
"responseComment": "string",
"sourceRegion": "string",
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/OrgResidencyRelocationNoticeDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Conflict"
}
},
"summary": "Records the organisation's response to a pre-cutover relocation notice — an acknowledgement\r\nor an objection with its reason.",
"tags": [
"OrgResidency"
]
}
},
"/api/v1/organizations/{organizationId}/residency/status": {
"get": {
"operationId": "OrgResidency_GetStatus",
"parameters": [
{
"in": "path",
"name": "organizationId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"currentRegion": "string",
"effectiveAt": "2026-01-01T00:00:00.0000000+00:00",
"evidencePackageUrl": "string",
"legalBasis": "string",
"noticeCount": 0,
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/OrgResidencyStatusDto"
}
}
},
"description": "OK"
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Reads the organisation's current residency status — region, when it took effect, the legal\r\nbasis it is held on, a link to the organisation's own evidence package, and the pending\r\npre-cutover relocation notice when one is in flight.",
"tags": [
"OrgResidency"
]
}
},
"/api/v1/registration": {
"get": {
"operationId": "Registration_ListRegistrationRequests",
"parameters": [
{
"description": "Optional target instance ID filter.",
"in": "query",
"name": "targetInstanceId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Optional status filter (Pending, Approved, Completed, Rejected, Revoked, Expired).",
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
},
{
"description": "Optional requesting instance ID filter.",
"in": "query",
"name": "requestingInstanceId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/RegistrationRequestDto"
},
"type": "array"
}
}
},
"description": "Registration requests retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists registration requests with optional filtering.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/organization-to-sovereign": {
"post": {
"operationId": "Registration_SubmitOrganizationToSovereignRegistration",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"isDedicated": false,
"jurisdictionCode": "string",
"justification": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"region": "string",
"requestType": "string",
"requestedByEmail": "string",
"requestedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceName": "string",
"slug": "string",
"targetInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetInstanceType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateRegistrationRequestCommand"
}
},
"application/json": {
"example": {
"isDedicated": false,
"jurisdictionCode": "string",
"justification": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"region": "string",
"requestType": "string",
"requestedByEmail": "string",
"requestedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceName": "string",
"slug": "string",
"targetInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetInstanceType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateRegistrationRequestCommand"
}
},
"text/json": {
"example": {
"isDedicated": false,
"jurisdictionCode": "string",
"justification": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"region": "string",
"requestType": "string",
"requestedByEmail": "string",
"requestedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceName": "string",
"slug": "string",
"targetInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetInstanceType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateRegistrationRequestCommand"
}
}
},
"description": "The registration request details."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Registration request created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Submits an organization-to-sovereign registration request.\r\nAn organization instance requests to register with a sovereign instance.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/requests": {
"get": {
"operationId": "Registration_ListRegistrationRequests",
"parameters": [
{
"description": "Optional target instance ID filter.",
"in": "query",
"name": "targetInstanceId",
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Optional status filter (Pending, Approved, Completed, Rejected, Revoked, Expired).",
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
},
{
"description": "Optional requesting instance ID filter.",
"in": "query",
"name": "requestingInstanceId",
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/RegistrationRequestDto"
},
"type": "array"
}
}
},
"description": "Registration requests retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists registration requests with optional filtering.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/requests/{id}": {
"get": {
"operationId": "Registration_GetRegistrationRequest",
"parameters": [
{
"description": "The registration request ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"approvalConditions": "string",
"approvalTokenConsumed": false,
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDedicated": false,
"jurisdictionCode": "string",
"justification": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"region": "string",
"rejectionReason": "string",
"requestType": "string",
"requestedByEmail": "string",
"requestedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceName": "string",
"reviewedAt": "2026-01-01T00:00:00.0000000+00:00",
"reviewedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"slug": "string",
"status": "string",
"targetInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetInstanceType": "string"
},
"schema": {
"$ref": "#/components/schemas/RegistrationRequestDto"
}
}
},
"description": "Registration request retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a specific registration request by ID.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/requests/{id}/approve": {
"post": {
"operationId": "Registration_ApproveRegistrationRequest",
"parameters": [
{
"description": "The registration request ID to approve.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"conditions": "string"
},
"schema": {
"$ref": "#/components/schemas/ApproveRegistrationRequestBody"
}
},
"application/json": {
"example": {
"conditions": "string"
},
"schema": {
"$ref": "#/components/schemas/ApproveRegistrationRequestBody"
}
},
"text/json": {
"example": {
"conditions": "string"
},
"schema": {
"$ref": "#/components/schemas/ApproveRegistrationRequestBody"
}
}
},
"description": "The approval details including signing key."
},
"responses": {
"200": {
"description": "Registration request approved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Approves a pending registration request.\r\nGenerates an HMAC-SHA256 approval token for the requesting instance to complete registration.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/requests/{id}/complete": {
"post": {
"operationId": "Registration_CompleteRegistration",
"parameters": [
{
"description": "The registration request ID to complete.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"approvalToken": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteRegistrationRequestBody"
}
},
"application/json": {
"example": {
"approvalToken": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteRegistrationRequestBody"
}
},
"text/json": {
"example": {
"approvalToken": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteRegistrationRequestBody"
}
}
},
"description": "The completion details including approval token."
},
"responses": {
"200": {
"description": "Registration completed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid token or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Completes a registration by validating the approval token.\r\nThe requesting instance uses the token received during approval to finalize registration.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/requests/{id}/reject": {
"post": {
"operationId": "Registration_RejectRegistrationRequest",
"parameters": [
{
"description": "The registration request ID to reject.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RejectRegistrationRequestBody"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RejectRegistrationRequestBody"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RejectRegistrationRequestBody"
}
}
},
"description": "The rejection details including reason."
},
"responses": {
"204": {
"description": "Registration request rejected successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Rejects a pending registration request.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/requests/{id}/revoke": {
"post": {
"operationId": "Registration_RevokeRegistration",
"parameters": [
{
"description": "The registration request ID to revoke.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RevokeRegistrationRequestBody"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RevokeRegistrationRequestBody"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RevokeRegistrationRequestBody"
}
}
},
"description": "The revocation details including reason."
},
"responses": {
"204": {
"description": "Registration revoked successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Revokes a previously approved or completed registration.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/sovereign-to-global": {
"post": {
"operationId": "Registration_SubmitSovereignToGlobalRegistration",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"isDedicated": false,
"jurisdictionCode": "string",
"justification": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"region": "string",
"requestType": "string",
"requestedByEmail": "string",
"requestedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceName": "string",
"slug": "string",
"targetInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetInstanceType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateRegistrationRequestCommand"
}
},
"application/json": {
"example": {
"isDedicated": false,
"jurisdictionCode": "string",
"justification": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"region": "string",
"requestType": "string",
"requestedByEmail": "string",
"requestedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceName": "string",
"slug": "string",
"targetInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetInstanceType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateRegistrationRequestCommand"
}
},
"text/json": {
"example": {
"isDedicated": false,
"jurisdictionCode": "string",
"justification": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"region": "string",
"requestType": "string",
"requestedByEmail": "string",
"requestedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceName": "string",
"slug": "string",
"targetInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetInstanceType": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateRegistrationRequestCommand"
}
}
},
"description": "The registration request details."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Registration request created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Submits a sovereign-to-global registration request.\r\nA sovereign instance requests to register with the global instance.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/{id}": {
"get": {
"operationId": "Registration_GetRegistrationRequest",
"parameters": [
{
"description": "The registration request ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"approvalConditions": "string",
"approvalTokenConsumed": false,
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDedicated": false,
"jurisdictionCode": "string",
"justification": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"organizationName": "string",
"region": "string",
"rejectionReason": "string",
"requestType": "string",
"requestedByEmail": "string",
"requestedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestingInstanceName": "string",
"reviewedAt": "2026-01-01T00:00:00.0000000+00:00",
"reviewedByUserId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"slug": "string",
"status": "string",
"targetInstanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"targetInstanceType": "string"
},
"schema": {
"$ref": "#/components/schemas/RegistrationRequestDto"
}
}
},
"description": "Registration request retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a specific registration request by ID.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/{id}/approve": {
"post": {
"operationId": "Registration_ApproveRegistrationRequest",
"parameters": [
{
"description": "The registration request ID to approve.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"conditions": "string"
},
"schema": {
"$ref": "#/components/schemas/ApproveRegistrationRequestBody"
}
},
"application/json": {
"example": {
"conditions": "string"
},
"schema": {
"$ref": "#/components/schemas/ApproveRegistrationRequestBody"
}
},
"text/json": {
"example": {
"conditions": "string"
},
"schema": {
"$ref": "#/components/schemas/ApproveRegistrationRequestBody"
}
}
},
"description": "The approval details including signing key."
},
"responses": {
"200": {
"description": "Registration request approved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Approves a pending registration request.\r\nGenerates an HMAC-SHA256 approval token for the requesting instance to complete registration.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/{id}/complete": {
"post": {
"operationId": "Registration_CompleteRegistration",
"parameters": [
{
"description": "The registration request ID to complete.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"approvalToken": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteRegistrationRequestBody"
}
},
"application/json": {
"example": {
"approvalToken": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteRegistrationRequestBody"
}
},
"text/json": {
"example": {
"approvalToken": "string"
},
"schema": {
"$ref": "#/components/schemas/CompleteRegistrationRequestBody"
}
}
},
"description": "The completion details including approval token."
},
"responses": {
"200": {
"description": "Registration completed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid token or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Completes a registration by validating the approval token.\r\nThe requesting instance uses the token received during approval to finalize registration.",
"tags": [
"Registration"
]
}
},
"/api/v1/registration/{id}/reject": {
"post": {
"operationId": "Registration_RejectRegistrationRequest",
"parameters": [
{
"description": "The registration request ID to reject.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RejectRegistrationRequestBody"
}
},
"application/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RejectRegistrationRequestBody"
}
},
"text/json": {
"example": {
"reason": "string"
},
"schema": {
"$ref": "#/components/schemas/RejectRegistrationRequestBody"
}
}
},
"description": "The rejection details including reason."
},
"responses": {
"204": {
"description": "Registration request rejected successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data or validation failure."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registration request not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Rejects a pending registration request.",
"tags": [
"Registration"
]
}
},
"/api/v1/registry": {
"get": {
"operationId": "InstanceRegistry_GetRegistry",
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"createdBy": "string",
"deletedAt": "2026-01-01T00:00:00.0000000+00:00",
"deletedBy": "string",
"description": "string",
"domainEvents": [],
"entries": {},
"hasDomainEvents": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isDeleted": false,
"lastUpdatedAt": "2026-01-01T00:00:00.0000000+00:00",
"name": "string",
"rowVersion": "string",
"totalInstances": 0,
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedBy": "string"
},
"schema": {
"$ref": "#/components/schemas/InstanceRegistry"
}
}
},
"description": "Registry retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Registry not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the global instance registry.",
"tags": [
"InstanceRegistry"
]
}
},
"/api/v1/registry/instances": {
"post": {
"operationId": "InstanceRegistry_RegisterInstance",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"endpointUrl": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceName": "string",
"region": "string"
},
"schema": {
"$ref": "#/components/schemas/RegisterInstanceCommand"
}
},
"application/json": {
"example": {
"endpointUrl": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceName": "string",
"region": "string"
},
"schema": {
"$ref": "#/components/schemas/RegisterInstanceCommand"
}
},
"text/json": {
"example": {
"endpointUrl": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceName": "string",
"region": "string"
},
"schema": {
"$ref": "#/components/schemas/RegisterInstanceCommand"
}
}
},
"description": "The register instance command."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Instance registered successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
},
"409": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance already registered."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Registers a new instance in the registry.",
"tags": [
"InstanceRegistry"
]
}
},
"/api/v1/registry/instances/by-type/{instanceType}": {
"get": {
"operationId": "InstanceRegistry_GetInstancesByType",
"parameters": [
{
"description": "The instance type filter.",
"in": "path",
"name": "instanceType",
"required": true,
"schema": {
"$ref": "#/components/schemas/InstanceType"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/InstanceRegistryEntry"
},
"type": "array"
}
}
},
"description": "Instances retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid instance type."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves instances by type.",
"tags": [
"InstanceRegistry"
]
}
},
"/api/v1/registry/instances/count": {
"get": {
"operationId": "InstanceRegistry_GetTotalInstanceCount",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"format": "int32",
"type": "integer"
}
}
},
"description": "Count retrieved successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the total count of registered instances.",
"tags": [
"InstanceRegistry"
]
}
},
"/api/v1/registry/instances/{instanceId}": {
"delete": {
"operationId": "InstanceRegistry_UnregisterInstance",
"parameters": [
{
"description": "The instance ID to unregister.",
"in": "path",
"name": "instanceId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Instance unregistered successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Unregisters an instance from the registry.",
"tags": [
"InstanceRegistry"
]
},
"get": {
"operationId": "InstanceRegistry_GetInstanceEntry",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "instanceId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"activationUpdatedAt": "2026-01-01T00:00:00.0000000+00:00",
"endpointUrl": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceName": "string",
"region": "string",
"registeredAt": "2026-01-01T00:00:00.0000000+00:00",
"registryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subscriptionTier": "string"
},
"schema": {
"$ref": "#/components/schemas/InstanceRegistryEntry"
}
}
},
"description": "Instance entry retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a specific instance entry from the registry.",
"tags": [
"InstanceRegistry"
]
}
},
"/api/v1/registry/instances/{instanceId}/endpoint": {
"put": {
"operationId": "InstanceRegistry_UpdateInstanceEndpoint",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "instanceId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"newEndpointUrl": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateInstanceEndpointCommand"
}
},
"application/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"newEndpointUrl": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateInstanceEndpointCommand"
}
},
"text/json": {
"example": {
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"newEndpointUrl": "string"
},
"schema": {
"$ref": "#/components/schemas/UpdateInstanceEndpointCommand"
}
}
},
"description": "The update endpoint command."
},
"responses": {
"204": {
"description": "Endpoint updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Instance not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates the endpoint URL for an instance.",
"tags": [
"InstanceRegistry"
]
}
},
"/api/v1/registry/instances/{instanceId}/registered": {
"get": {
"operationId": "InstanceRegistry_IsInstanceRegistered",
"parameters": [
{
"description": "The instance ID to check.",
"in": "path",
"name": "instanceId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"type": "boolean"
}
}
},
"description": "Check completed successfully."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Checks if an instance is registered.",
"tags": [
"InstanceRegistry"
]
}
},
"/api/v1/registry/users/me/vaults": {
"get": {
"operationId": "UserVaultRegistry_GetMyVaults",
"responses": {
"200": {
"description": "Registry entries retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves the authenticated caller's vault registry entries — one row per vault they own,\r\nacross every sovereign region.",
"tags": [
"UserVaultRegistry"
]
}
},
"/api/v1/residency/adequacy-matrix/corridors/inadequate": {
"post": {
"operationId": "Residency_RevokeCorridorAdequacy",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"reason": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/RevokeCorridorAdequacyBody"
}
},
"application/json": {
"example": {
"reason": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/RevokeCorridorAdequacyBody"
}
},
"text/json": {
"example": {
"reason": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string"
},
"schema": {
"$ref": "#/components/schemas/RevokeCorridorAdequacyBody"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "FR-03.029a matrix-maintenance write — the adequacy-decision authority flips a corridor to\r\ninadequate. Triggers enforcement: still-valid approvals over the corridor are\r\nauto-expired (system-initiated `Expired`, reason `adequacy-matrix-revoked`) and any\r\nin-flight transfer is halted at its next checkpoint (reason `matrix-change`), so a stale\r\napproval can never re-authorise a transfer the matrix no longer permits.",
"tags": [
"Residency"
]
}
},
"/api/v1/residency/approvals": {
"get": {
"operationId": "Residency_GetApprovals",
"parameters": [
{
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "pageSize",
"schema": {
"default": 50,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"hasMore": false,
"items": [],
"nextCursor": "string",
"pageSize": 0,
"previousCursor": "string"
},
"schema": {
"$ref": "#/components/schemas/CrossBorderApprovalDtoCursorResult"
}
}
},
"description": "OK"
}
},
"summary": "S-03.02 (read) — cross-border approval queue. Returns pending / active / expiring approval\r\nrequests with their resolved adequacy-matrix outcome and decision metadata.",
"tags": [
"Residency"
]
},
"post": {
"description": "SEC-002/SEC-004 (debt-2026-06-28-720): origination is restricted by an explicit role gate —\r\nonly an admin for the instance (InstanceAdmin) or a cross-instance platform operator may\r\noriginate a cross-border transfer request. This AND-combines with the controller-level\r\nEssence.Core.Instance.Api.Authorization.Policies.PolicyNames.InstanceAdminFor policy. The PascalCase role list it replaces\r\ncould not match the platform's `platform-admin`, so the platform's own superuser was\r\nrefused here (#22641). The \"essence-strict\"\r\nper-subject rate limit (10/min) bounds queue-flooding of the approval queue by any single caller.",
"operationId": "Residency_RequestApproval",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"dataClassification": "string",
"purpose": "string",
"recipient": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string",
"territories": []
},
"schema": {
"$ref": "#/components/schemas/RequestCrossBorderApprovalBody"
}
},
"application/json": {
"example": {
"dataClassification": "string",
"purpose": "string",
"recipient": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string",
"territories": []
},
"schema": {
"$ref": "#/components/schemas/RequestCrossBorderApprovalBody"
}
},
"text/json": {
"example": {
"dataClassification": "string",
"purpose": "string",
"recipient": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string",
"territories": []
},
"schema": {
"$ref": "#/components/schemas/RequestCrossBorderApprovalBody"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "S-03.02 (write) — raises a new pending cross-border approval request (the C-03.02 \"Request\r\ncross-border approval\" affordance). The requesting actor is established server-side from the\r\ncaller's identity.",
"tags": [
"Residency"
]
}
},
"/api/v1/residency/approvals/{id}/approve": {
"post": {
"operationId": "Residency_Approve",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
},
"application/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
},
"text/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "S-03.02 (write) — approves a pending cross-border transfer request.",
"tags": [
"Residency"
]
}
},
"/api/v1/residency/approvals/{id}/deny": {
"post": {
"operationId": "Residency_Deny",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
},
"application/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
},
"text/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "S-03.02 (write) — denies a pending cross-border transfer request.",
"tags": [
"Residency"
]
}
},
"/api/v1/residency/approvals/{id}/expire": {
"post": {
"operationId": "Residency_Expire",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
},
"application/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
},
"text/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"mechanism": "string",
"reason": "string",
"scope": "string"
},
"schema": {
"$ref": "#/components/schemas/ApprovalDecisionBody"
}
}
}
},
"responses": {
"202": {
"description": "Accepted"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "S-03.02 (write) — gracefully expires a previously-approved transfer (no violation).",
"tags": [
"Residency"
]
}
},
"/api/v1/residency/cross-border-verdict": {
"get": {
"operationId": "Residency_GetCrossBorderVerdict",
"parameters": [
{
"in": "query",
"name": "source",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "target",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "recipient",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"adequacyOutcome": "string",
"approvalId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"approvalStatus": "string",
"approvingAuthority": "string",
"binding": false,
"decidedAt": "2026-01-01T00:00:00.0000000+00:00",
"evaluatedAt": "2026-01-01T00:00:00.0000000+00:00",
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"legalBasis": "string",
"recipient": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string",
"verdict": "string"
},
"schema": {
"$ref": "#/components/schemas/CrossBorderVerdictDto"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "S-03.02 (read) — the binding cross-border verdict (FR-03.029a) for a proposed\r\nmigration corridor. Returns one authoritative Essence.Core.Instance.Contracts.DTOs.CrossBorderVerdictDto\r\n(Permitted / Pending / Denied) derived server-side from the adequacy-decision matrix and the\r\nrecorded approval requests, so the vault-cross-instance-migration pre-flight surface can show\r\nand export a decision that gates the transfer instead of a client-side advisory preview\r\n(debt-2026-07-03-029). Metadata-only — corridor, legal basis, authority, timestamps.",
"tags": [
"Residency"
]
}
},
"/api/v1/residency/my/approvals": {
"get": {
"operationId": "SubjectResidency_GetApprovals",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/CrossBorderApprovalDto"
},
"type": "array"
}
}
},
"description": "OK"
}
},
"summary": "Lists the cross-border approval requests the caller raised for themselves, newest-first,\r\neach with its current state (Pending / Approved / Denied / Expired) and, once decided, the\r\ndeciding authority and reason.",
"tags": [
"SubjectResidency"
]
},
"post": {
"operationId": "SubjectResidency_RequestApproval",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"dataClassification": "string",
"purpose": "string",
"recipient": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string",
"territories": []
},
"schema": {
"$ref": "#/components/schemas/SubjectApprovalRequestBody"
}
},
"application/json": {
"example": {
"dataClassification": "string",
"purpose": "string",
"recipient": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string",
"territories": []
},
"schema": {
"$ref": "#/components/schemas/SubjectApprovalRequestBody"
}
},
"text/json": {
"example": {
"dataClassification": "string",
"purpose": "string",
"recipient": "string",
"sourceJurisdiction": "string",
"targetJurisdiction": "string",
"territories": []
},
"schema": {
"$ref": "#/components/schemas/SubjectApprovalRequestBody"
}
}
}
},
"responses": {
"202": {
"content": {
"application/json": {
"example": {
"adequacyOutcome": "string",
"dataClassification": "string",
"decidedAt": "2026-01-01T00:00:00.0000000+00:00",
"decidedBy": "string",
"decisionReason": "string",
"decisionScope": "string",
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"mechanism": "string",
"origin": "string",
"purpose": "string",
"recipient": "string",
"requestedAt": "2026-01-01T00:00:00.0000000+00:00",
"requestedBy": "string",
"sourceJurisdiction": "string",
"status": "string",
"targetJurisdiction": "string",
"territories": []
},
"schema": {
"$ref": "#/components/schemas/CrossBorderApprovalDto"
}
}
},
"description": "Accepted"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "Raises a cross-border approval request for a corridor affecting the caller's OWN data.\r\nThe request enters the same FR-03.029a approval queue an authority-raised one does, marked\r\n`Origin = DataSubject` so the console can tell that a person is waiting on the reply.",
"tags": [
"SubjectResidency"
]
}
},
"/api/v1/residency/my/approvals/{id}": {
"get": {
"operationId": "SubjectResidency_GetApproval",
"parameters": [
{
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"adequacyOutcome": "string",
"dataClassification": "string",
"decidedAt": "2026-01-01T00:00:00.0000000+00:00",
"decidedBy": "string",
"decisionReason": "string",
"decisionScope": "string",
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"mechanism": "string",
"origin": "string",
"purpose": "string",
"recipient": "string",
"requestedAt": "2026-01-01T00:00:00.0000000+00:00",
"requestedBy": "string",
"sourceJurisdiction": "string",
"status": "string",
"targetJurisdiction": "string",
"territories": []
},
"schema": {
"$ref": "#/components/schemas/CrossBorderApprovalDto"
}
}
},
"description": "OK"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Not Found"
}
},
"summary": "Reads one of the caller's own cross-border approval requests. A request that does not exist\r\nand one that belongs to another subject both return 404 — deliberately indistinguishable.",
"tags": [
"SubjectResidency"
]
}
},
"/api/v1/residency/relocation-notices": {
"post": {
"description": "Issued when an EPIC 88 `ResidencyMigration` lifecycle operation begins, so the affected\r\norganisation learns of the move before it happens and the `ResidencyPositionApproved`\r\ngate has attributable notification evidence. The organisation reads the notice, and records\r\nits response, through Essence.Core.Instance.Api.Controllers.OrgResidencyController.\r\n \r\n\nThe effective date must be in the future: a \"pre-cutover notice\" served on or after\r\nthe cutover is not a notice, and accepting one would let the gate claim notification\r\nevidence it does not have.",
"operationId": "Residency_RaiseRelocationNotice",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"destinationRegion": "string",
"effectiveAt": "2026-01-01T00:00:00.0000000+00:00",
"legalBasis": "string",
"operationReference": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"plainLanguageImpact": "string",
"sourceRegion": "string"
},
"schema": {
"$ref": "#/components/schemas/RaiseRelocationNoticeBody"
}
},
"application/json": {
"example": {
"destinationRegion": "string",
"effectiveAt": "2026-01-01T00:00:00.0000000+00:00",
"legalBasis": "string",
"operationReference": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"plainLanguageImpact": "string",
"sourceRegion": "string"
},
"schema": {
"$ref": "#/components/schemas/RaiseRelocationNoticeBody"
}
},
"text/json": {
"example": {
"destinationRegion": "string",
"effectiveAt": "2026-01-01T00:00:00.0000000+00:00",
"legalBasis": "string",
"operationReference": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"plainLanguageImpact": "string",
"sourceRegion": "string"
},
"schema": {
"$ref": "#/components/schemas/RaiseRelocationNoticeBody"
}
}
}
},
"responses": {
"202": {
"content": {
"application/json": {
"example": {
"destinationRegion": "string",
"effectiveAt": "2026-01-01T00:00:00.0000000+00:00",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legalBasis": "string",
"operationReference": "string",
"organizationId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"plainLanguageImpact": "string",
"raisedAt": "2026-01-01T00:00:00.0000000+00:00",
"raisedBy": "string",
"respondedAt": "2026-01-01T00:00:00.0000000+00:00",
"respondedBy": "string",
"response": "string",
"responseComment": "string",
"sourceRegion": "string",
"status": "string"
},
"schema": {
"$ref": "#/components/schemas/OrgResidencyRelocationNoticeDto"
}
}
},
"description": "Accepted"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "Raises a pre-cutover residency relocation notice for one organisation — the operator write\r\nthat opens the organisation-facing half of the residency-migration seam.",
"tags": [
"Residency"
]
}
},
"/api/v1/residency/report": {
"get": {
"operationId": "Residency_GetReport",
"parameters": [
{
"in": "query",
"name": "from",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "to",
"schema": {
"format": "date-time",
"type": "string"
}
},
{
"in": "query",
"name": "sourceSovereign",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "targetSovereign",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "legalBasis",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "format",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"in": "query",
"name": "pageSize",
"schema": {
"default": 50,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"description": "OK"
}
},
"summary": "S-03.01 — cross-border residency report. Returns a metadata-only projection of cross-border\r\ntransfer decisions, filterable by date range, sovereign pair, legal basis and outcome\r\nstatus. `format=json` (default) returns a keyset page; `format=csv|pdf` streams the\r\nfull filtered set as a downloadable evidence artifact.",
"tags": [
"Residency"
]
}
},
"/api/v1/sovereignty/cross-boundary-replication/attest": {
"post": {
"operationId": "Sovereignty_AttestCrossBoundaryReplication",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"backupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"encryptionKeyId": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestedBy": "string",
"sourceRegion": "string",
"sovereignKmsRegion": "string",
"targetRegion": "string"
},
"schema": {
"$ref": "#/components/schemas/AttestCrossBoundaryReplicationRequest"
}
},
"application/json": {
"example": {
"backupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"encryptionKeyId": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestedBy": "string",
"sourceRegion": "string",
"sovereignKmsRegion": "string",
"targetRegion": "string"
},
"schema": {
"$ref": "#/components/schemas/AttestCrossBoundaryReplicationRequest"
}
},
"text/json": {
"example": {
"backupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"encryptionKeyId": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"requestedBy": "string",
"sourceRegion": "string",
"sovereignKmsRegion": "string",
"targetRegion": "string"
},
"schema": {
"$ref": "#/components/schemas/AttestCrossBoundaryReplicationRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"algorithm": "string",
"backupId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"contentHash": "string",
"encryptionKeyId": "string",
"foreignRegion": "string",
"keyNeverLeftSovereignKms": false,
"signature": "string",
"signedAt": "2026-01-01T00:00:00.0000000+00:00",
"sovereignKmsRegion": "string",
"statement": "string"
},
"schema": {
"$ref": "#/components/schemas/KeySovereigntyAttestation"
}
}
},
"description": "OK"
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
}
},
"summary": "Records a cross-boundary encrypted-backup geo-replication and returns a signed\r\nCC-090 key-sovereignty attestation.",
"tags": [
"Sovereignty"
]
}
},
"/api/v1/users": {
"get": {
"operationId": "Users_ListUsers",
"parameters": [
{
"description": "Optional filter by active status (\"active\" or \"inactive\").",
"in": "query",
"name": "status",
"schema": {
"type": "string"
}
},
{
"description": "Optional search term to match against name or email.",
"in": "query",
"name": "search",
"schema": {
"type": "string"
}
},
{
"description": "Page number (1-based, defaults to 1).",
"in": "query",
"name": "page",
"schema": {
"default": 1,
"format": "int32",
"type": "integer"
}
},
{
"description": "Items per page (defaults to 50, capped at 100).",
"in": "query",
"name": "pageSize",
"schema": {
"default": 50,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Users retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists users with optional status and search filters.",
"tags": [
"Users"
]
},
"post": {
"operationId": "Users_CreateUser",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"email": "string",
"fullName": "string",
"role": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateUserRequest"
}
},
"application/json": {
"example": {
"email": "string",
"fullName": "string",
"role": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateUserRequest"
}
},
"text/json": {
"example": {
"email": "string",
"fullName": "string",
"role": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateUserRequest"
}
}
},
"description": "The create user request."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "User created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Creates a new user.",
"tags": [
"Users"
]
}
},
"/api/v1/users/search": {
"get": {
"operationId": "Users_SearchUsers",
"parameters": [
{
"description": "The search term to match against email, first name, or last name.",
"in": "query",
"name": "searchTerm",
"schema": {
"type": "string"
}
},
{
"description": "1-based page index (defaults to 1).",
"in": "query",
"name": "page",
"schema": {
"default": 1,
"format": "int32",
"type": "integer"
}
},
{
"description": "Items per page (defaults to 50, capped server-side at 100).",
"in": "query",
"name": "pageSize",
"schema": {
"default": 50,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/UserSummaryResponse"
},
"type": "array"
}
}
},
"description": "Users retrieved successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid search term."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Searches for users by email or name within the current instance.\r\nOnly returns active, email-verified users.",
"tags": [
"Users"
]
}
},
"/api/v1/users/{id}": {
"get": {
"operationId": "Users_GetUserProfile",
"parameters": [
{
"description": "The user ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"email": "string",
"emailVerified": false,
"firstName": "string",
"fullName": "string",
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isActive": false,
"lastName": "string",
"roles": []
},
"schema": {
"$ref": "#/components/schemas/UserSummaryResponse"
}
}
},
"description": "User profile retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found or not accessible."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a user's profile by their unique identifier.\r\nOnly returns profiles for active, email-verified users in the same instance.",
"tags": [
"Users"
]
}
},
"/api/v1/users/{id}/activate": {
"post": {
"operationId": "Users_ActivateUser",
"parameters": [
{
"description": "The user ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "User activated successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Activates a user account.",
"tags": [
"Users"
]
}
},
"/api/v1/users/{id}/audit": {
"get": {
"operationId": "Users_GetUserAudit",
"parameters": [
{
"description": "The user ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Page number (1-based, defaults to 1).",
"in": "query",
"name": "page",
"schema": {
"default": 1,
"format": "int32",
"type": "integer"
}
},
{
"description": "Number of items per page (defaults to 20).",
"in": "query",
"name": "pageSize",
"schema": {
"default": 20,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Audit entries retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves audit log entries for a user.",
"tags": [
"Users"
]
}
},
"/api/v1/users/{id}/permissions": {
"get": {
"operationId": "Users_GetUserPermissions",
"parameters": [
{
"description": "The user ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Permissions retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves permissions for a user based on their assigned roles.",
"tags": [
"Users"
]
}
},
"/api/v1/users/{id}/roles": {
"get": {
"operationId": "Users_GetUserRoles",
"parameters": [
{
"description": "The user ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Roles retrieved successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves roles assigned to a user.",
"tags": [
"Users"
]
},
"post": {
"operationId": "Users_AssignUserRole",
"parameters": [
{
"description": "The user ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"instanceScope": "string",
"roleId": "string"
},
"schema": {
"$ref": "#/components/schemas/AssignRoleRequest"
}
},
"application/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"instanceScope": "string",
"roleId": "string"
},
"schema": {
"$ref": "#/components/schemas/AssignRoleRequest"
}
},
"text/json": {
"example": {
"expiresAt": "2026-01-01T00:00:00.0000000+00:00",
"instanceScope": "string",
"roleId": "string"
},
"schema": {
"$ref": "#/components/schemas/AssignRoleRequest"
}
}
},
"description": "The role assignment request."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Role assigned successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Assigns a role to a user.",
"tags": [
"Users"
]
}
},
"/api/v1/users/{id}/roles/{roleId}": {
"delete": {
"operationId": "Users_RemoveUserRole",
"parameters": [
{
"description": "The user ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "The role ID to remove.",
"in": "path",
"name": "roleId",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "Role removed successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Bad Request"
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Removes a role from a user.",
"tags": [
"Users"
]
}
},
"/api/v1/users/{id}/suspend": {
"post": {
"operationId": "Users_SuspendUser",
"parameters": [
{
"description": "The user ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {}
}
},
"description": "User suspended successfully."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "User not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Suspends a user account.",
"tags": [
"Users"
]
}
},
"/api/v1/vaults": {
"post": {
"operationId": "Vaults_CreateVault",
"requestBody": {
"content": {
"application/*+json": {
"example": {
"authenticationTag": "string",
"autoDeleteDays": 0,
"autoDeleteEnabled": false,
"description": "string",
"initializationVector": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"keyId": "string",
"maxDocuments": 0,
"maxSizeBytes": 0,
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"salt": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateVaultCommand"
}
},
"application/json": {
"example": {
"authenticationTag": "string",
"autoDeleteDays": 0,
"autoDeleteEnabled": false,
"description": "string",
"initializationVector": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"keyId": "string",
"maxDocuments": 0,
"maxSizeBytes": 0,
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"salt": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateVaultCommand"
}
},
"text/json": {
"example": {
"authenticationTag": "string",
"autoDeleteDays": 0,
"autoDeleteEnabled": false,
"description": "string",
"initializationVector": "string",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"keyId": "string",
"maxDocuments": 0,
"maxSizeBytes": 0,
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"salt": "string"
},
"schema": {
"$ref": "#/components/schemas/CreateVaultCommand"
}
}
},
"description": "The create vault command."
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"format": "uuid",
"type": "string"
}
}
},
"description": "Vault created successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden"
},
"500": {
"description": "Internal server error."
}
},
"summary": "Creates a new vault for secure data storage.",
"tags": [
"Vaults"
]
}
},
"/api/v1/vaults/instance/{instanceId}": {
"get": {
"operationId": "Vaults_GetVaultsByInstance",
"parameters": [
{
"description": "The instance ID.",
"in": "path",
"name": "instanceId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Whether to include archived vaults (default: false).",
"in": "query",
"name": "includeArchived",
"schema": {
"default": false,
"type": "boolean"
}
},
{
"description": "Opaque continuation cursor from a prior page's NextCursor, or null for the first slice.",
"in": "query",
"name": "cursor",
"schema": {
"type": "string"
}
},
{
"description": "Requested slice size; clamped to [1, 500] (DAT-006).",
"in": "query",
"name": "pageSize",
"schema": {
"default": 100,
"format": "int32",
"type": "integer"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"hasMore": false,
"items": [],
"nextCursor": "string",
"pageSize": 0,
"previousCursor": "string"
},
"schema": {
"$ref": "#/components/schemas/VaultProvisioningRecordCursorResult"
}
}
},
"description": "Vaults retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user does not have admin privileges."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists all vaults for a specific instance.\r\nRequires InstanceAdmin or GlobalAdmin role.",
"tags": [
"Vaults"
]
}
},
"/api/v1/vaults/owner/{ownerId}": {
"get": {
"description": "Authorization boundary (debt-2026-06-28-254): the administrator cross-owner\r\nenumeration is instance-scoped by design — bounded to the caller's own\r\n`InstanceId`, pushed into the SQL predicate below, so cross-instance vault\r\nmetadata is never loaded. There is no org-membership predicate within an instance,\r\nwhich is why the administrator here is the INSTANCE administrator: a sovereign\r\ninstance hosts many organisations' members, so an organisation's administrator\r\nmust not inherit an instance-wide read (#22641; the gate used to name\r\n\"OrganizationAdmin\", a role no token carries). Should organisation administrators\r\nneed this read, an explicit org-membership predicate must be added to\r\nEssence.Core.Instance.Application.Queries.ListVaultsByOwnerQuery first — see the debt for the product decision.",
"operationId": "Vaults_GetVaultsByOwner",
"parameters": [
{
"description": "The owner user ID.",
"in": "path",
"name": "ownerId",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
},
{
"description": "Whether to include archived vaults (default: false).",
"in": "query",
"name": "includeArchived",
"schema": {
"default": false,
"type": "boolean"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/VaultProvisioningRecord"
},
"type": "array"
}
}
},
"description": "Vaults retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user cannot access another user's vaults."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Lists all vaults owned by a specific user.",
"tags": [
"Vaults"
]
}
},
"/api/v1/vaults/{id}": {
"get": {
"operationId": "Vaults_GetVaultById",
"parameters": [
{
"description": "The vault ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"example": {
"archivedAt": "2026-01-01T00:00:00.0000000+00:00",
"createdAt": "2026-01-01T00:00:00.0000000+00:00",
"createdBy": "string",
"deletedAt": "2026-01-01T00:00:00.0000000+00:00",
"deletedBy": "string",
"description": "string",
"documentCount": 0,
"domainEvents": [],
"hasDomainEvents": false,
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"instanceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"isActive": false,
"isDeleted": false,
"lastAccessedAt": "2026-01-01T00:00:00.0000000+00:00",
"maxDocuments": 0,
"maxSizeBytes": 0,
"metadata": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"rowVersion": "string",
"totalSizeBytes": 0,
"updatedAt": "2026-01-01T00:00:00.0000000+00:00",
"updatedBy": "string"
},
"schema": {
"$ref": "#/components/schemas/VaultProvisioningRecord"
}
}
},
"description": "Vault retrieved successfully."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault not found, or the caller is not the owner (existence is not\r\n disclosed to non-owners — debt-2026-06-02-1365)."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Retrieves a vault by its unique identifier.",
"tags": [
"Vaults"
]
},
"put": {
"operationId": "Vaults_UpdateVault",
"parameters": [
{
"description": "The vault ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"description": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateVaultCommand"
}
},
"application/json": {
"example": {
"description": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateVaultCommand"
}
},
"text/json": {
"example": {
"description": "string",
"name": "string",
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateVaultCommand"
}
}
},
"description": "The update vault command."
},
"responses": {
"204": {
"description": "Vault updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user does not own this vault."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates vault name and description.",
"tags": [
"Vaults"
]
}
},
"/api/v1/vaults/{id}/archive": {
"post": {
"operationId": "Vaults_ArchiveVault",
"parameters": [
{
"description": "The vault ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Vault archived successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault is already archived."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user does not own this vault."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Archives a vault (soft delete).\r\nArchived vaults cannot have documents added but existing data is preserved.",
"tags": [
"Vaults"
]
}
},
"/api/v1/vaults/{id}/limits": {
"put": {
"operationId": "Vaults_UpdateVaultLimits",
"parameters": [
{
"description": "The vault ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"requestBody": {
"content": {
"application/*+json": {
"example": {
"maxDocuments": 0,
"maxSizeBytes": 0,
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateVaultLimitsCommand"
}
},
"application/json": {
"example": {
"maxDocuments": 0,
"maxSizeBytes": 0,
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateVaultLimitsCommand"
}
},
"text/json": {
"example": {
"maxDocuments": 0,
"maxSizeBytes": 0,
"ownerId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"vaultId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
},
"schema": {
"$ref": "#/components/schemas/UpdateVaultLimitsCommand"
}
}
},
"description": "The update vault limits command."
},
"responses": {
"204": {
"description": "Vault limits updated successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Invalid request data - limits exceed current usage."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user does not own this vault."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Updates vault storage and document limits.",
"tags": [
"Vaults"
]
}
},
"/api/v1/vaults/{id}/restore": {
"post": {
"operationId": "Vaults_RestoreVault",
"parameters": [
{
"description": "The vault ID.",
"in": "path",
"name": "id",
"required": true,
"schema": {
"format": "uuid",
"type": "string"
}
}
],
"responses": {
"204": {
"description": "Vault restored successfully."
},
"400": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault is not archived."
},
"401": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Unauthorized - user not authenticated."
},
"403": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Forbidden - user does not own this vault."
},
"404": {
"content": {
"application/json": {
"example": {
"detail": "string",
"instance": "string",
"status": 0,
"title": "string",
"type": "string"
},
"schema": {
"$ref": "#/components/schemas/ProblemDetails"
}
}
},
"description": "Vault not found."
},
"500": {
"description": "Internal server error."
}
},
"summary": "Restores an archived vault.",
"tags": [
"Vaults"
]
}
}
},
"security": [
{
"Bearer": []
}
],
"tags": [
{
"description": "Admin-only test-fixture organisation provisioning surface (§9a —\r\nprovisioning entry point #3: \"Create organisation (+ seed an org-admin\r\nmember)\"). `OrganizationInstancesController.CreateOrganizationInstance`\r\nis deliberately locked to `OrgProvisioningScope` (2.6/D4 — creation\r\nmust go through the EPIC 43 KYB onboarding workflow); its own comment\r\nrecords that the ONLY sanctioned bypass is `OperatorOrganizationSeeder`\r\ndispatching Essence.Core.Instance.Application.Commands.CreateOrganizationInstanceCommand in-process via\r\nMediatR.IMediator. This controller is that same sanctioned bypass,\r\ngeneralised to an admin-gated HTTP surface for QA fixtures instead of a\r\nstartup-only seeder — no new domain logic, same command/handler.",
"name": "AdminOrganizations"
},
{
"description": "Controller for certificate management operations.\r\nProvides endpoints for certificate issuance, revocation, and querying.",
"name": "Certificates"
},
{
"description": "API controller for commercial operations including subscriptions, licenses, invoices, usage, and pricing plans.\r\nProxies real data from Billing, License, and Partner services.",
"name": "Commercial"
},
{
"description": "Read-only compliance overview surface for the admin portal. The full\r\nassessment/audit/evidence persistence model belongs to EPIC 12\r\n(Security Certifications & Audit) and is not yet in place — until\r\nthat lands these endpoints return honest empty projections rather\r\nthan synthesised assessment scores or fabricated IP addresses\r\n(resolves debt-2026-05-17-084).",
"name": "Compliance"
},
{
"description": "Presented-credential lockdown API (stolen-wallet journey\r\n`stolen-wallet-bulk-credential-reissue-and-fraud-lockdown`). Lets an\r\nauthenticated user flag a presented physical credential compromised so\r\na thief who took their wallet cannot re-present it. Flagging emits\r\n`PresentedCredentialCompromisedEvent` (outbound relying-party notification —\r\nEPIC 66 — + incident-audit anchor — EPIC 4) and `CredentialRevokedEvent`\r\n(FR-03.014a/021) over the transactional outbox.\r\n \r\n\nZero-knowledge: the request carries opaque references and the lawful-basis /\r\nconsent record reference only — never user-identity PII or credential material.",
"name": "CredentialLockdown"
},
{
"description": "EPIC-3 producer surface for the cross-border credential-presentation journeys, rooted at\r\n`/api/v1/cross-border` (the routing convention the essence-web cross-border engine client\r\ntargets). This controller backs the `cross-border-driving-licence-recognition` journey's\r\nheld-driving-entitlement seam:\r\n- `GET /driving-entitlement` — the driver-side presentation screen's live read of the\r\n holder's held entitlement (previously 404'd — the SPA feature was non-functional through the\r\n UI, debt-2026-07-19-421 / ESS-QA-009);
- `POST /driving-entitlement` — the wallet / credential-import population path that\r\n registers or replaces the holder's held entitlement (EPIC 16/24 caller).
\n\r\nAuthorisation: authenticated users only (SEC-001/002). The entitlement is always the caller's\r\nown — the owning subject is taken from the JWT claim, never a body-supplied id. A read that names\r\na `userId` other than the caller's subject is refused (`403`, IDOR prevention). The\r\nresponse is a `{ data: … }` envelope (the cross-border client unwraps `data.data`).\r\n\nZero-knowledge (ZK-ARCH-001): every field is an opaque holder reference, a jurisdiction /\r\ncategory / restriction code, or an ISO date — never the holder's name, licence number, or\r\nphotograph.",
"name": "CrossBorder"
},
{
"description": "Cross-region rolling releases of the Global control plane (FR-03.044, #23205).\r\n \r\n\n\r\nThe deploy path opens a rollout, rolls each region in order and reports the region's post-roll\r\nhealth outcome here. The guard is server-side: an unhealthy outcome does not roll the region and\r\ndrives the rollout into `RolloutHaltedAuto` — the populated \"rollout halted (auto)\" operator\r\nstate — committing `GlobalRolloutHaltedIntegrationEvent` onto the outbox with the transition\r\n(EVT-003). Operators read the halted state and its reason here and resume, abandon or keep it\r\nhalted to investigate. A second rollout cannot start while one is live.\r\n\n\r\nMounted under both prefixes the Global gateways already send to this service:\r\n`/api/v1/instances/global/rollouts` (api-gateway) and `/api/v1/global-instances/rollouts`\r\n(platformadmin-gateway, the admin console's).\r\n",
"name": "CrossRegionRollouts"
},
{
"description": "The operator's queue for dedicated environments, and the callback that finishes them\r\n(Phase 4.3).\r\n \r\n\nWhy a human is in this loop. Nothing on this platform builds dedicated infrastructure —\r\n`IInstanceOperator.ReconcileAsync` has no production caller, and automated per-platform\r\nmaterialisers are their own spec (Du Sovereign HyperCloud needs commercial and technical\r\nonboarding before any code at all). An operator was already doing this work. What was missing is\r\nthat the platform did not know: provisioning invented a connection string and marked the instance\r\nActive, so the customer was told their dedicated instance was live while it did not exist.\r\n\n\r\nProvisioning now pauses at `AwaitingMaterialisation` and waits here. This surface is the\r\nhonest version of what already happened.\r\n",
"name": "DedicatedMaterialisations"
},
{
"description": "API controller for managing developer identifiers.\r\nHandles listing, creation, suspension, and revocation of developer IDs.",
"name": "DeveloperIds"
},
{
"description": "API controller for instance discovery and routing operations.\r\nProvides endpoints for discovering optimal instances, computing routes, health checks, and latency measurements.\r\nSupports 1M queries/second through distributed caching with 5-minute TTL.",
"name": "Discovery"
},
{
"description": "API controller for DNS zone and record management operations.\r\nHandles creation, retrieval, updating, deletion, and verification of DNS resources.",
"name": "Dns"
},
{
"description": "API controller for encrypted document-reference management operations.\r\nThese endpoints manage encrypted document references and metadata (the `VaultDocumentRef`\r\nconcept) — pointers to client-side-encrypted blobs and their metadata — never plaintext\r\ndocument content. \"Document\" throughout this controller therefore means that encrypted\r\nreference/metadata record, consistent with the 'Ref' concept used by the layers below.\r\nAll operations require authenticated users and enforce vault owner-based authorization.\r\nZero-knowledge architecture: all document content is encrypted client-side and is never\r\nseen by the server (debt-2026-06-23-255).",
"name": "Documents"
},
{
"description": "Serves the sovereign edge's per-org TLS route table (EPIC 3 FR-03.060, debt-2026-08-11-051).\r\n \r\n\n\r\nConsumed by Traefik's HTTP provider on each sovereign box, which polls this endpoint and applies\r\nthe returned dynamic configuration. Each entry is one verified, entitled custom domain, carrying\r\nan ACME `certResolver` — so a domain that passes DNS-ownership verification becomes\r\nreachable over HTTPS without an operator touching a certificate, and one that is unbound (or\r\nwhose subscription lapses) disappears from the table and stops being served.\r\n",
"name": "EdgeRoutes"
},
{
"description": "API controller for global instance management operations.\r\nProvides endpoints for creating, configuring, and managing the global instance.\r\n \r\n\nRouting (debt-2026-08-13-039). The authoritative contract\r\n(`docs/epics/epic-3-multi-instance/api-contracts.md` §1) specifies\r\n`/api/v1/instances/global[/{id},/health,/suspend,/resume]`. The implementation had drifted\r\nto `api/v{version}/global-instances` only — a path the ApiGateway does not route (it routes\r\n`/api/{version}/instances/**`), so global-instance management was unreachable through the\r\ngateway under either path. The contract path is now served as the primary route, which\r\nthe existing gateway rule already covers; the historical `global-instances` path is\r\nretained as a secondary route so any in-flight internal caller keeps working.\r\n",
"name": "GlobalInstances"
},
{
"description": "The BRP → eVisa immigration-status seam, rooted at\r\n`/api/v1/cross-border/immigration-status` (journey\r\n`brp-to-evisa-immigration-status-transition`, EPIC 24 producer surface).\r\n \r\n\n\r\nThe route prefix is deliberate. `/api/v1/cross-border/{**catch-all}` is already routed at\r\nthe API gateway to `instance-service`, which is what makes every endpoint below reachable\r\nfrom both SPAs on day one — a sibling immigration surface at `/api/v1/uk-gov/*` has no\r\ngateway route at all and is therefore unreachable however complete its code is.\r\n\nMigrant endpoints (Steps 1–4) are scoped to the caller's own JWT subject; no body or query\r\nparameter names a user, so there is no id to spoof. Verifier endpoints are scoped to the\r\ncaller's organisation claim, which is why a verifier can redeem a stranger's code — that is what\r\na share code is for — but can only ever see and configure their own organisation's records.\r\n\nWire envelope: these endpoints return their DTOs bare (no `{ data: … }`\r\nwrapper). The immigration-status client unwraps `response.data` directly, unlike the\r\ncross-border engine client on the same prefix which unwraps `data.data`.\r\n\nZero-knowledge (ZK-ARCH-001): nothing here accepts a BRP number, a date of birth, a\r\nname or a nationality. The link step takes a trailing mask computed on the device; an issued\r\nshare code is returned once and stored only as a SHA-256 fingerprint plus a four-character\r\nmask.",
"name": "ImmigrationStatus"
},
{
"description": "Cross-type instance lifecycle facade (debt-2026-06-21-1063): the single\r\ntype-agnostic entry point that lists, activates, suspends, and terminates\r\ninstances regardless of whether they are Global, Sovereign, or Organization. It\r\ndispatches by looking the instance up across all three aggregate tables, so it sits\r\nabove — and deliberately overlaps — the per-type controllers\r\n(Essence.Core.Instance.Api.Controllers.GlobalInstancesController, Essence.Core.Instance.Api.Controllers.SovereignInstancesController,\r\nEssence.Core.Instance.Api.Controllers.OrganizationInstancesController) and the read-only\r\nEssence.Core.Instance.Api.Controllers.InstanceRegistryController. Use the per-type controllers for\r\ntype-specific operations — creation included: `POST /instances/global` belongs to\r\nEssence.Core.Instance.Api.Controllers.GlobalInstancesController alone, because a second action on the same template\r\nmade every create an `AmbiguousMatchException` (#14190) — and use this facade for the\r\ncommon lifecycle verbs.\r\nWrite-side actions (activate / suspend / terminate) require GlobalAdmin;\r\nread-side actions accept InstanceAdmin so per-instance operators can see their own\r\ninstance metadata.",
"name": "InstanceLifecycle"
},
{
"description": "API controller for instance registry operations.\r\nProvides endpoints for instance registration, discovery, and registry management.",
"name": "InstanceRegistry"
},
{
"description": "Internal API controller for secure cross-instance messaging operations.\r\nReceives and processes messages from other instances through Istio service\r\nmesh with mTLS. The Essence.Core.Instance.Api.Authorization.Policies.PolicyNames.InstanceServiceAccount policy\r\nrequires the caller's JWT to carry the `InstanceServiceAccount` role\r\n(or GlobalAdmin for break-glass); the body-supplied\r\nEssence.Core.Instance.Api.Controllers.ReceiveMessageRequest.SourceInstanceId is reconciled against\r\nthe caller's `InstanceId` claim before any message is admitted.",
"name": "InternalMessaging"
},
{
"description": "Joint-venture co-ownership agreements — the front door for a tenant owned by two co-equal\r\nparents rather than by one applicant (EPIC 3, tl:journey-test #6421).\r\n \r\n\n\r\nBefore this controller, EPIC 3 could express exactly two organisation structures: one entity\r\nonboarding on its own, and a parent that will onboard subsidiaries. A joint venture is neither,\r\nso a sponsor had to mis-declare their legal structure to get in at all — and then found no\r\ncounterpart admin five phases later.\r\n\nScoping (SEC-002). Every action resolves the acting organisation from the caller's\r\n`org_id` claim. The proposing parent is never taken from the request body, and the\r\naggregate refuses an approval cast by the proposing parent — an organisation cannot be bound\r\ninto co-ownership of a tenant by the other party's say-so.\r\n\nMetadata only: organisation ids and display names, an enum, percentages, booleans (ZK-ARCH-001).",
"name": "JointVentures"
},
{
"description": "API controller for cross-instance messaging operations.\r\nProvides secure endpoints for sending, receiving, and managing encrypted messages between users.\r\nAll operations require authenticated users and enforce sender/recipient-based authorization.\r\nZero-knowledge architecture: all message content is encrypted client-side.",
"name": "Messages"
},
{
"description": "API controller for platform monitoring dashboard operations.\r\nProvides real-time instance health data and deterministic seed data for alerts,\r\nincidents, SLAs, and metrics until dedicated domain layers are implemented.\r\n \r\nThis controller is a thin HTTP translation layer (SRP, debt-2026-06-28-698): the database\r\nprojection logic lives in Essence.Core.Instance.Application.Services.Monitoring.IMonitoringProjectionService and the deterministic\r\nseed/metric generation lives in Essence.Core.Instance.Application.Services.Monitoring.IMonitoringSeedDataProvider. Operator status\r\nactions are recorded by Essence.Core.Instance.Application.Services.IMonitoringActionStateStore. The controller orchestrates\r\nthese collaborators and shapes the HTTP responses; it owns no data generation and no\r\n`InstanceDbContext` dependency.",
"name": "Monitoring"
},
{
"description": "API controller for organization settings, security configuration, and module management.\r\nSupports read and write operations with in-memory state persistence within the process lifetime.",
"name": "Organization"
},
{
"description": "API controller for organization instance management operations.\r\nHandles creation, retrieval, and listing of organization-level instances.",
"name": "OrganizationInstances"
},
{
"description": "The organisation-facing half of the residency-migration seam: where does MY organisation's data\r\nlive, since when, on what legal basis, and is it about to move?\r\n \r\n\n\r\nEvery other residency endpoint on this service is platform-operator scoped, and the S-03.01\r\nreport reachable from Essence.Core.Instance.Api.Controllers.ResidencyController is a cross-border transfer AUDIT\r\nEXPORT — a different artefact for a different reader. An org administrator whose instance was\r\nbeing re-homed previously had no surface at all. This controller closes that gap with three\r\nreads (status, notice history, evidence package) and one write (the organisation's response to\r\na pre-cutover notice).\r\n\nScoping (SEC-002). The route carries an organisation id, but it is NEVER trusted for a\r\ntenant-scoped caller: the platform superuser may read any\r\norganisation, and every other caller is bound to their own `org_id` claim, with a missing\r\nor self-conflicting claim refused outright. This is the same guard\r\n`CommercialController.TryResolveScopedOrganizationId` applies, for the same A01-IDOR\r\nreason.\r\n\nMetadata only — regions, dates, legal basis, impact prose. No raw PII (ZK-ARCH-001).",
"name": "OrgResidency"
},
{
"description": "API controller for instance registration workflow operations.\r\nHandles sovereign-to-global and organization-to-sovereign registration requests,\r\nincluding approval, rejection, completion, and revocation.",
"name": "Registration"
},
{
"description": "Global registry maintenance surface — the authoritative record of WHERE each user's data lives\r\n(their home Sovereign instance). CREATE is event-driven (see UserCreatedRegistryConsumer); this\r\ncontroller exposes the UPDATE (re-home) and DELETE (erasure) triggers plus a location lookup, for\r\nthe Global orchestrators that perform those lifecycle operations. Each write is a single-database\r\ntransaction. Admin/service authorised — never a user-facing surface. Location metadata only, no PII.",
"name": "Registry"
},
{
"description": "EPIC 24's renunciation front door and teardown orchestration, rooted at\r\n`/api/v1/cross-border/renunciation` (journey\r\n`citizenship-renunciation-credential-teardown`, gaps G1/G2/G6 — debt-2026-06-06-553 / -549 /\r\n-551).",
"name": "RenunciationTeardown"
},
{
"description": "EPIC-3-owned producer surface for the data-residency consumer seams S-03.01 (cross-border\r\nresidency report) and S-03.02 (cross-border approval queue). EPIC 3 provides these REST\r\nendpoints; the consuming UI is rendered by EPIC 11 (Regulatory Compliance) / EPIC 7 (Org\r\nDashboard) / EPIC 48 (Platform Admin). All projections are metadata-only — jurisdiction codes,\r\nlegal basis, outcome, timestamp — and never expose raw PII (ZK-ARCH-001). Approval outcomes are\r\nobserved exclusively through this read/write seam; there is no cross-border decision event\r\n(EVT-002; debt-2026-06-14-391/393). Resolves debt-2026-06-22-077.",
"name": "Residency"
},
{
"description": "Service-account read of a returning-national intake for the EPIC 9 bootstrap gate (#14018).\r\n \r\n\n\r\nThe gate must decide on what the platform recorded at intake, not on what the caller sends.\r\nThis route hands the token authority exactly that: the intake's corridor origin and the basis\r\ncredential's issuer, scheme and assurance level, for an intake the named subject opened.\r\n\n\r\nIt is service-principal only (`EssenceServicePolicies.ServiceInternal`), takes\r\nthe subject as input rather than revealing one, and answers 404 for an intake that is missing\r\nand for one that belongs to someone else alike.\r\n",
"name": "ReturningNationalIntakeFacts"
},
{
"description": "Who operates a sovereign instance, under which law, and what it commits to\r\n(EPIC 107 FR-HMF.002 and FR-HMF.024), rooted at\r\n`/api/v1/instances/sovereign/{id}/operating-terms`.",
"name": "SovereignInstanceOperatingTerms"
},
{
"description": "API controller for sovereign instance management operations.\r\nHandles region-specific instances with data residency enforcement.",
"name": "SovereignInstances"
},
{
"description": "Provider surface for the CC-090 / FR-69.027 cross-boundary key-sovereignty contract.\r\nThe Backup & DR service (EPIC 69) calls this on activation of an international\r\nencrypted-backup geo-replication so the ciphertext movement is durably audited and a\r\nsigned key-sovereignty attestation is issued (proving the encryption key never left the\r\nsovereign KMS region). Zero-knowledge: only regions and key identifiers cross\r\nthis boundary — never key material or plaintext.",
"name": "Sovereignty"
},
{
"description": "Sponsored organisation resolution (FR-ST.030 / AC-21 / AC-19) — programme workstream 2.7b.\r\n \r\n\n\r\nSupersedes `/api/v1/instances/provision-or-link`, which Supplier Trust called and NO SERVER\r\nEVER IMPLEMENTED. In its absence Supplier Trust resolved sponsorships against its own table, so\r\n\"provisioned\" meant a row asserting an instance nobody had minted.\r\n\nThe response is AC-19-neutral by construction. It carries an opaque reference and a state\r\nidentical whether the organisation was freshly provisioned or already an Essence customer. It\r\ndeliberately returns no organisation id: a sponsor who could correlate one across invitations\r\nwould learn which of their suppliers are already Essence customers — commercially valuable\r\ninformation the supplier never agreed to share, harvestable by inviting any company the sponsor\r\nis merely curious about.\r\n",
"name": "SponsoredResolutions"
},
{
"description": "The DATA SUBJECT's cross-border approval path (FR-03.029a subject-origination extension).\r\n \r\n\nEssence.Core.Instance.Api.Controllers.ResidencyController carries a class-level\r\n`[Authorize(Policy = InstanceAdminFor)]`, and its `POST /residency/approvals` action\r\nadditionally requires InstanceAdmin/OrganizationAdmin/PlatformAdmin/GlobalAdmin — an\r\nintentional SEC-002 origination gate. ASP.NET policies AND-combine rather than override, so a\r\nlooser action on that controller is impossible: an individual emigrant holds none of those\r\nroles and could therefore neither raise a request for their own transfer nor read its status.\r\nThe one forward path out of an inadequate corridor was closed to the very person whose data it\r\nis. This controller is a separate surface with its own plain-authenticated policy so the gate\r\non the authority-side seam stays exactly as strict as it was.\r\n\nWhat this does NOT do. Origination and read only. The approve / deny / expire decision\r\nremains solely on Essence.Core.Instance.Api.Controllers.ResidencyController with the approval authority — a data\r\nsubject can ask, and can watch, but cannot decide.\r\n\nScoping (SEC-002). The subject id is resolved server-side from the caller's token and is\r\nnever accepted from a route, query or body. Reads return only requests this subject raised\r\nthrough this path (`Origin = DataSubject` AND a matching requester), and a request\r\nbelonging to somebody else is reported as absent rather than forbidden so the endpoint cannot\r\nbe used to probe for other people's requests.\r\n",
"name": "SubjectResidency"
},
{
"description": "Supervised (minor) instance provisioning API\r\n(journey `minor-supervised-account-provisioning-parental-controls`). Lets a\r\nverifying guardian / supervising admin provision supervised instances for minors\r\nunder their care, each carrying a durable, auditable age-assurance attribute, and\r\nlist their roster for the supervised-accounts console.\r\n \r\n\nThree seams:- `POST /api/v1/instances/supervised` — the wizard's Step-2 per-child provision.
- `POST /api/v1/instances/supervised/batch` — the supervising-admin cohort\r\n path: one control template applied across a whole roster in one atomic call\r\n (debt-2026-07-09-038).
- `GET /api/v1/instances/supervised` — the roster listing, scoped to the\r\n authenticated guardian (it takes no guardian id from the request).
\nZero-knowledge: requests and responses carry opaque ids and the age-assurance\r\nmethod + level only — never the minor's identity PII.",
"name": "SupervisedInstances"
},
{
"description": "API controller for user discovery and management operations.\r\nRead-side actions require InstanceAdmin and filter results to the caller's\r\nown instance; write-side actions that touch role membership require\r\nGlobalAdmin.",
"name": "Users"
},
{
"description": "Self-service read of the caller's cross-region vault registry (multi-region Phase 2a, task 6)\r\n— sibling of Essence.Core.Instance.Api.Controllers.InstanceRegistryController under the same\r\n`api/v{version}/registry` route base. Deliberately a separate controller: unlike\r\nEssence.Core.Instance.Api.Controllers.InstanceRegistryController (operator/admin surface,\r\n`[Authorize(Policy = PolicyNames.InstanceAdmin)]`), this endpoint is user-facing — any\r\nauthenticated user reads their OWN rows. Stacking a plain `[Authorize]` on a single action\r\nof that controller would not relax its class-level policy (ASP.NET Core combines, never\r\noverrides, multiple `[Authorize]` attributes), so the InstanceAdmin restriction would still\r\napply; a sibling controller with its own `[Authorize]` avoids that trap entirely.",
"name": "UserVaultRegistry"
},
{
"description": "User-facing surface for a vault re-home — moving a person's documents out of a shared\r\nvault into their own sovereign vault (family-separation-shared-vault-split journey,\r\ndebt-2026-07-08-197). Backs the essence-web `VaultRehomeProgressPanel`:\r\n- `POST /` — start a re-home for the caller (the INITIATION seam, debt-2026-08-12-040);
- `GET /status` — the honest progress + per-document breakdown + confirmation;
- `POST /documents/{documentId}/retry` — safe per-document retry of a failed move.
\n\r\nAuthorisation: authenticated users only (SEC-001/002). A re-home job is owned by the person\r\nwhose documents are moving, so every action is additionally guarded by an ownership check\r\nagainst the caller's subject claim — a non-owner sees `404 Not Found` (existence is never\r\ndisclosed to a non-owner, IDOR prevention). The returned DTO is ZK-sanitised (display names +\r\ncoarse states only).\r\n",
"name": "VaultRehome"
},
{
"description": "API controller for vault management operations.\r\nProvides secure endpoints for creating, retrieving, updating, archiving, and restoring vaults.\r\nAll operations require authenticated users and enforce owner-based authorization.",
"name": "Vaults"
}
]
}