API Reference

Client-facing REST API reference for VertexY.

Base URL

plaintext
https://api.vertexY.com/api

Authentication summary

  1. Bearer access token Used by most authenticated endpoints.
  2. Bearer refresh token Used by POST /auth/refresh.
  3. HMAC signature headers Used by POST /events/ingest.
  4. Public access Used by POST /auth/register-company-admin, POST /auth/login, and POST /billing/lemon-squeezy/webhook.

Roles and access

Some endpoints are limited by:

  • authenticated role (admin, analyst)
  • active subscription
  • plan features

This reference focuses on client-facing tenant endpoints. Superadmin control-plane endpoints are intentionally not covered here.

Auth endpoints

  1. POST /auth/register-company-admin Public. Creates a company and its first admin.
  2. POST /auth/login Public. Returns access and refresh tokens.
  3. POST /auth/refresh Uses a refresh token. Rotates access and refresh tokens.
  4. POST /auth/logout Uses a bearer token. Invalidates the current session.
  5. POST /auth/webhook-secret/regenerate Bearer admin. Rotates the event signing secret.
  6. POST /auth/webhook-secret/status Bearer admin. Checks whether a secret is configured.

Subscriptions

  1. GET /subscriptions/me Bearer admin. Fetches the current active subscription.
  2. GET /subscriptions/me/usage Bearer admin. Fetches monthly usage.

Event ingestion

  1. POST /events/ingest Uses HMAC signing. Ingests one signed platform event and returns an assessment.

Risk engine

  1. POST /risk-engine/assess Bearer token. Runs real-time risk scoring.
  2. POST /risk-engine/feedback Bearer token. Submits outcome feedback.
  3. GET /risk-engine/evaluations Bearer token plus feature access. Lists stored evaluations.
  4. GET /risk-engine/evaluations/:evaluationId Bearer token plus feature access. Fetches one evaluation.
  5. GET /risk-engine/analytics/summary Bearer token. Returns summary analytics.
  6. GET /risk-engine/analytics/time-series Bearer token. Returns time-series analytics.
  7. GET /risk-engine/analytics/score-distribution Bearer token. Returns score distribution analytics.
  8. GET /risk-engine/analytics/reason-codes Bearer token. Returns reason-code leaderboard analytics.
  9. GET /risk-engine/analytics/recent-blocks Bearer token. Returns recently blocked transactions.
  10. GET /risk-engine/policy Bearer admin. Reads the current policy.
  11. PUT /risk-engine/policy Bearer admin. Updates the policy.

Reviews

  1. GET /reviews Bearer admin or analyst plus feature access. Lists reviews.
  2. GET /reviews/:id Bearer admin or analyst plus feature access. Fetches one review.
  3. POST /reviews Bearer admin or analyst plus feature access. Creates a review.
  4. PATCH /reviews/status Bearer admin or analyst plus feature access. Updates review status.

Graph explorer

  1. GET /graph/explore/:id Bearer token plus feature access. Builds an assessment-anchored graph neighborhood.

Audit logs

  1. GET /audit-logs Bearer admin plus feature access. Lists tenant audit logs.

Threat intelligence

  1. POST /threat-intel/subscriptions Bearer admin plus feature access. Creates an outbound threat webhook subscription.
  2. GET /threat-intel/subscriptions Bearer admin plus feature access. Lists subscriptions.
  3. DELETE /threat-intel/subscriptions/:subscriptionId Bearer admin plus feature access. Removes a subscription.

Common query parameters

Pagination

Many list endpoints accept:

  1. page Integer. Default is 1.
  2. limit Integer. Default depends on the endpoint.

Evaluation list filters

GET /risk-engine/evaluations supports:

  1. action allow, review, or block.
  2. riskLevel low, medium, high, or critical.
  3. from ISO 8601 datetime.
  4. to ISO 8601 datetime.
  5. search Free-text transaction search.
  6. sort field:direction.
  7. requireUserId Boolean.

Next reference pages