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" }