State Management API Documentation This document describes the API endpoints for managing state diagrams. 1. Generate State Diagram ----------------------- Endpoint: POST /api/modules/{module_id}/functions/{function_id}/state/generate Description: Generate a state diagram using Claude AI. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function Request Body: { "use_default_template": true,\n "custom_instructions": "Optional custom instructions for generation" } Fields: - use_default_template (boolean, required): Whether to use the default prompt template - custom_instructions (string, optional): Custom instructions for diagram generation Response: { "message": "State diagram generated successfully",\n "diagrams": [ { "ID": "STATE_12345678",\n "diagram": "stateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]",\n "raw": "```mermaid\nstateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]\n```",\n "states": [...],\n "transitions": [...],\n "status": "active",\n "selected": false,\n "current_version": 1,\n "has_versions": true,\n "created_at": "2024-01-01T00:00:00Z",\n "updated_at": "2024-01-01T00:00:00Z",\n "created_by": "claude",\n "last_modified_by": "claude",\n "api_usage": {"tokens": 1000} } ],\n "metadata": { "function_id": "func_12345678",\n "module_id": "MOD_12345678",\n "total_count": 1,\n "created_at": "2024-01-01T00:00:00Z",\n "updated_at": "2024-01-01T00:00:00Z",\n "api_usage": {"tokens": 1000},\n "function_current_version": 1,\n "state_descriptions": {},\n "integration_points": [],\n "validation_rules": [],\n "error_handling": {},\n "async_operations": [] } } 2. Create State Diagram Manually ------------------------------ Endpoint: POST /api/modules/{module_id}/functions/{function_id}/state/manual Description: Create a new state diagram manually. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function Request Body: { "title": "Login Flow",\n "description": "State diagram for user login flow",\n "diagram": "stateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]",\n "created_by": "user123" } Fields: - title (string, required): Title of the state diagram - description (string, required): Description of the state diagram - diagram (string, required): Raw mermaid state diagram content - created_by (string, required): Creator of the diagram Response: { "message": "State diagram created successfully",\n "diagram": { "ID": "STATE_12345678",\n "diagram": "stateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]",\n "raw": "```mermaid\nstateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]\n```",\n "states": [...],\n "transitions": [...],\n "status": "active",\n "selected": false,\n "current_version": 1,\n "has_versions": true,\n "created_at": "2024-01-01T00:00:00Z",\n "updated_at": "2024-01-01T00:00:00Z",\n "created_by": "user123",\n "last_modified_by": "user123",\n "title": "Login Flow",\n "description": "State diagram for user login flow",\n "api_usage": {"tokens": 0} } } 3. List State Diagrams -------------------- Endpoint: GET /api/modules/{module_id}/functions/{function_id}/state Description: List all state diagrams for a function. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function - search (query, optional): Search term for filtering state diagrams - include_inactive (query, optional): Include inactive state diagrams in results Response: { "total": 1,\n "diagrams": [ { "ID": "STATE_12345678",\n "diagram": "stateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]",\n "raw": "```mermaid\nstateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]\n```",\n "states": [...],\n "transitions": [...],\n "status": "active",\n "selected": false,\n "current_version": 1,\n "has_versions": true,\n "created_at": "2024-01-01T00:00:00Z",\n "updated_at": "2024-01-01T00:00:00Z",\n "created_by": "user123",\n "last_modified_by": "user123",\n "title": "Login Flow",\n "description": "State diagram for user login flow",\n "api_usage": {"tokens": 0} } ],\n "metadata": { "function_id": "func_12345678",\n "module_id": "MOD_12345678",\n "total_count": 1,\n "created_at": "2024-01-01T00:00:00Z",\n "updated_at": "2024-01-01T00:00:00Z",\n "api_usage": {"tokens": 0},\n "function_current_version": 1 } } 4. List State Diagram Versions --------------------------- Endpoint: GET /api/modules/{module_id}/functions/{function_id}/state/{state_id}/versions Description: List all versions of a specific state diagram. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function - state_id (path, required): The ID of the state diagram - include_content (query, optional): Include full diagram content in response Response: { "total": 1,\n "versions": [ { "ID": "STATE_VER_12345678",\n "state_id": "STATE_12345678",\n "module_id": "MOD_12345678",\n "function_id": "func_12345678",\n "version_number": 1,\n "function_version": 1,\n "created_at": "2024-01-01T00:00:00Z",\n "created_by": "user123",\n "api_usage": {"tokens": 0},\n "is_current": true } ] } 5. Get State Diagram Version ------------------------- Endpoint: GET /api/modules/{module_id}/functions/{function_id}/state/{state_id}/versions/{version_id} Description: Get a specific version of a state diagram. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function - state_id (path, required): The ID of the state diagram - version_id (path, required): The ID of the version Response: { "version": { "ID": "STATE_VER_12345678",\n "state_id": "STATE_12345678",\n "module_id": "MOD_12345678",\n "function_id": "func_12345678",\n "content": "stateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]",\n "raw": "```mermaid\nstateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]\n```",\n "states": [...],\n "transitions": [...],\n "version_number": 1,\n "function_version": 1,\n "created_at": "2024-01-01T00:00:00Z",\n "created_by": "user123",\n "api_usage": {"tokens": 0},\n "is_current": true } } 6. Update State Diagram -------------------- Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/state/{state_id} Description: Update a specific state diagram by ID. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function - state_id (path, required): The ID of the state diagram Request Body: { "diagram": "stateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]",\n "states": [...],\n "transitions": [...],\n "status": "active",\n "modified_by": "user123",\n "change_reason": "Updated state transitions" } Fields: - diagram (string, optional): Raw mermaid diagram content - states (array, optional): List of states in the diagram - transitions (array, optional): List of transitions between states - status (string, optional): Status of the diagram - modified_by (string, required): User making the modification - change_reason (string, optional): Reason for the change Response: { "message": "State diagram updated successfully",\n "diagram": { "ID": "STATE_12345678",\n "diagram": "stateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]",\n "raw": "```mermaid\nstateDiagram-v2\n [*] --> State1\n State1 --> State2\n State2 --> [*]\n```",\n "states": [...],\n "transitions": [...],\n "status": "active",\n "selected": false,\n "current_version": 2,\n "has_versions": true,\n "created_at": "2024-01-01T00:00:00Z",\n "updated_at": "2024-01-01T00:00:00Z",\n "created_by": "user123",\n "last_modified_by": "user123",\n "api_usage": {"tokens": 0} } } 7. Activate/Deactivate State Diagram -------------------------------- Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/state/{state_id}/activate Description: Activate or deactivate a state diagram. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function - state_id (path, required): The ID of the state diagram - activate (query, required): Whether to activate or deactivate the diagram Response: { "message": "State diagram activated successfully",\n "diagram": { "ID": "STATE_12345678",\n "status": "active",\n "updated_at": "2024-01-01T00:00:00Z",\n ... } } 8. Select State Diagram -------------------- Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/state/{state_id}/select Description: Select a state diagram as the current version. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function - state_id (path, required): The ID of the state diagram Response: { "message": "State diagram selected successfully",\n "diagram": { "ID": "STATE_12345678",\n "selected": true,\n "updated_at": "2024-01-01T00:00:00Z",\n ... } } 9. Deselect State Diagram ---------------------- Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/state/{state_id}/deselect Description: Deselect a state diagram. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function - state_id (path, required): The ID of the state diagram Response: { "message": "State diagram deselected successfully",\n "diagram": { "ID": "STATE_12345678",\n "selected": false,\n "updated_at": "2024-01-01T00:00:00Z",\n ... } } 10. Mark for Development -------------------- Endpoint: PUT /api/modules/{module_id}/functions/{function_id}/state/{state_id}/mark_for_development Description: Mark a state diagram for development with version and status information. Request Parameters: - module_id (path, required): The ID of the module - function_id (path, required): The ID of the function - state_id (path, required): The ID of the state diagram Request Body: { "version": "v1.0.0",\n "notes": "Initial development version",\n "status": "in_development" } Fields: - version (string, required): Development version (e.g. v1.0.0) - notes (string, optional): Additional notes about the development status - status (string, required): Development status (not_started/in_development/completed/archived) Response: { "message": "State diagram marked for development with version v1.0.0 and status: in_development",\n "diagram": { "ID": "STATE_12345678",\n "development": { "version": "v1.0.0",\n "notes": "Initial development version",\n "status": "in_development" },\n "updated_at": "2024-01-01T00:00:00Z",\n ... } } Note: All endpoints include CORS headers and proper error handling. Error responses follow the standard HTTP status codes and include detailed error messages.