Reference

API overview

Tiyi exposes one ConnectRPC API. The same proto schema serves the Vben Admin UI (JSON over HTTP), the tiyi CLI (JSON over HTTP), and the agent stream (gRPC bidi). One source of truth at proto/tiyi/v1/*.proto means the CLI and API stay in lockstep by construction.

Transport

JSON for UI and CLI clients. Default Content-Type: application/json; URLs follow the ConnectRPC convention /{service}/{Method}.
gRPC for the agent bidi stream and any other client that prefers binary.
Connect-Web for the embedded Vben UI — no separate REST shim, no separate gateway.

Authentication

Three auth surfaces, picked by deployment context:

Surface	Mechanism	Used by
Local admin socket	OS file permissions on `admin.sock`	`tiyi` CLI on the same host as the server.
HS256 JWT	`Authorization: Bearer <jwt>` over HTTP	Vben Admin UI, remote CLI, anything driving the API from off-host. Issued by `AuthService.Login`; refreshed by `RefreshToken`.
Agent stream token	One-use enrollment token → long-lived stream token	Agents on the bidi `AgentStream`. Tokens are issued through `AgentService.IssueEnrollmentToken`.

$ curl -sS http://primary:8080/tiyi.v1.AuthService/Login \
    -H "Content-Type: application/json" \
    -d '{"username":"admin","password":"..."}'
{
  "accessToken": "<jwt>",
  "refreshToken": "<refresh>",
  "user": { "id": "<uuid>", "role": "Administrator" }
}

The 14 services

Service	Scope
`SystemService`	Health, version, dashboard rollups, settings, releases, replication, promote/demote.
`AuthService`	Login, logout, refresh, current user, OIDC redirect, access codes.
`UserService`	User CRUD, lock/unlock, password reset.
`RoleService`	Role + permission lookup. RBAC table is built-in.
`SiteService`	Site CRUD, enable/disable, preview, per-site policy override.
`UpstreamService`	Upstream pool CRUD; deletion refused while in use.
`CertService`	Upload, ACME issue/renew, DNS provider CRUD.
`PolicyService`	WAF policy CRUD, layer updates, version snapshots, SecLang preview, test lab.
`RuleOverrideService`	Per-rule overrides, custom rules, IP lists, rate-limit endpoints.
`CrsService`	CRS catalog browse + ingest + exclusion-package install/attach.
`AgentService`	Agent CRUD, enrollment tokens, install scripts, commands, agent groups, `AgentStream`.
`TrustService`	Client-IP trust profile (tenant + site overrides), CDN snapshot list/refresh, explain.
`AlertService`	Alert rule + channel CRUD, active alert ack/resolve, channel test send.
`LogService`	Security/access/error/audit query, get, export, live tail.

Error codes

Tiyi returns standard ConnectRPC error codes mapped from gRPC. The CLI and UI surface localized messages on top of the canonical code:

Code	HTTP	Typical cause
`invalid_argument`	400	Bad input shape or value rejected by the validator.
`unauthenticated`	401	Missing or invalid JWT.
`permission_denied`	403	JWT lacks the required RBAC permission.
`not_found`	404	Resource id does not exist or is soft-deleted.
`already_exists`	409	Unique constraint violated (site name, policy name, etc.).
`failed_precondition`	412	Revision conflict, `UPSTREAM_IN_USE`, replication-lag gate, etc.
`unimplemented`	501	RPC not yet wired (rare — the `2026-05-26` changelog entry closed the last batch).
`internal`	500	Server-side bug or infrastructure failure. Audit chain receives a row when relevant.

RBAC

Each RPC declares a required permission like site:read, policy:write, log:read, system:write. The middleware checks the JWT subject's roles against the permission table; the canonical mapping lives in internal/api/middleware.go. There are 52 fine-grained permissions in v3.0.0-rc.1.

Streaming RPCs

AgentService.AgentStream — long-lived bidi stream. Agent sends Hello, StateReport, AgentEventPush, ApplyResult, ChallengeResponse. Server sends Welcome, ConfigUpdate, Command, ChallengeDispatch.
AlertService.StreamAlerts — server-streaming. Pushes alert lifecycle events to the dashboard with reconnect-with-backoff on the client side.
AgentService.StreamAgentEvents — server-streaming. Live agent state (online/offline, metrics).
LogService.TailSecurityEvents — server-streaming. Live security log feed for the live-tail page.
SystemService.StreamUpgradeRun — server-streaming. Per-agent upgrade run progress events.

Canonical spec

The PRD-API document in the source tree is the canonical per-RPC spec. It enumerates every method's request/response shape, RBAC permission, error codes, and audit-row contract. These docs cover the operator surface; that doc covers the API contract. They should agree — file an issue if they don't.

For a generated reference, regenerate Connect Go and Protobuf Go from proto/:

$ make proto
$ ls internal/api/gen/tiyi/v1/
# <service>.pb.go and <service>.connect.go for each .proto file