API conventions

Every StackRivet endpoint — including the ones the code generator emits — follows the same conventions, under the base path /api/v1. The exhaustive endpoint catalog is the OpenAPI 3.1 document generated by the running app; this page is the contract those endpoints share.

# Fresh local database only — use the local seed, never hosted-demo credentials.
STACKRIVET_LOCAL_ADMIN_PASSWORD=stackrivet2026
TOKEN=$(curl -s http://127.0.0.1:8080/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d "{\"username\":\"admin\",\"password\":\"${STACKRIVET_LOCAL_ADMIN_PASSWORD}\"}" | jq -r '.data.accessToken')

curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8080/v3/api-docs
unset STACKRIVET_LOCAL_ADMIN_PASSWORD TOKEN

If you do not have jq, copy data.accessToken from the login response. This example deliberately targets 127.0.0.1; do not reuse the local seed password for the hosted demo or a deployed instance. Hosted-demo access, when available, is published separately on its sign-in page.

Response envelope

Every response is wrapped, with a traceId you can correlate to server logs:

{ "code": "0", "message": "OK", "data": {}, "traceId": "01J..." }

code: "0" means success. The HTTP status is also meaningful (StackRivet does not collapse everything to 200) — code is the stable, machine-branchable contract; HTTP status is the transport-level signal.

A paginated data:

{ "items": [], "page": 1, "pageSize": 20, "total": 0 }

HTTP status

Status	When
200 / 201	success / created
400	bad parameters
401 / 403	unauthenticated / unauthorized
404	not found
409	state / unique-key / version conflict
413 / 415	upload too large / unsupported type
429	rate limited
500	server error

Error codes

The error code is a stable, never-localized contract — clients branch on it. The wire format is {PREFIX}_{REASON}_{HTTP}:

{ "code": "SYSTEM_USER_DUPLICATED_409", "message": "...", "details": [], "traceId": "01J..." }

Prefixes include AUTH, PERM, VALIDATION, SYSTEM, ASSET, SIGNED_URL, GENERATOR, TASK. All codes come from the ErrorCode registry in stackrivet-common; the message is localized by Accept-Language (falling back to English), but the code is not. A build-time gate keeps every code’s English and Chinese message in sync.

Pagination & sorting

Param	Default	Details
page	1	1-based
pageSize	20	max 200
sort	—	e.g. createdAt,desc; whitelisted fields only

sort accepts only whitelisted fields — arbitrary SQL columns are never passed through.

Types

• Timestamps are ISO 8601 strings.
• Precision-sensitive values (money, ratios) are strings or integer minor units — never a float.
• Enums are lowercase strings; booleans are JSON booleans; IDs are strings.

Headers

Authorization: Bearer <access_token>
X-Request-Id: optional-client-request-id

• Tokens are short-lived and revocable; a forced logout invalidates the old token. Tokens never appear in logs.
• Send an idempotency key only where the endpoint explicitly documents support for it. Task submission carries idempotencyKey in the JSON body so retries do not duplicate the same job.
• Task submission returns 201 with the task resource; run, cancel and retry are explicit task actions. Track task state via tasks.

API groups

OpenAPI tags map to path prefixes: Auth (/auth), Me (/me), Users, Departments, Posts, Roles, Menus, Dictionaries, Params, Audit, Assets, Generator, Tasks, System — all under /api/v1.