API reference (Swagger)

Download the OpenAPI specification. Enable JavaScript for the interactive API explorer.

openapi: 3.0.3
info:
  title: Provantix API
  version: "1.0"
  description: |
    Complete API surface for the Provantix agent-telemetry control plane.

    Three authentication schemes coexist, by design:
    - **Session** (`/api/auth/*`, `/api/account/*`, `/api/members`, `/api/overview` and other
      product reads): bearer session token from sign-in. Held in memory by clients; 30-day lifetime.
    - **Emitter signature** (`POST /v1/batches`): ECDSA P-256 over the batch envelope. No bearer
      token travels with telemetry; routing is by emitter id.
    - **Org admin** (legacy/single-tenant `/api/emitters` and the engine's `/v1/*` surface):
      bearer admin token. In SaaS mode the platform derives this token from your session
      automatically, so product UI calls never handle it.

    Base URL: `https://app.provantix.tech`
servers:
  - url: https://app.provantix.tech
tags:
  - name: Auth
    description: Sign-up, sign-in, password reset, SSO
  - name: Account
    description: Organization, profile, members, billing
  - name: Emitters
    description: Signing identities for agent telemetry
  - name: Ingest
    description: Signed batch ingest
  - name: Agents
    description: Agent inventory and lifecycle
  - name: Records
    description: Event search and retrieval
  - name: Findings
    description: Persisted findings with status and history
  - name: Coverage
    description: Telemetry coverage and gaps
  - name: Export
    description: Evidence bundles and verification
  - name: Reporting
    description: Questions, dashboards and ad-hoc queries
  - name: Admin
    description: Operator-level provisioning
paths:
  /health:
    get:
      tags: [Admin]
      summary: Liveness probe
      security: []
      responses:
        "200":
          description: Service is up
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  mode: { type: string, example: saas }

  # ---- Auth ----
  /api/auth/config:
    get:
      tags: [Auth]
      summary: Public auth configuration
      description: Whether signup is open or invite-only, and whether SSO is enabled.
      security: []
      responses:
        "200":
          description: Auth configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  signup_mode: { type: string, enum: [open, invite] }
                  sso: { type: boolean }
  /api/auth/signup:
    post:
      tags: [Auth]
      summary: Create an account and organization
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password, org_name]
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
                org_name: { type: string }
                invite_code: { type: string, description: Required when signup_mode is invite }
      responses:
        "201":
          description: Account created; returns session token
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Session" }
        "400": { $ref: "#/components/responses/BadRequest" }
        "409": { $ref: "#/components/responses/Conflict" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /api/auth/login:
    post:
      tags: [Auth]
      summary: Sign in with email and password
      description: Returns a session token and, for accounts in multiple organizations, the org list.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, password]
              properties:
                email: { type: string, format: email }
                password: { type: string }
                org_id: { type: string, description: Required when the account belongs to more than one organization }
      responses:
        "200":
          description: Session token (and org list when ambiguous)
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Session" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /api/auth/logout:
    post:
      tags: [Auth]
      summary: Sign out (deletes the session server-side)
      security: [{ session: [] }]
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /api/auth/forgot-password:
    post:
      tags: [Auth]
      summary: Request a password-reset code
      description: Always returns 200 whether or not the email exists, to avoid account enumeration.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
        "429": { $ref: "#/components/responses/RateLimited" }
  /api/auth/reset-password:
    post:
      tags: [Auth]
      summary: Reset password with a code
      description: Verifies the emailed code, sets the new password, and revokes all sessions of the account.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, code, new_password]
              properties:
                email: { type: string, format: email }
                code: { type: string }
                new_password: { type: string, minLength: 8 }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
        "400": { $ref: "#/components/responses/BadRequest" }
  /api/auth/accept-invite:
    post:
      tags: [Auth]
      summary: Accept an organization invite
      description: For an existing account, requires that account to be signed in (A1c hardening); new accounts set a password.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code: { type: string }
                password: { type: string, description: Set only when creating a new account }
      responses:
        "200":
          description: Membership created; session for the invited org
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Session" }
        "401": { $ref: "#/components/responses/Unauthorized" }
        "410": { $ref: "#/components/responses/Gone" }
  /api/auth/sso/start:
    post:
      tags: [Auth]
      summary: Begin an SSO flow (Entra or Google OIDC)
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email, description: Work email; determines the identity provider and org }
      responses:
        "200":
          description: Redirect URL for the identity provider
          content:
            application/json:
              schema:
                type: object
                properties:
                  authorize_url: { type: string, format: uri }
        "400": { $ref: "#/components/responses/BadRequest" }
  /api/auth/sso/callback:
    get:
      tags: [Auth]
      summary: OIDC callback (browser redirect target)
      security: []
      parameters:
        - name: code
          in: query
          required: true
          schema: { type: string }
        - name: state
          in: query
          required: true
          schema: { type: string }
      responses:
        "302":
          description: Redirect back to the app with a one-time exchange code
  /api/auth/sso/exchange:
    post:
      tags: [Auth]
      summary: Exchange an SSO callback code for a session
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code: { type: string }
      responses:
        "200":
          description: Session token
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Session" }
        "401": { $ref: "#/components/responses/Unauthorized" }

  # ---- Account ----
  /api/account:
    get:
      tags: [Account]
      summary: Current user and organization
      security: [{ session: [] }]
      responses:
        "200":
          description: Account summary
          content:
            application/json:
              schema:
                type: object
                properties:
                  org: { $ref: "#/components/schemas/Org" }
                  user: { $ref: "#/components/schemas/User" }
  /api/account/password:
    post:
      tags: [Account]
      summary: Change password
      description: Rate-limited; revokes every existing session of the account except the current one.
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [current_password, new_password]
              properties:
                current_password: { type: string }
                new_password: { type: string, minLength: 8 }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
        "401": { $ref: "#/components/responses/Unauthorized" }
  /api/account/profile:
    patch:
      tags: [Account]
      summary: Update profile (display name)
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                display_name: { type: string }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /api/account/billing:
    get:
      tags: [Account]
      summary: Billing status and plans
      security: [{ session: [] }]
      responses:
        "200":
          description: Plans and current subscription
          content:
            application/json:
              schema:
                type: object
                properties:
                  configured: { type: boolean }
                  plans: { type: array, items: { $ref: "#/components/schemas/Plan" } }
                  subscription: { type: object, nullable: true }
  /api/account/billing/checkout:
    post:
      tags: [Account]
      summary: Create a Razorpay checkout for a plan
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [plan_id, cycle]
              properties:
                plan_id: { type: string }
                cycle: { type: string, enum: [monthly, annual] }
      responses:
        "200":
          description: Checkout identifiers
          content:
            application/json:
              schema:
                type: object
                properties:
                  order_id: { type: string }
                  key_id: { type: string }
  /api/account/sso:
    get:
      tags: [Account]
      summary: SSO configuration of the organization
      security: [{ session: [] }]
      responses:
        "200":
          description: Configured identity provider, if any
          content:
            application/json:
              schema: { $ref: "#/components/schemas/SsoConfig" }
    put:
      tags: [Account]
      summary: Configure SSO (Entra or Google OIDC)
      description: Domain verification is required before SSO is enabled.
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/SsoConfig" }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
        "400": { $ref: "#/components/responses/BadRequest" }

  # ---- Members ----
  /api/members:
    get:
      tags: [Account]
      summary: List organization members
      security: [{ session: [] }]
      responses:
        "200":
          description: Member list
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Member" }
  /api/members/invites:
    post:
      tags: [Account]
      summary: Invite a member (single-use, expiring, attempt-limited)
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email]
              properties:
                email: { type: string, format: email }
      responses:
        "201":
          description: Invite created; the code is shown once
          content:
            application/json:
              schema:
                type: object
                properties:
                  email: { type: string }
                  code: { type: string }
  /api/members/{userId}:
    delete:
      tags: [Account]
      summary: Remove a member (revokes their sessions for this org)
      security: [{ session: [] }]
      parameters:
        - name: userId
          in: path
          required: true
          schema: { type: string, pattern: "^usr_" }
      responses:
        "200": { $ref: "#/components/responses/Ok" }

  # ---- Emitters ----
  /api/account/emitters:
    post:
      tags: [Emitters]
      summary: Register an emitter
      description: Generates an ECDSA P-256 keypair and returns the private key exactly once, or accepts your public key (BYOK).
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string, description: Label, e.g. prod }
                public_key_pem: { type: string, description: BYOK public key (SPKI PEM). Omit to have the platform generate the keypair. }
      responses:
        "201":
          description: Emitter registered
          content:
            application/json:
              schema: { $ref: "#/components/schemas/EmitterRegistration" }
  /api/account/emitters/{emitterId}:
    delete:
      tags: [Emitters]
      summary: Revoke an emitter, or purge a revoked one
      description: |
        Without `purge`: marks the emitter revoked (idempotent). Ingest rejects revoked
        emitters with 403; historical batches stay verifiable.
        With `?purge=1`: hard-deletes a revoked emitter that never shipped a batch. Refused
        with 409 when batches exist.
      security: [{ session: [] }]
      parameters:
        - name: emitterId
          in: path
          required: true
          schema: { type: string, pattern: "^emi_" }
        - name: purge
          in: query
          schema: { type: integer, enum: [1] }
      responses:
        "200":
          description: Resulting status (revoked or deleted)
          content:
            application/json:
              schema:
                type: object
                properties:
                  emitter_id: { type: string }
                  status: { type: string, enum: [revoked, deleted] }
        "404": { $ref: "#/components/responses/NotFound" }
        "409": { $ref: "#/components/responses/Conflict" }
  /api/account/setup:
    get:
      tags: [Emitters]
      summary: Onboarding summary
      description: Organization, ingest endpoint, tenant id, emitter list with live counters, and SDK notes.
      security: [{ session: [] }]
      responses:
        "200":
          description: Everything the Setup page shows
          content:
            application/json:
              schema:
                type: object
                properties:
                  org: { $ref: "#/components/schemas/Org" }
                  ingest_base_url: { type: string, format: uri }
                  batches_endpoint: { type: string, format: uri }
                  tenant_id: { type: string }
                  emitters:
                    type: array
                    items: { $ref: "#/components/schemas/Emitter" }

  # ---- Ingest ----
  /v1/batches:
    post:
      tags: [Ingest]
      summary: Ship a signed batch of Agent Action Records
      description: |
        Authenticates by ECDSA signature, not bearer token. The envelope's `collector_id`
        routes the batch to the owning organization. `batch_seq` must increase by 1 per
        emitter. Schema-invalid records inside a valid batch are rejected individually and
        counted; valid records are still stored.
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: "#/components/schemas/BatchEnvelope" }
      responses:
        "200":
          description: Batch accepted
          content:
            application/json:
              schema:
                type: object
                properties:
                  accepted: { type: integer }
                  rejected: { type: integer }
                  batch_seq: { type: integer }
        "400": { $ref: "#/components/responses/BadRequest" }
        "401":
          description: Unknown emitter
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "403":
          description: Signature mismatch or emitter revoked
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "409":
          description: batch_seq duplicate or out of order
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Error" }
        "413": { $ref: "#/components/responses/TooLarge" }

  # ---- Product API (session) ----
  /api/overview:
    get:
      tags: [Records]
      summary: Home bundle
      description: Coverage, findings, agents, per-day and per-system counts, attribution rate, candidates, connectors, latest root, batch and gap tallies.
      security: [{ session: [] }]
      responses:
        "200": { description: Overview bundle }
  /api/records/search:
    get:
      tags: [Records]
      summary: Semantic search over record content
      description: Embedding similarity over stored event text; full-text search is on the roadmap.
      security: [{ session: [] }]
      parameters:
        - name: q
          in: query
          required: true
          schema: { type: string }
        - name: limit
          in: query
          schema: { type: integer, default: 50 }
      responses:
        "200":
          description: Ranked matches with similarity scores
  /api/agents/{agentId}/detail:
    get:
      tags: [Agents]
      summary: Agent detail bundle
      description: Agent record, identity mappings, reach, recent records, related findings.
      security: [{ session: [] }]
      parameters:
        - name: agentId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: Agent detail }
        "404": { $ref: "#/components/responses/NotFound" }
  /api/agents/{agentId}/risk-tier:
    post:
      tags: [Agents]
      summary: Set an agent's risk tier
      security: [{ session: [] }]
      parameters:
        - name: agentId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [risk_tier]
              properties:
                risk_tier: { type: string, enum: [low, medium, high, critical] }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /api/candidates/{principalId}/confirm:
    post:
      tags: [Agents]
      summary: Confirm a candidate identity as an agent
      security: [{ session: [] }]
      parameters:
        - name: principalId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [agent_id]
              properties:
                agent_id: { type: string }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /api/candidates/{principalId}/dismiss:
    post:
      tags: [Agents]
      summary: Dismiss a candidate
      security: [{ session: [] }]
      parameters:
        - name: principalId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                reason: { type: string }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /api/audit:
    get:
      tags: [Admin]
      summary: Admin audit log (register/revoke/delete emitter, member changes, sign-ins)
      security: [{ session: [] }]
      parameters:
        - name: limit
          in: query
          schema: { type: integer, default: 500 }
      responses:
        "200": { description: Audit entries }

  # ---- Engine /v1 (org-scoped; admin token in single-tenant, derived from session in SaaS) ----
  /v1/agents:
    get:
      tags: [Agents]
      summary: List agent records
      security: [{ orgAdmin: [] }]
      responses:
        "200":
          description: Agent records
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Agent" }
    post:
      tags: [Agents]
      summary: Create an agent record
      description: Matching `vendor` + `vendor_agent_id` attributes incoming telemetry at 0.95 confidence.
      security: [{ orgAdmin: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [display_name, vendor, vendor_agent_id]
              properties:
                display_name: { type: string }
                vendor: { type: string }
                vendor_agent_id: { type: string }
                owner: { type: string, description: Email of the accountable human or team }
      responses:
        "201": { description: Agent created }
  /v1/agents/{agentId}/owner:
    post:
      tags: [Agents]
      summary: Set the owning human or team
      security: [{ orgAdmin: [] }]
      parameters:
        - name: agentId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [owner]
              properties:
                owner: { type: string }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /v1/agents/{agentId}/lifecycle:
    post:
      tags: [Agents]
      summary: Move the agent to a lifecycle state
      description: Inventory labels only; no enforcement side effects anywhere.
      security: [{ orgAdmin: [] }]
      parameters:
        - name: agentId
          in: path
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [to]
              properties:
                to: { type: string, enum: [active, paused, deprecated, quarantined] }
                reason: { type: string }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /v1/findings:
    get:
      tags: [Findings]
      summary: List persisted findings
      security: [{ orgAdmin: [] }]
      responses:
        "200":
          description: Findings with status and history
          content:
            application/json:
              schema:
                type: array
                items: { $ref: "#/components/schemas/Finding" }
  /v1/findings/{findingId}:
    get:
      tags: [Findings]
      summary: One finding with full history
      security: [{ orgAdmin: [] }]
      parameters:
        - name: findingId
          in: path
          required: true
          schema: { type: string, pattern: "^fnd_" }
      responses:
        "200":
          description: Finding detail
          content:
            application/json:
              schema: { $ref: "#/components/schemas/Finding" }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/findings/run:
    post:
      tags: [Findings]
      summary: Run reconciliation now (otherwise scheduled)
      security: [{ orgAdmin: [] }]
      responses:
        "200":
          description: Run summary with per-rule counts
  /v1/findings/{findingId}/status:
    post:
      tags: [Findings]
      summary: Transition a finding's status
      description: Every transition appends to the finding's history with actor and reason.
      security: [{ orgAdmin: [] }]
      parameters:
        - name: findingId
          in: path
          required: true
          schema: { type: string, pattern: "^fnd_" }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [status]
              properties:
                status: { type: string, enum: [open, acknowledged, resolved] }
                reason: { type: string }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /v1/coverage:
    get:
      tags: [Coverage]
      summary: Coverage rollup per source system
      security: [{ orgAdmin: [] }]
      responses:
        "200": { description: Coverage rows with expected vs observed hours }
  /v1/candidates:
    get:
      tags: [Agents]
      summary: Unattributed identities awaiting review
      security: [{ orgAdmin: [] }]
      responses:
        "200": { description: Candidate list }
  /v1/gaps:
    get:
      tags: [Coverage]
      summary: Known chain and custody gaps
      security: [{ orgAdmin: [] }]
      responses:
        "200": { description: Gap list }
  /v1/timeline:
    get:
      tags: [Records]
      summary: Investigation timeline (records and gaps, newest first)
      security: [{ orgAdmin: [] }]
      parameters:
        - name: q
          in: query
          schema: { type: string, description: Optional semantic query }
      responses:
        "200": { description: Timeline rows }
  /v1/records/{recordId}:
    get:
      tags: [Records]
      summary: One record with full provenance and integrity fields
      security: [{ orgAdmin: [] }]
      parameters:
        - name: recordId
          in: path
          required: true
          schema: { type: string }
      responses:
        "200": { description: Record detail }
        "404": { $ref: "#/components/responses/NotFound" }
  /v1/connectors:
    get:
      tags: [Coverage]
      summary: List connector instances
      security: [{ orgAdmin: [] }]
      responses:
        "200": { description: Connector list }
    post:
      tags: [Coverage]
      summary: Register a connector instance
      security: [{ orgAdmin: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [instance_id, connector_slug, system]
              properties:
                instance_id: { type: string }
                connector_slug: { type: string }
                system: { type: string }
                status: { type: string }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /v1/exports:
    post:
      tags: [Export]
      summary: Build an evidence export bundle
      description: Attributed event chain, finding history, agent records with owners, and a manifest of custody hashes. JSON today; PDF on the roadmap.
      security: [{ orgAdmin: [] }]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                from: { type: string, format: date }
                to: { type: string, format: date }
                agent_id: { type: string }
      responses:
        "200":
          description: Export manifest and bundle location
  /v1/exports/verify:
    post:
      tags: [Export]
      summary: Re-verify an export bundle
      description: Re-hashes the bundle and compares against the manifest. Runs anywhere; the auditor needs no Provantix access.
      security: [{ orgAdmin: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [bundle]
              properties:
                bundle: { type: object }
      responses:
        "200":
          description: Verification result
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok: { type: boolean }
                  mismatches: { type: array, items: { type: string } }
  /v1/roots/{day}:
    post:
      tags: [Admin]
      summary: Seal a day's chains with a root (normally scheduled)
      description: Roots are write-once. A day becomes rootable 48 hours after it opens; open days are never rooted and rooted days reject new ingest.
      security: [{ orgAdmin: [] }]
      parameters:
        - name: day
          in: path
          required: true
          schema: { type: string, format: date, example: "2026-10-19" }
      responses:
        "200": { $ref: "#/components/responses/Ok" }
        "409": { $ref: "#/components/responses/Conflict" }

  # ---- Reporting ----
  /api/reporting/schema:
    get:
      tags: [Reporting]
      summary: Queryable tables, columns and joins
      security: [{ session: [] }]
      responses:
        "200": { description: Schema description }
  /api/reporting/query:
    post:
      tags: [Reporting]
      summary: Run an ad-hoc query
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [table]
              properties:
                table: { type: string }
                filters: { type: array, items: { type: object } }
                summarize: { type: object }
                viz: { type: string, enum: [table, scalar, bar, line, pie] }
      responses:
        "200": { description: Rows and optional visualization shape }
  /api/reporting/questions:
    get:
      tags: [Reporting]
      summary: List saved questions
      security: [{ session: [] }]
      responses:
        "200": { description: Saved questions }
    post:
      tags: [Reporting]
      summary: Save a question
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                table: { type: string }
                filters: { type: array }
                summarize: { type: object }
                viz: { type: string }
      responses:
        "201": { description: Created question }
  /api/reporting/questions/{questionId}:
    get:
      tags: [Reporting]
      summary: One saved question
      security: [{ session: [] }]
      parameters: [{ name: questionId, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { description: Question }
        "404": { $ref: "#/components/responses/NotFound" }
    put:
      tags: [Reporting]
      summary: Update a saved question
      security: [{ session: [] }]
      parameters: [{ name: questionId, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { $ref: "#/components/responses/Ok" }
    delete:
      tags: [Reporting]
      summary: Delete a saved question
      security: [{ session: [] }]
      parameters: [{ name: questionId, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /api/reporting/dashboards:
    get:
      tags: [Reporting]
      summary: List dashboards
      security: [{ session: [] }]
      responses:
        "200": { description: Dashboards }
    post:
      tags: [Reporting]
      summary: Create a dashboard
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [name]
              properties:
                name: { type: string }
      responses:
        "201": { description: Created dashboard }
  /api/reporting/dashboards/{dashboardId}:
    get:
      tags: [Reporting]
      summary: One dashboard with its cards
      security: [{ session: [] }]
      parameters: [{ name: dashboardId, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { description: Dashboard with cards }
        "404": { $ref: "#/components/responses/NotFound" }
    delete:
      tags: [Reporting]
      summary: Delete a dashboard
      security: [{ session: [] }]
      parameters: [{ name: dashboardId, in: path, required: true, schema: { type: string } }]
      responses:
        "200": { $ref: "#/components/responses/Ok" }
  /api/reporting/dashboards/{dashboardId}/cards:
    post:
      tags: [Reporting]
      summary: Add a card (a saved question rendered on the dashboard)
      security: [{ session: [] }]
      parameters: [{ name: dashboardId, in: path, required: true, schema: { type: string } }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [question_id]
              properties:
                question_id: { type: string }
                position: { type: integer }
      responses:
        "201": { description: Card added }
  /api/reporting/dashboards/{dashboardId}/cards/{cardId}:
    delete:
      tags: [Reporting]
      summary: Remove a card
      security: [{ session: [] }]
      parameters:
        - { name: dashboardId, in: path, required: true, schema: { type: string } }
        - { name: cardId, in: path, required: true, schema: { type: string } }
      responses:
        "200": { $ref: "#/components/responses/Ok" }

  # ---- Operator ----
  /api/admin/invites:
    post:
      tags: [Admin]
      summary: Issue a platform-level invite code (operator only)
      security: [{ session: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                note: { type: string }
      responses:
        "201": { description: Invite code, shown once }

components:
  securitySchemes:
    session:
      type: http
      scheme: bearer
      bearerFormat: session token
      description: From POST /api/auth/login or /api/auth/signup. 30-day lifetime.
    orgAdmin:
      type: http
      scheme: bearer
      bearerFormat: admin token
      description: Single-tenant admin token. In SaaS mode the platform derives it from your session automatically.
  schemas:
    Error:
      type: object
      properties:
        error: { type: string }
    Session:
      type: object
      properties:
        token: { type: string }
        user: { $ref: "#/components/schemas/User" }
        orgs:
          type: array
          description: Present when the account belongs to more than one organization; the client must pick.
          items: { $ref: "#/components/schemas/Org" }
    User:
      type: object
      properties:
        user_id: { type: string }
        email: { type: string, format: email }
        display_name: { type: string }
    Org:
      type: object
      properties:
        org_id: { type: string }
        name: { type: string }
        tenant_id: { type: string }
        created_at: { type: string, format: date-time }
    Member:
      type: object
      properties:
        user_id: { type: string }
        email: { type: string }
        role: { type: string, enum: [admin, member] }
        joined_at: { type: string, format: date-time }
    Plan:
      type: object
      properties:
        id: { type: string }
        name: { type: string }
        price_monthly_inr: { type: integer }
        price_annual_inr: { type: integer }
    SsoConfig:
      type: object
      properties:
        provider: { type: string, enum: [entra, google], nullable: true }
        domain: { type: string, nullable: true }
        client_id: { type: string, nullable: true }
        tenant_id: { type: string, description: Entra tenant id, nullable: true }
        verified: { type: boolean }
    Emitter:
      type: object
      properties:
        emitter_id: { type: string }
        connector_instance: { type: string }
        status: { type: string, enum: [active, revoked] }
        registered_at: { type: string, format: date-time }
        last_batch_seq: { type: integer }
        records_shipped: { type: integer }
    EmitterRegistration:
      allOf:
        - $ref: "#/components/schemas/Emitter"
        - type: object
          properties:
            tenant_id: { type: string }
            name: { type: string, nullable: true }
            batches_endpoint: { type: string, example: /v1/batches }
            key_source: { type: string, enum: [generated, customer] }
            public_key_pem: { type: string }
            private_key_pem: { type: string, nullable: true, description: Generated keys only; shown exactly once }
    Agent:
      type: object
      properties:
        agent_id: { type: string }
        display_name: { type: string }
        vendor: { type: string }
        vendor_agent_id: { type: string }
        owner: { type: string, nullable: true }
        lifecycle: { type: string, enum: [active, paused, deprecated, quarantined] }
        risk_tier: { type: string, enum: [low, medium, high, critical] }
        created_at: { type: string, format: date-time }
    Finding:
      type: object
      properties:
        finding_id: { type: string }
        rule: { type: string }
        severity: { type: string, enum: [info, low, medium, high, critical] }
        status: { type: string, enum: [open, acknowledged, resolved, stale] }
        subject: { type: object }
        detail: { type: string }
        recommendation: { type: string }
        first_seen: { type: string, format: date-time }
        record_ids: { type: array, items: { type: string } }
        history:
          type: array
          items:
            type: object
            properties:
              at: { type: string, format: date-time }
              from_status: { type: string, nullable: true }
              to_status: { type: string }
              reason: { type: string, nullable: true }
              actor: { type: string }
    AAR:
      type: object
      required: [profile_version, event_id, tenant_id, emitter_id, observed_at, system, agent, action]
      properties:
        profile_version: { type: string, example: "1.0" }
        event_id: { type: string }
        tenant_id: { type: string }
        emitter_id: { type: string }
        observed_at: { type: string, format: date-time }
        system: { type: string, example: internal-tools }
        vantage: { type: string, enum: [inside, boundary, destination, identity] }
        agent:
          type: object
          properties:
            vendor: { type: string }
            vendor_agent_id: { type: string }
            version: { type: string }
            principal: { type: string }
            client_id: { type: string }
            token_actor: { type: string }
        action:
          type: object
          required: [action_type]
          properties:
            action_type:
              type: string
              enum: [read, write, create, update, delete, send, execute, approve, escalate, call_model, call_tool, call_agent, login, grant, revoke, download, upload, unknown]
            target_system: { type: string }
            target_entity_type: { type: string }
            target_entity_id: { type: string }
            operation: { type: string }
            tool_name: { type: string }
            field_names: { type: array, items: { type: string } }
            data_classes:
              type: array
              items:
                type: string
                enum: [pii, phi, pci, financial, hr, secret, customer, internal, public, unknown]
            external_recipient: { type: string }
        data: { type: object }
        model: { type: object }
        correlation: { type: object }
        quality: { type: object }
    BatchEnvelope:
      type: object
      required: [collector_id, tenant_id, batch_seq, records, signature]
      properties:
        collector_id: { type: string, description: Emitter id; routes the batch to the owning organization }
        tenant_id: { type: string }
        batch_seq: { type: integer, minimum: 1, description: Strictly increasing per emitter }
        records:
          type: array
          items: { $ref: "#/components/schemas/AAR" }
        signature:
          type: string
          description: Base64 detached ECDSA P-256 (SHA-256) signature over the canonical envelope without this field
  responses:
    Ok:
      description: Success
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    BadRequest:
      description: Malformed request or schema-invalid payload
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Unauthorized:
      description: Missing or invalid credentials
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Conflict:
      description: State conflict (duplicate, already exists, sequence out of order)
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    Gone:
      description: Invite expired or used
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    RateLimited:
      description: Too many attempts; back off
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }
    TooLarge:
      description: Payload over the 10 MB limit
      content:
        application/json:
          schema: { $ref: "#/components/schemas/Error" }