{
  "openapi": "3.0.3",
  "info": {
    "title": "Syntra EV Infrastructure Actions API",
    "version": "0.1.0",
    "description": "Safe, approval-gated EV workflow actions for Microsoft Copilot Studio / M365 agent integration. All write-capable actions require human approval before execution. No real external system connections are used in demo mode.",
    "contact": {
      "name": "Syntra Suite",
      "url": "https://syntra.ai"
    }
  },
  "servers": [
    {
      "url": "/api/ev-infrastructure",
      "description": "Same-origin API root (Next.js route handlers)"
    }
  ],
  "tags": [
    {
      "name": "Actions",
      "description": "EV infrastructure workflow actions exposed for Copilot / agent consumption"
    },
    {
      "name": "Safety",
      "description": "Safety and approval behavior"
    }
  ],
  "paths": {
    "/actions": {
      "get": {
        "operationId": "listEvActions",
        "summary": "List available EV Infrastructure actions",
        "description": "Returns all registered EV workflow actions with their metadata, including which actions require approval before execution.",
        "tags": ["Actions"],
        "responses": {
          "200": {
            "description": "List of available actions",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/actions/create-opportunity": {
      "post": {
        "operationId": "createOpportunity",
        "summary": "Create a new EV infrastructure opportunity",
        "description": "Creates a sanitized opportunity record. In demo mode, no data is persisted externally. This action does NOT require approval.",
        "tags": ["Actions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Opportunity prepared (demo mode or approval queued)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/actions/start-research": {
      "post": {
        "operationId": "startResearch",
        "summary": "Start research tasks for an opportunity",
        "description": "Queues research tasks (utility rates, site constraints, incentives) for a given project. In demo mode, no external data sources are queried.",
        "tags": ["Actions"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Research tasks queued (demo mode or approval queued)",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/actions/create-proposal-outline": {
      "post": {
        "operationId": "createProposalOutline",
        "summary": "Create a proposal outline (approval required)",
        "description": "Generates a proposal outline for an EV infrastructure project. Creates an approval queue item. No files are written without human approval.",
        "tags": ["Actions", "Safety"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval item created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/actions/create-business-case": {
      "post": {
        "operationId": "createBusinessCase",
        "summary": "Create a business case (approval required)",
        "description": "Drafts a business case with ROI/TCO assumptions. Creates an approval queue item. No financial data is saved without human approval.",
        "tags": ["Actions", "Safety"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval item created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/actions/create-deck-outline": {
      "post": {
        "operationId": "createDeckOutline",
        "summary": "Create a PowerPoint deck outline (approval required)",
        "description": "Generates a deck outline for an EV infrastructure proposal. Creates an approval queue item. No PPTX files are created without human approval.",
        "tags": ["Actions", "Safety"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval item created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/actions/prepare-follow-up": {
      "post": {
        "operationId": "prepareFollowUp",
        "summary": "Prepare a client follow-up (approval required)",
        "description": "Drafts a client follow-up communication. Creates an approval queue item. No email is sent without human approval.",
        "tags": ["Actions", "Safety"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval item created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/actions/prepare-smartsheet-update": {
      "post": {
        "operationId": "prepareSmartsheetUpdate",
        "summary": "Prepare a Smartsheet update (approval required)",
        "description": "Prepares a Smartsheet row update for an EV project. Creates an approval queue item. No data is written to Smartsheet without human approval.",
        "tags": ["Actions", "Safety"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Approval item created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/actions/route-for-approval": {
      "post": {
        "operationId": "routeForApproval",
        "summary": "Route an action through the approval queue",
        "description": "Routes any EV action through the human approval queue. All sensitive fields are sanitized. No external systems are affected until approved.",
        "tags": ["Actions", "Safety"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action routed to approval queue",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ActionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "ActionMeta": {
        "type": "object",
        "required": ["type", "label", "description", "requiresApproval", "category"],
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "create_opportunity",
              "start_research",
              "create_proposal_outline",
              "create_business_case",
              "create_deck_outline",
              "prepare_follow_up",
              "prepare_smartsheet_update",
              "route_for_approval"
            ],
            "description": "Machine-readable action type identifier"
          },
          "label": {
            "type": "string",
            "description": "Human-readable action label"
          },
          "description": {
            "type": "string",
            "description": "Detailed description of what the action does"
          },
          "requiresApproval": {
            "type": "boolean",
            "description": "Whether this action requires human approval before execution. True for all actions that would modify external systems."
          },
          "category": {
            "type": "string",
            "enum": [
              "Opportunities",
              "Research",
              "Proposals",
              "Business Case",
              "Deliverables",
              "Follow-Up",
              "Smartsheet",
              "Approval"
            ]
          }
        }
      },
      "ActionRequest": {
        "type": "object",
        "required": ["projectName"],
        "properties": {
          "actionType": {
            "type": "string",
            "description": "Optional for single-action endpoints; required for route-for-approval"
          },
          "projectName": {
            "type": "string",
            "description": "Project name (sanitized before processing)",
            "example": "Northstar EV - Site A"
          },
          "clientName": {
            "type": "string",
            "description": "Client name (sanitized before processing)",
            "example": "John Davis"
          },
          "opportunityName": {
            "type": "string",
            "description": "Opportunity name (used by create-opportunity)",
            "example": "Fleet Depot Phase 1"
          },
          "siteCount": {
            "type": "integer",
            "description": "Number of sites",
            "minimum": 1
          },
          "coordinatorNote": {
            "type": "string",
            "description": "Free-text note from the coordinator (sanitized)",
            "example": "Please prepare the proposal by Friday"
          },
          "workspaceSlug": {
            "type": "string",
            "description": "Workspace slug for routing",
            "default": "ev-infrastructure"
          },
          "extra": {
            "type": "object",
            "description": "Additional action-specific fields",
            "additionalProperties": true
          }
        }
      },
      "ApprovalQueueItem": {
        "type": "object",
        "required": ["id", "type", "label", "sanitized", "sanitizedProjectName", "sanitizedClientName", "status", "createdAt", "workspaceSlug"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique approval item ID"
          },
          "type": {
            "type": "string",
            "description": "Action type that generated this approval item"
          },
          "label": {
            "type": "string",
            "description": "Human-readable action label"
          },
          "sanitized": {
            "type": "boolean",
            "description": "Whether input data has been sanitized (always true)"
          },
          "sanitizedProjectName": {
            "type": "string",
            "description": "Sanitized project name (sensitive fields redacted)"
          },
          "sanitizedClientName": {
            "type": "string",
            "description": "Sanitized client name (PII redacted)"
          },
          "coordinatorNote": {
            "type": "string",
            "description": "Sanitized coordinator note"
          },
          "status": {
            "type": "string",
            "enum": ["needs_approval"],
            "description": "Current status (always needs_approval when created)"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "ISO 8601 timestamp"
          },
          "workspaceSlug": {
            "type": "string",
            "description": "Workspace this action belongs to"
          },
          "extra": {
            "type": "object",
            "description": "Additional sanitized fields",
            "additionalProperties": true
          }
        }
      },
      "ActionListResponse": {
        "type": "object",
        "required": ["success", "data", "demoMode", "message"],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ActionMeta"
            }
          },
          "demoMode": {
            "type": "boolean",
            "description": "Always true in this build — no real Copilot connection"
          },
          "message": {
            "type": "string"
          }
        }
      },
      "ActionResponse": {
        "type": "object",
        "required": ["success", "data", "demoMode", "message", "approvalRequired"],
        "properties": {
          "success": {
            "type": "boolean"
          },
          "data": {
            "oneOf": [
              { "$ref": "#/components/schemas/ApprovalQueueItem" },
              { "type": "null" }
            ],
            "description": "Approval queue item or null"
          },
          "demoMode": {
            "type": "boolean",
            "description": "Always true in this build — no real Copilot connection"
          },
          "message": {
            "type": "string",
            "description": "Human-readable status message"
          },
          "approvalRequired": {
            "type": "boolean",
            "description": "Whether this specific action requires human approval before execution"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": ["success", "error"],
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "error": {
            "type": "string"
          }
        }
      }
    },
    "securitySchemes": {}
  },
  "x-safety": {
    "demoMode": true,
    "approvalGated": true,
    "noRealCopilot": true,
    "noExternalWrites": true,
    "inputSanitization": true,
    "piiRedactedFields": [
      "site addresses",
      "account numbers",
      "contract values",
      "load data (kW, kWh, MW)",
      "utility accounts",
      "email addresses",
      "phone numbers",
      "client names",
      "confidential markers"
    ],
    "actionsThatNeverExecuteDirectly": [
      "create_proposal_outline",
      "create_business_case",
      "create_deck_outline",
      "prepare_follow_up",
      "prepare_smartsheet_update",
      "route_for_approval"
    ]
  }
}