digital-psychology/.ai/api.md

API — Golden Rules

Style

• REST only for public HTTP.
• Never use POST for pure queries (use GET).
• Verbs: GET / POST / PUT / DELETE.
• Prefix: /api/v1.

Envelope (mandatory — never invent alternatives)

Success:

{ "code": 0, "message": "success", "data": {} }

Error:

{ "code": 10001, "message": "user not found" }

Forbidden shapes: { success: true }, { ok: true }, bare arrays as root.

Error codes

• Start business codes at 10000.
• 0 = success.
• Ranges: 1xxxx general/auth, 2xxxx profile, 3xxxx report/scale, 4xxxx order/membership, 5xxxx AI/companion.

Pagination

Query: page, page_size
Data:

{ "list": [], "total": 0, "page": 1, "page_size": 20 }

Auth

• Bearer token in Authorization header when required.
• Resource ownership checked in service layer.

Docs

• Public route changes update proto/openapi.yaml in the same change set.
• Do not invent endpoints that are not in OpenAPI / task spec.