{
  "openapi": "3.1.0",
  "info": {
    "title": "Spectosoft Platform API",
    "version": "1.0.0",
    "description": "Spectosoft workforce intelligence API. Authenticate with POST /auth/login to receive a JWT, then send it as Authorization: Bearer. Named permission scopes are declared here and in RFC 9728 metadata at /.well-known/oauth-protected-resource. Website discovery: /openapi.json, /api/health, /.well-known/api-catalog.",
    "contact": {
      "name": "Spectosoft Support",
      "email": "contact@spectosoft.com",
      "url": "https://spectosoft.com/resources/documentation"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://spectosoft.com/company/terms"
    }
  },
  "servers": [
    {
      "url": "https://api.spectosoft.com/api/v1",
      "description": "Production API"
    },
    {
      "url": "https://dev.api.spectosoft.com/api/v1",
      "description": "Development API"
    }
  ],
  "security": [
    {
      "OAuth2": ["analytics.read"]
    },
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/auth/login": {
      "post": {
        "summary": "User authentication",
        "operationId": "login",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JWT session or 2FA challenge",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LoginResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/auth/verify-2fa": {
      "post": {
        "summary": "Verify two-factor OTP",
        "operationId": "verify2FA",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Verify2FARequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tokens issued",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequestError"
          }
        }
      }
    },
    "/auth/refresh": {
      "post": {
        "summary": "Refresh access token",
        "operationId": "refreshToken",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["refresh_token"],
                "properties": {
                  "refresh_token": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Rotated tokens",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTokenResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/auth/profile": {
      "get": {
        "summary": "Current user profile",
        "operationId": "getProfile",
        "security": [
          { "OAuth2": ["users.read"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Authenticated user profile"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/analytics/dashboard-stats": {
      "get": {
        "summary": "Dashboard overview statistics",
        "operationId": "getDashboardStats",
        "security": [
          { "OAuth2": ["analytics.read"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Aggregated organization telemetry"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/monitoring/activities": {
      "get": {
        "summary": "List activity telemetry",
        "operationId": "listActivities",
        "security": [
          { "OAuth2": ["activities.view"] },
          { "BearerAuth": [] }
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "schema": { "type": "integer", "default": 1 }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": { "type": "integer", "default": 50 }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated activity records"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/monitoring/screenshots": {
      "get": {
        "summary": "List captured screenshots",
        "operationId": "listScreenshots",
        "security": [
          { "OAuth2": ["screenshots.view"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Screenshot metadata and media URLs"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/monitoring/recordings": {
      "get": {
        "summary": "List session recordings",
        "operationId": "listRecordings",
        "security": [
          { "OAuth2": ["recordings.view"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Recording sessions"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/analytics/live-users": {
      "get": {
        "summary": "Live monitoring users",
        "operationId": "listLiveUsers",
        "security": [
          { "OAuth2": ["streaming.view"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Currently streaming users"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/risk/events": {
      "get": {
        "summary": "List risk and alert events",
        "operationId": "listRiskEvents",
        "security": [
          { "OAuth2": ["ops.read"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Risk events"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/users": {
      "get": {
        "summary": "List organization users",
        "operationId": "listUsers",
        "security": [
          { "OAuth2": ["users.read"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "User directory"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/teams": {
      "get": {
        "summary": "List teams",
        "operationId": "listTeams",
        "security": [
          { "OAuth2": ["users.read"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Teams"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    },
    "/ai-search": {
      "post": {
        "summary": "Natural-language telemetry search",
        "operationId": "aiSearch",
        "security": [
          { "OAuth2": ["ai_search.use"] },
          { "BearerAuth": [] }
        ],
        "responses": {
          "200": {
            "description": "Search result"
          },
          "401": {
            "$ref": "#/components/responses/UnauthorizedError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "OAuth2": {
        "type": "oauth2",
        "description": "Named RBAC permission scopes for least-privilege access. Access tokens are JWTs issued by POST /auth/login and sent as Authorization: Bearer.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://spectosoft.com/auth/login",
            "tokenUrl": "https://api.spectosoft.com/api/v1/auth/login",
            "scopes": {
              "activities.view": "View activity logs, window titles, and website URLs",
              "screenshots.view": "View captured screenshots",
              "recordings.view": "View session recordings",
              "streaming.view": "View live screen streams",
              "replay.view": "View session replay recordings",
              "analytics.read": "Read analytics dashboards and productivity metrics",
              "ai_search.use": "Run natural-language AI search across telemetry",
              "assistant.use": "Use the Spectosoft AI assistant",
              "reports.export": "Export CSV and PDF reports",
              "users.read": "Read organization user profiles",
              "users.write": "Invite, update, and manage user accounts",
              "org.settings": "Read and update organization settings",
              "ops.read": "Read AI Ops dashboards",
              "ops.manage": "Manage connectors and AI Ops configuration",
              "teams.manage": "Create and manage teams",
              "cortex.discovery.manage_taxonomy": "Manage Cortex application taxonomy",
              "support.company": "Access company support tickets",
              "support.inbox": "Access the Human Support Team inbox"
            }
          }
        }
      },
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "JWT access token from POST /auth/login or POST /auth/refresh."
      }
    },
    "schemas": {
      "ProblemDetails": {
        "type": "object",
        "required": ["type", "title", "status", "detail", "code"],
        "properties": {
          "type": { "type": "string", "format": "uri" },
          "title": { "type": "string" },
          "status": { "type": "integer" },
          "detail": { "type": "string" },
          "instance": { "type": "string" },
          "code": { "type": "string", "example": "ENDPOINT_NOT_FOUND" },
          "resolution": { "type": "string" },
          "documentation_url": { "type": "string", "format": "uri" }
        }
      },
      "LoginRequest": {
        "type": "object",
        "required": ["email", "password"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "password": { "type": "string", "format": "password" }
        }
      },
      "LoginResponse": {
        "type": "object",
        "properties": {
          "requires_two_factor": { "type": "boolean" },
          "access_token": { "type": "string" },
          "refresh_token": { "type": "string" },
          "message": { "type": "string" }
        }
      },
      "Verify2FARequest": {
        "type": "object",
        "required": ["email", "otp"],
        "properties": {
          "email": { "type": "string", "format": "email" },
          "otp": { "type": "string" }
        }
      },
      "AuthTokenResponse": {
        "type": "object",
        "properties": {
          "access_token": { "type": "string" },
          "refresh_token": { "type": "string" },
          "token_type": { "type": "string", "example": "Bearer" },
          "expires_in": { "type": "integer" }
        }
      }
    },
    "responses": {
      "BadRequestError": {
        "description": "Invalid parameters or payload",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "UnauthorizedError": {
        "description": "Authentication token missing, expired, or invalid",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      },
      "NotFoundError": {
        "description": "Requested resource not found",
        "content": {
          "application/problem+json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          },
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ProblemDetails" }
          }
        }
      }
    }
  }
}