REST API reference

VinTekh exposes a read-mostly REST API for SIEM ingest, ticketing integrations, and auditor pulls. Every endpoint is tenant-scoped via the bearer token + the same Prisma middleware that protects the UI.

Authentication

Send Authorization: Bearer vtk_live_<…> on every request. Issue keys at Settings → API keys; plaintext is shown once. Each key has a scope:

read — every read endpoint
scim — SCIM 2.0 user provisioning
audit — audit log pull
* — everything (admin scripts)

Rate limiting

Every /api/* path is rate-limited to 60 requests per 60 seconds per (client IP, path prefix). The SCIM and audit endpoints are excluded from rate limiting when called with a key bearing the corresponding scope — rotate keys not IPs for batch operations.

Endpoints

Method	Path	Description
GET	`/api/v1/findings`	List open findings; filter by severity, framework, source.
GET	`/api/v1/findings/{id}`	Single finding with blast-radius payload.
GET	`/api/v1/investigations`	List investigations.
GET	`/api/v1/investigations/{id}`	Investigation with evidence + recommendations.
GET	`/api/v1/recommendations`	List recommendations; filter by status.
GET	`/api/v1/audit-log`	Paginated audit events. Requires `audit` scope.
GET	`/api/v1/saved-views`	List saved filter recipes.
GET	`/api/v1/saved-views/{id}/execute`	Run a saved view; returns filtered findings.
GET	`/api/scim/v2/Users`	SCIM 2.0 list users. Requires `scim` scope. See SCIM guide.
POST	`/api/scim/v2/Users`	Provision user. `scim` scope.
GET	`/api/health`	Deep readiness probe (DB, Neo4j, Redis).
GET	`/health`	L7 liveness — dependency-free.

Pagination

REST endpoints accept ?limit=<n>&cursor=<c>. Default limit 50; max 200. Cursors are opaque; use the nextCursor in the response.

SCIM endpoints follow RFC 7644 pagination: ?startIndex=1&count=50 (1-based).

Error responses

Standard JSON: { "error": "<code>", "message": "<human>" } with appropriate HTTP status. SCIM endpoints return the SCIM-shape { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "detail": "<…>", "status": "<…>" }.

Webhooks (push)

Configure outbound webhooks at Settings → Webhooks. VinTekh POSTs JSON with an X-VinTekh-Signature HMAC-SHA256 header. Verify the signature with the shared secret you copied on creation.

Stability promise

During pilot, /api/v1 is stable for additive changes only; breaking changes go to /api/v2 with at least 30 days' deprecation notice surfaced in the response header X-VinTekh-Deprecation.