API conventions

1VEC's API comes in two kinds: internal and public. Internal APIs serve only our own frontends and can change as needed; public APIs are an external contract — versioned and backward-compatible.

Version prefixes / planes

Breaking changes to public APIs must go through a new version (v2) with a deprecation notice and a transition window — never changed in place.

Unified response

{ "code": 0, "data": { /* ... */ }, "message": "ok" }

• code: the business error code, 0 = success; failures use 4xxxx, kept separate from the HTTP status code.
• Lists return { items, page, pageSize, total }, with pageSize ≤ 100.
• Accept-Language controls the response language, defaulting to zh-CN.

Auth

• Session (frontend): after OIDC sign-in, 1VEC issues its own JWT.
• API key (programs / third parties / MCP): Authorization: Bearer <key>. A key is scoped to an org + authorized projects + a role (not super).

curl https://<your-host>/api/public/v1/issues \
  -H "Authorization: Bearer $ONEVEC_API_KEY"

Error code ranges

The public API and SDK are still being finalized; treat actual responses as authoritative. A full endpoint list will be added once the stable version ships.