8ada623bbf
- Created openapi.yaml (1,621 lines, 46KB) - Documents all API endpoints with full schemas - Authentication, Documents, Governance Services, Audit, Admin - Added OpenAPI download link to api-reference.html - Deployed to production Task 12 (API Documentation) - OpenAPI spec complete
1621 lines
46 KiB
YAML
1621 lines
46 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: Tractatus Framework API
|
|
version: 1.0.0
|
|
description: |
|
|
REST API for the Tractatus Framework - an architectural AI safety framework implementing structural governance for agentic AI systems.
|
|
|
|
**Key Features:**
|
|
- Instruction persistence and classification
|
|
- Cross-reference validation (prevents training pattern override)
|
|
- Boundary enforcement (separates technical from values decisions)
|
|
- Context pressure monitoring (multi-factor session health)
|
|
- Metacognitive verification (AI self-checks for scope creep)
|
|
- Comprehensive audit logging
|
|
|
|
**Security:** Most endpoints require JWT authentication with admin role.
|
|
|
|
**Rate Limiting:**
|
|
- Login endpoint: 5 attempts per 15 minutes per IP
|
|
- General API: 100 requests per 15 minutes per IP
|
|
contact:
|
|
name: Tractatus Framework
|
|
email: john.stroh.nz@pm.me
|
|
url: https://agenticgovernance.digital
|
|
license:
|
|
name: Apache 2.0
|
|
url: https://www.apache.org/licenses/LICENSE-2.0.html
|
|
|
|
servers:
|
|
- url: https://agenticgovernance.digital/api
|
|
description: Production server
|
|
- url: http://localhost:9000/api
|
|
description: Development server
|
|
|
|
tags:
|
|
- name: Authentication
|
|
description: User authentication and session management
|
|
- name: Documents
|
|
description: Framework documentation endpoints
|
|
- name: Governance Services
|
|
description: Core AI safety framework services (admin only)
|
|
- name: Audit
|
|
description: Audit logging and analytics (admin only)
|
|
- name: Admin
|
|
description: System administration and moderation (admin only)
|
|
|
|
paths:
|
|
# ==================== Authentication ====================
|
|
/auth/login:
|
|
post:
|
|
tags:
|
|
- Authentication
|
|
summary: User login
|
|
description: |
|
|
Authenticate with email and password to receive a JWT access token.
|
|
|
|
**Rate Limiting:** 5 attempts per 15 minutes per IP address.
|
|
operationId: login
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- email
|
|
- password
|
|
properties:
|
|
email:
|
|
type: string
|
|
format: email
|
|
example: admin@tractatus.local
|
|
password:
|
|
type: string
|
|
format: password
|
|
example: tractatus2025
|
|
responses:
|
|
'200':
|
|
description: Login successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
token:
|
|
type: string
|
|
example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
|
|
user:
|
|
$ref: '#/components/schemas/User'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'429':
|
|
description: Too many login attempts
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: Too many login attempts from this IP. Please try again in 15 minutes.
|
|
|
|
/auth/me:
|
|
get:
|
|
tags:
|
|
- Authentication
|
|
summary: Get current user
|
|
description: Retrieve the authenticated user's profile information
|
|
operationId: getCurrentUser
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: User profile retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
user:
|
|
$ref: '#/components/schemas/User'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
|
|
/auth/logout:
|
|
post:
|
|
tags:
|
|
- Authentication
|
|
summary: User logout
|
|
description: |
|
|
Logout the current user. This logs the event on the server side.
|
|
The client should remove the JWT token from storage.
|
|
operationId: logout
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: Logout successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
message:
|
|
type: string
|
|
example: Logged out successfully
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
|
|
# ==================== Documents ====================
|
|
/documents:
|
|
get:
|
|
tags:
|
|
- Documents
|
|
summary: List all documents
|
|
description: Retrieve a paginated list of all published framework documents
|
|
operationId: listDocuments
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 1
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 50
|
|
- name: quadrant
|
|
in: query
|
|
description: Filter by quadrant
|
|
schema:
|
|
type: string
|
|
enum: [STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC]
|
|
responses:
|
|
'200':
|
|
description: Documents retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
documents:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Document'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
|
|
post:
|
|
tags:
|
|
- Documents
|
|
summary: Create document (admin)
|
|
description: Create a new framework document
|
|
operationId: createDocument
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DocumentInput'
|
|
responses:
|
|
'201':
|
|
description: Document created successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
document:
|
|
$ref: '#/components/schemas/Document'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/documents/search:
|
|
get:
|
|
tags:
|
|
- Documents
|
|
summary: Search documents
|
|
description: Full-text search across all framework documents
|
|
operationId: searchDocuments
|
|
parameters:
|
|
- name: q
|
|
in: query
|
|
required: true
|
|
description: Search query
|
|
schema:
|
|
type: string
|
|
example: boundary enforcement
|
|
responses:
|
|
'200':
|
|
description: Search results retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
results:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Document'
|
|
count:
|
|
type: integer
|
|
example: 5
|
|
|
|
/documents/archived:
|
|
get:
|
|
tags:
|
|
- Documents
|
|
summary: List archived documents
|
|
description: Retrieve all archived documents
|
|
operationId: listArchivedDocuments
|
|
responses:
|
|
'200':
|
|
description: Archived documents retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
documents:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/Document'
|
|
|
|
/documents/{identifier}:
|
|
get:
|
|
tags:
|
|
- Documents
|
|
summary: Get document by ID or slug
|
|
description: Retrieve a single document by MongoDB ObjectId or URL slug
|
|
operationId: getDocument
|
|
parameters:
|
|
- name: identifier
|
|
in: path
|
|
required: true
|
|
description: Document ID or slug
|
|
schema:
|
|
type: string
|
|
example: 27027-incident-analysis
|
|
responses:
|
|
'200':
|
|
description: Document retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
document:
|
|
$ref: '#/components/schemas/Document'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
put:
|
|
tags:
|
|
- Documents
|
|
summary: Update document (admin)
|
|
description: Update an existing document
|
|
operationId: updateDocument
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: identifier
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DocumentInput'
|
|
responses:
|
|
'200':
|
|
description: Document updated successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
document:
|
|
$ref: '#/components/schemas/Document'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
delete:
|
|
tags:
|
|
- Documents
|
|
summary: Delete document (admin)
|
|
description: Delete a document (soft delete - archives it)
|
|
operationId: deleteDocument
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: identifier
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Document deleted successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
message:
|
|
type: string
|
|
example: Document archived successfully
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
# ==================== Governance Services ====================
|
|
/governance:
|
|
get:
|
|
tags:
|
|
- Governance Services
|
|
summary: Get framework status
|
|
description: |
|
|
Retrieve the current status of all governance framework components.
|
|
|
|
**Admin Only** - Contains sensitive runtime data.
|
|
operationId: getFrameworkStatus
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: Framework status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FrameworkStatus'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/governance/status:
|
|
get:
|
|
tags:
|
|
- Governance Services
|
|
summary: Get detailed governance status
|
|
description: |
|
|
Retrieve detailed status including component health, instruction counts, and system uptime.
|
|
|
|
**Admin Only**
|
|
operationId: getDetailedGovernanceStatus
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: Detailed status retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/components/schemas/FrameworkStatus'
|
|
- type: object
|
|
properties:
|
|
uptime:
|
|
type: number
|
|
description: Server uptime in seconds
|
|
example: 86400.5
|
|
environment:
|
|
type: string
|
|
example: production
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/governance/classify:
|
|
post:
|
|
tags:
|
|
- Governance Services
|
|
summary: Classify instruction
|
|
description: |
|
|
Test the InstructionPersistenceClassifier service by classifying a text instruction.
|
|
|
|
Returns: quadrant, persistence level, temporal scope, verification requirements, reasoning, and confidence score.
|
|
|
|
**Admin Only**
|
|
operationId: classifyInstruction
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- text
|
|
properties:
|
|
text:
|
|
type: string
|
|
example: Always use MongoDB on port 27027
|
|
context:
|
|
type: object
|
|
properties:
|
|
source:
|
|
type: string
|
|
example: user
|
|
session_id:
|
|
type: string
|
|
example: sess_123
|
|
responses:
|
|
'200':
|
|
description: Classification successful
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
classification:
|
|
$ref: '#/components/schemas/InstructionClassification'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/governance/validate:
|
|
post:
|
|
tags:
|
|
- Governance Services
|
|
summary: Validate action
|
|
description: |
|
|
Test the CrossReferenceValidator service by validating a proposed action against instruction history.
|
|
|
|
Detects conflicts, training pattern overrides (27027 failure mode), and provides validation status.
|
|
|
|
**Admin Only**
|
|
operationId: validateAction
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- action
|
|
properties:
|
|
action:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
example: database_change
|
|
description:
|
|
type: string
|
|
example: Change MongoDB port from 27027 to 27017
|
|
impact:
|
|
type: string
|
|
example: System configuration change
|
|
context:
|
|
type: object
|
|
properties:
|
|
messages:
|
|
type: array
|
|
items:
|
|
type: object
|
|
responses:
|
|
'200':
|
|
description: Validation complete
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
validation:
|
|
$ref: '#/components/schemas/ValidationResult'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/governance/enforce:
|
|
post:
|
|
tags:
|
|
- Governance Services
|
|
summary: Test boundary enforcement
|
|
description: |
|
|
Test the BoundaryEnforcer service by checking if an action crosses into values territory.
|
|
|
|
Identifies privacy, ethics, sovereignty, and strategic direction decisions requiring human approval.
|
|
|
|
**Admin Only**
|
|
operationId: enforceBounda ry
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- action
|
|
properties:
|
|
action:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
example: content_moderation
|
|
description:
|
|
type: string
|
|
example: Decide which user comments to hide
|
|
context:
|
|
type: object
|
|
responses:
|
|
'200':
|
|
description: Boundary enforcement check complete
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
enforcement:
|
|
$ref: '#/components/schemas/BoundaryEnforcement'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/governance/pressure:
|
|
post:
|
|
tags:
|
|
- Governance Services
|
|
summary: Analyze context pressure
|
|
description: |
|
|
Test the ContextPressureMonitor service by analyzing session health across multiple factors.
|
|
|
|
Returns pressure level (NORMAL/ELEVATED/HIGH/CRITICAL/DANGEROUS) and individual factor scores.
|
|
|
|
**Admin Only**
|
|
operationId: analyzePressure
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
context:
|
|
type: object
|
|
properties:
|
|
tokenUsage:
|
|
type: integer
|
|
example: 50000
|
|
tokenBudget:
|
|
type: integer
|
|
example: 200000
|
|
messageCount:
|
|
type: integer
|
|
example: 20
|
|
errorCount:
|
|
type: integer
|
|
example: 2
|
|
complexityScore:
|
|
type: number
|
|
example: 0.6
|
|
responses:
|
|
'200':
|
|
description: Pressure analysis complete
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
pressure:
|
|
$ref: '#/components/schemas/PressureAnalysis'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/governance/verify:
|
|
post:
|
|
tags:
|
|
- Governance Services
|
|
summary: Metacognitive verification
|
|
description: |
|
|
Test the MetacognitiveVerifier service by performing AI self-checks on proposed actions.
|
|
|
|
Detects scope creep, misalignment, and provides confidence scoring with alternatives.
|
|
|
|
**Admin Only**
|
|
operationId: verifyAction
|
|
security:
|
|
- BearerAuth: []
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- action
|
|
properties:
|
|
action:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
example: feature_implementation
|
|
description:
|
|
type: string
|
|
example: Add user authentication system
|
|
steps:
|
|
type: array
|
|
items:
|
|
type: string
|
|
reasoning:
|
|
type: object
|
|
properties:
|
|
justification:
|
|
type: string
|
|
example: Required for secure user management
|
|
context:
|
|
type: object
|
|
responses:
|
|
'200':
|
|
description: Verification complete
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
verification:
|
|
$ref: '#/components/schemas/MetacognitiveVerification'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
# ==================== Audit ====================
|
|
/audit/audit-logs:
|
|
get:
|
|
tags:
|
|
- Audit
|
|
summary: Get audit logs
|
|
description: |
|
|
Retrieve audit logs with filtering and pagination.
|
|
|
|
**Admin Only**
|
|
operationId: getAuditLogs
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: page
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 1
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 50
|
|
- name: action
|
|
in: query
|
|
description: Filter by action type
|
|
schema:
|
|
type: string
|
|
- name: userId
|
|
in: query
|
|
description: Filter by user ID
|
|
schema:
|
|
type: string
|
|
- name: startDate
|
|
in: query
|
|
description: Filter by start date (ISO 8601)
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
- name: endDate
|
|
in: query
|
|
description: Filter by end date (ISO 8601)
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
responses:
|
|
'200':
|
|
description: Audit logs retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
logs:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/AuditLog'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/audit/audit-analytics:
|
|
get:
|
|
tags:
|
|
- Audit
|
|
summary: Get audit analytics
|
|
description: |
|
|
Retrieve aggregated analytics on audit logs (action counts, user activity, trends).
|
|
|
|
**Admin Only**
|
|
operationId: getAuditAnalytics
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: startDate
|
|
in: query
|
|
description: Start date for analytics period (ISO 8601)
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
- name: endDate
|
|
in: query
|
|
description: End date for analytics period (ISO 8601)
|
|
schema:
|
|
type: string
|
|
format: date-time
|
|
responses:
|
|
'200':
|
|
description: Analytics retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
analytics:
|
|
type: object
|
|
properties:
|
|
totalLogs:
|
|
type: integer
|
|
example: 1250
|
|
actionBreakdown:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
example:
|
|
login: 450
|
|
document_create: 120
|
|
document_update: 380
|
|
classify: 200
|
|
validate: 100
|
|
topUsers:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
userId:
|
|
type: string
|
|
email:
|
|
type: string
|
|
count:
|
|
type: integer
|
|
timeline:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
date:
|
|
type: string
|
|
format: date
|
|
count:
|
|
type: integer
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
# ==================== Admin ====================
|
|
/admin/moderation:
|
|
get:
|
|
tags:
|
|
- Admin
|
|
summary: List moderation queue
|
|
description: |
|
|
Retrieve items pending moderation.
|
|
|
|
**Admin or Moderator role required**
|
|
operationId: getModerationQueue
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: status
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: [pending, approved, rejected, escalated]
|
|
default: pending
|
|
- name: page
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 1
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 50
|
|
responses:
|
|
'200':
|
|
description: Moderation queue retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
items:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ModerationItem'
|
|
pagination:
|
|
$ref: '#/components/schemas/Pagination'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/admin/moderation/{id}:
|
|
get:
|
|
tags:
|
|
- Admin
|
|
summary: Get moderation item
|
|
description: |
|
|
Retrieve a single moderation item by ID.
|
|
|
|
**Admin or Moderator role required**
|
|
operationId: getModerationItem
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Moderation item retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
item:
|
|
$ref: '#/components/schemas/ModerationItem'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/admin/moderation/{id}/review:
|
|
post:
|
|
tags:
|
|
- Admin
|
|
summary: Review moderation item
|
|
description: |
|
|
Approve, reject, or escalate a moderation item.
|
|
|
|
**Admin or Moderator role required**
|
|
operationId: reviewModerationItem
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- action
|
|
properties:
|
|
action:
|
|
type: string
|
|
enum: [approve, reject, escalate]
|
|
example: approve
|
|
notes:
|
|
type: string
|
|
example: Content meets guidelines
|
|
responses:
|
|
'200':
|
|
description: Review completed successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
item:
|
|
$ref: '#/components/schemas/ModerationItem'
|
|
'400':
|
|
$ref: '#/components/responses/BadRequest'
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
'404':
|
|
$ref: '#/components/responses/NotFound'
|
|
|
|
/admin/stats:
|
|
get:
|
|
tags:
|
|
- Admin
|
|
summary: Get system statistics
|
|
description: |
|
|
Retrieve overall system statistics (users, documents, submissions, moderation queue).
|
|
|
|
**Admin or Moderator role required**
|
|
operationId: getSystemStats
|
|
security:
|
|
- BearerAuth: []
|
|
responses:
|
|
'200':
|
|
description: Statistics retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
stats:
|
|
type: object
|
|
properties:
|
|
users:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
example: 125
|
|
admins:
|
|
type: integer
|
|
example: 3
|
|
moderators:
|
|
type: integer
|
|
example: 5
|
|
documents:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
example: 45
|
|
published:
|
|
type: integer
|
|
example: 42
|
|
archived:
|
|
type: integer
|
|
example: 3
|
|
moderation:
|
|
type: object
|
|
properties:
|
|
pending:
|
|
type: integer
|
|
example: 12
|
|
approved:
|
|
type: integer
|
|
example: 380
|
|
rejected:
|
|
type: integer
|
|
example: 45
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
/admin/activity:
|
|
get:
|
|
tags:
|
|
- Admin
|
|
summary: Get activity log
|
|
description: |
|
|
Retrieve recent admin activity (last 100 actions).
|
|
|
|
**Admin role required**
|
|
operationId: getActivityLog
|
|
security:
|
|
- BearerAuth: []
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 100
|
|
maximum: 500
|
|
responses:
|
|
'200':
|
|
description: Activity log retrieved successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
activities:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
userId:
|
|
type: string
|
|
email:
|
|
type: string
|
|
action:
|
|
type: string
|
|
example: document_update
|
|
details:
|
|
type: object
|
|
'401':
|
|
$ref: '#/components/responses/Unauthorized'
|
|
'403':
|
|
$ref: '#/components/responses/Forbidden'
|
|
|
|
# ==================== Components ====================
|
|
components:
|
|
securitySchemes:
|
|
BearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: |
|
|
JWT token obtained from /api/auth/login endpoint.
|
|
|
|
Include in Authorization header: `Authorization: Bearer <token>`
|
|
|
|
schemas:
|
|
User:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
example: 68e3a6fb21af2fd194bf4b50
|
|
email:
|
|
type: string
|
|
format: email
|
|
example: admin@tractatus.local
|
|
role:
|
|
type: string
|
|
enum: [admin, moderator, user]
|
|
example: admin
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
Document:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
example: 67890abc12345def67890abc
|
|
title:
|
|
type: string
|
|
example: Introduction to the Tractatus Framework
|
|
slug:
|
|
type: string
|
|
example: introduction-to-tractatus
|
|
quadrant:
|
|
type: string
|
|
enum: [STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC]
|
|
example: STRATEGIC
|
|
content_markdown:
|
|
type: string
|
|
description: Document content in Markdown format
|
|
content_html:
|
|
type: string
|
|
description: Auto-generated HTML from Markdown
|
|
status:
|
|
type: string
|
|
enum: [draft, published, archived]
|
|
default: published
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
created_by:
|
|
type: string
|
|
description: User ID
|
|
|
|
DocumentInput:
|
|
type: object
|
|
required:
|
|
- title
|
|
- slug
|
|
- quadrant
|
|
- content_markdown
|
|
properties:
|
|
title:
|
|
type: string
|
|
example: Core Concepts of the Tractatus Framework
|
|
slug:
|
|
type: string
|
|
pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*$
|
|
example: core-concepts
|
|
quadrant:
|
|
type: string
|
|
enum: [STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC]
|
|
example: OPERATIONAL
|
|
content_markdown:
|
|
type: string
|
|
description: Document content in Markdown format
|
|
status:
|
|
type: string
|
|
enum: [draft, published, archived]
|
|
default: published
|
|
|
|
FrameworkStatus:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
example: true
|
|
components:
|
|
type: object
|
|
properties:
|
|
InstructionPersistenceClassifier:
|
|
type: string
|
|
enum: [ACTIVE, INACTIVE, ERROR]
|
|
example: ACTIVE
|
|
CrossReferenceValidator:
|
|
type: string
|
|
enum: [ACTIVE, INACTIVE, ERROR]
|
|
example: ACTIVE
|
|
BoundaryEnforcer:
|
|
type: string
|
|
enum: [ACTIVE, INACTIVE, ERROR]
|
|
example: ACTIVE
|
|
ContextPressureMonitor:
|
|
type: string
|
|
enum: [ACTIVE, INACTIVE, ERROR]
|
|
example: ACTIVE
|
|
MetacognitiveVerifier:
|
|
type: string
|
|
enum: [ACTIVE, INACTIVE, ERROR]
|
|
example: ACTIVE
|
|
instructions:
|
|
type: object
|
|
properties:
|
|
total:
|
|
type: integer
|
|
example: 28
|
|
HIGH:
|
|
type: integer
|
|
example: 27
|
|
MEDIUM:
|
|
type: integer
|
|
example: 1
|
|
LOW:
|
|
type: integer
|
|
example: 0
|
|
pressure:
|
|
type: object
|
|
properties:
|
|
level:
|
|
type: string
|
|
enum: [NORMAL, ELEVATED, HIGH, CRITICAL, DANGEROUS]
|
|
example: NORMAL
|
|
score:
|
|
type: number
|
|
example: 0.033
|
|
|
|
InstructionClassification:
|
|
type: object
|
|
properties:
|
|
quadrant:
|
|
type: string
|
|
enum: [STRATEGIC, OPERATIONAL, TACTICAL, SYSTEM, STOCHASTIC]
|
|
example: SYSTEM
|
|
persistence:
|
|
type: string
|
|
enum: [HIGH, MEDIUM, LOW]
|
|
example: HIGH
|
|
temporal_scope:
|
|
type: string
|
|
enum: [SESSION, PROJECT, PERMANENT]
|
|
example: PROJECT
|
|
verification_required:
|
|
type: string
|
|
enum: [MANDATORY, RECOMMENDED, OPTIONAL]
|
|
example: MANDATORY
|
|
reasoning:
|
|
type: string
|
|
example: Port configuration affects system infrastructure
|
|
confidence:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
maximum: 1
|
|
example: 0.95
|
|
|
|
ValidationResult:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [PASS, WARN, BLOCK]
|
|
example: BLOCK
|
|
conflicts:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
instruction_id:
|
|
type: string
|
|
text:
|
|
type: string
|
|
example: Always use MongoDB on port 27027
|
|
severity:
|
|
type: string
|
|
enum: [CRITICAL, HIGH, MEDIUM, LOW]
|
|
example: CRITICAL
|
|
trainingOverride:
|
|
type: boolean
|
|
example: true
|
|
description: True if action appears to override training patterns (27027 failure mode)
|
|
recommendation:
|
|
type: string
|
|
example: Action conflicts with HIGH persistence instruction (inst_002). Recommend maintaining port 27027.
|
|
|
|
BoundaryEnforcement:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
enum: [ALLOW, BLOCK, ESCALATE]
|
|
example: BLOCK
|
|
boundary:
|
|
type: string
|
|
enum: [PRIVACY, ETHICS, SOVEREIGNTY, STRATEGIC]
|
|
example: ETHICS
|
|
description: Which values boundary was crossed
|
|
reasoning:
|
|
type: string
|
|
example: Content moderation decisions involve ethical judgments about acceptable speech
|
|
alternatives:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example:
|
|
- Define clear content policy guidelines
|
|
- Implement automated flagging system
|
|
- Escalate to human moderators for final decision
|
|
requiresHuman:
|
|
type: boolean
|
|
example: true
|
|
|
|
PressureAnalysis:
|
|
type: object
|
|
properties:
|
|
level:
|
|
type: string
|
|
enum: [NORMAL, ELEVATED, HIGH, CRITICAL, DANGEROUS]
|
|
example: NORMAL
|
|
score:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
maximum: 1
|
|
example: 0.25
|
|
factors:
|
|
type: object
|
|
properties:
|
|
tokenPressure:
|
|
type: number
|
|
example: 0.25
|
|
description: Token usage / budget
|
|
messagePressure:
|
|
type: number
|
|
example: 0.15
|
|
description: Message count / threshold
|
|
errorPressure:
|
|
type: number
|
|
example: 0.1
|
|
description: Error rate
|
|
complexityPressure:
|
|
type: number
|
|
example: 0.6
|
|
description: Task complexity score
|
|
instructionVolume:
|
|
type: number
|
|
example: 0.28
|
|
description: Active instruction density
|
|
recommendation:
|
|
type: string
|
|
example: Session health is normal. Continue work.
|
|
triggerHandoff:
|
|
type: boolean
|
|
example: false
|
|
description: True if pressure warrants session handoff
|
|
|
|
MetacognitiveVerification:
|
|
type: object
|
|
properties:
|
|
decision:
|
|
type: string
|
|
enum: [PROCEED, REVIEW, BLOCK]
|
|
example: PROCEED
|
|
confidence:
|
|
type: number
|
|
format: float
|
|
minimum: 0
|
|
maximum: 1
|
|
example: 0.85
|
|
concerns:
|
|
type: array
|
|
items:
|
|
type: string
|
|
example:
|
|
- Consider rate limiting for authentication endpoints
|
|
alternatives:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
description:
|
|
type: string
|
|
pros:
|
|
type: array
|
|
items:
|
|
type: string
|
|
cons:
|
|
type: array
|
|
items:
|
|
type: string
|
|
scopeCreep:
|
|
type: boolean
|
|
example: false
|
|
description: True if action appears to exceed original scope
|
|
alignment:
|
|
type: object
|
|
properties:
|
|
strategic:
|
|
type: number
|
|
example: 0.9
|
|
operational:
|
|
type: number
|
|
example: 0.85
|
|
tactical:
|
|
type: number
|
|
example: 0.8
|
|
|
|
AuditLog:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
format: date-time
|
|
userId:
|
|
type: string
|
|
email:
|
|
type: string
|
|
format: email
|
|
action:
|
|
type: string
|
|
example: document_create
|
|
resource:
|
|
type: string
|
|
example: documents
|
|
resourceId:
|
|
type: string
|
|
details:
|
|
type: object
|
|
ipAddress:
|
|
type: string
|
|
example: 192.168.1.100
|
|
userAgent:
|
|
type: string
|
|
|
|
ModerationItem:
|
|
type: object
|
|
properties:
|
|
_id:
|
|
type: string
|
|
type:
|
|
type: string
|
|
enum: [case_submission, media_inquiry, comment]
|
|
example: case_submission
|
|
status:
|
|
type: string
|
|
enum: [pending, approved, rejected, escalated]
|
|
example: pending
|
|
submittedAt:
|
|
type: string
|
|
format: date-time
|
|
content:
|
|
type: object
|
|
reviewedBy:
|
|
type: string
|
|
description: User ID of reviewer
|
|
reviewedAt:
|
|
type: string
|
|
format: date-time
|
|
reviewNotes:
|
|
type: string
|
|
|
|
Pagination:
|
|
type: object
|
|
properties:
|
|
page:
|
|
type: integer
|
|
example: 1
|
|
limit:
|
|
type: integer
|
|
example: 50
|
|
total:
|
|
type: integer
|
|
example: 250
|
|
pages:
|
|
type: integer
|
|
example: 5
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
example: Bad Request
|
|
message:
|
|
type: string
|
|
example: Missing required field 'text'
|
|
details:
|
|
type: object
|
|
description: Additional error details (optional)
|
|
|
|
responses:
|
|
BadRequest:
|
|
description: Bad Request - Invalid input
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error: Bad Request
|
|
message: Missing required field 'text'
|
|
|
|
Unauthorized:
|
|
description: Unauthorized - Authentication required
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error: Unauthorized
|
|
message: Authentication required. Please provide a valid JWT token.
|
|
|
|
Forbidden:
|
|
description: Forbidden - Insufficient permissions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error: Forbidden
|
|
message: Admin role required for this endpoint
|
|
|
|
NotFound:
|
|
description: Not Found - Resource does not exist
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
example:
|
|
error: Not Found
|
|
message: Document not found
|
|
|
|
security:
|
|
- BearerAuth: []
|