REST API conventions

All product APIs use /api/v1 and a shared response envelope.

Module routes live under /api/v1/<module-key>/*. Control-plane APIs use /api/v1/control/*. Never bypass versioning — clients depend on stable error.code values.

Success envelope

{
  "success": true,
  "data": [{ "id": "rec_01", "name": "Example" }],
  "meta": {
    "pagination": { "page": 1, "pageSize": 25, "total": 1, "totalPages": 1 }
  }
}

Error envelope

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Missing permission my-integration.records:read"
  },
  "meta": {}
}

Pagination

List endpoints accept page, pageSize, sort, and order. Totals appear in meta.pagination.

Implementation checklist

• Zod-validate every request body and query shape.
• Enforce tenant id on every Core query (defense in depth).
• Check module permissions in middleware, not only in UI.
• Audit-log creates, updates, deletes, and auth-sensitive reads.