Authorization actor required to access this API operation.
MUST use camelCase. The actor name MUST match exactly with a user type/table defined in the database schema.
Set to null for public endpoints requiring no authentication.
Authorization type of the API operation.
"login": Credential validation operations"join": Account registration operations"refresh": Token renewal operationsnull: All other operationsAPI documentation for consumers. Describe the operation's purpose, business logic, relationships, and error handling.
Format: summary sentence first, \n\n, then paragraphs grouped by topic.
Reference DB schema table/column descriptions for consistency.
Do NOT use "soft delete" / "soft-delete" unless the operation actually implements soft deletion (triggers validation expecting soft_delete_column).
MUST be written in English. Never use other languages.
HTTP method (lowercase only).
Use patch (not get) when a read operation needs a complex
requestBody. get cannot have a request body.
Functional name of the API endpoint. MUST use camelCase.
MUST NOT be a JS/TS reserved word (delete, for, if, class,
return, new, this, void, const, let, var, async, await,
export, import, switch, case, throw, try). Use erase
instead of delete, iterate instead of for.
Standard names:
index: list/search (PATCH), at: get by ID (GET)create: POST, update: PUT, erase: DELETEAccessor uniqueness: the accessor is formed by joining non-parameter path
segments with dots, then appending the name. E.g., path
/shopping/sale/{saleId}/review/{reviewId} + name at = accessor
shopping.sale.review.at. Must be globally unique.
List of path parameters.
Each parameter name must correspond to a {paramName} in the
path.
HTTP path of the API operation.
Must start with /. Parameters use curly braces: {paramName}. Resource
names in camelCase. No quotes, spaces, role prefixes (/admin/), or API
version prefixes (/api/v1/).
Allowed characters: letters, digits, /, {, }, -, _, .
Prerequisites: API operations that must succeed before this one.
ONLY for business logic dependencies (resource existence, state checks,
data availability). NEVER for authentication -- use authorizationActor
instead.
Prerequisites are executed in array order; all must return 2xx before the main operation proceeds.
Request body of the API operation, or null if none.
Response body of the API operation, or null if none.
Internal implementation guidance for downstream agents (Realize, Test).
Describe HOW this operation should be implemented: service logic, DB queries, business rules, edge cases, and error handling.
MUST be written in English. Never use other languages.
Single API endpoint with method, path, parameters, and request/response.
All request/response bodies must be object types referencing named components. Content-type is always
application/json. For file upload/download, usestring & tags.Format<"uri">instead of binary.