API

REST API reference

Programmatic access to agents, licenses, configuration, alerts, flows, and reports. Base URL: /api/v1

API v1

TRIVLA REST API

Authenticate with a bearer token from the portal (Settings → API keys). All requests use JSON and HTTPS.

curl example

curl -H "Authorization: Bearer trvl_api_xxxx" \
     https://portal.trivla.com/api/v1/agents

Authentication

POST/api/v1/auth/login

Email/password login. Returns JWT access and refresh tokens. Google OAuth uses /api/v1/auth/google.

Agents

GET/api/v1/agents

List registered agents with status, version, last seen, and license state.

POST/api/v1/agents/register

Agent self-registration with license key, hostname, OS, and capabilities.

Licenses

GET/api/v1/licenses

List license keys, seat usage, and expiration.

POST/api/v1/licenses/validate

Validate a license key. Called by agents on startup and periodically.

Flows & analytics

GET/api/v1/flows?from=&to=&agent_id=

Query network flows from StarRocks. Supports filters for protocol, application, IP, and country.

GET/api/v1/flows/voip/calls

SIP call list, ladder, and Homer-style dialog state. Live cache when agents are exporting SIP telemetry.

Alerts

GET/api/v1/alerts

List security and operational alerts. Filter by severity, agent, and time range.

POST/api/v1/alerts/ingest

Agent alert ingestion endpoint. Used internally by agents; documented for custom integrations.

Configuration

GET/api/v1/config/agent_id

Fetch firewall rules, threat feed settings, and capture policy for an agent.

ℹ

Full OpenAPI 3.0 specification will ship with the open-source portal repository. This reference covers the core endpoints used by agents and integrations.