12. Appendix A: Generic resource catalogue

Path segment is the value after /api/v1/. Mode: crud (read, create and update), read-only (read only; writes return 403 or 501), gated (not available; returns 501). "Any" read means any active role in the tenant. "FR" is the finance read set: PSA, CSA, PA, SCA, IA, FEO, FA, AC, EDV, IV.

Write roles below are the domain write permissions (WRITE_PERMISSIONS) that apply to the resource's kind. PSA can always write.

Path segment	Mode	Read roles	Create or update roles (domain)	Notes
organizations	crud	Any	CSA
programmes	crud	Any	CSA, PA
sapzs	crud	Any	CSA, PA, SCA
institutions	crud	Any	CSA, PA, SCA, IA
commodities	crud	Any	CSA, PA, SCA	Kind reference_data
value-chains	crud	Any	CSA, PA, SCA	Kind reference_data
risk-assessments	crud	Any	CSA, PA, SCA, IA, MA	Create forces status DRAFT; records assessedBy
indicators	crud	Any	CSA, PA, SCA, MA
reports	crud	Any	CSA, PA, SCA, IA, MA	Report definitions, not exports
benchmarks	gated	n/a	n/a	501 FEATURE_UNAVAILABLE
transactions	read-only	FR	n/a	Use /finance/transactions to create
disbursements	read-only	FR	n/a	Filtered to type DISBURSEMENT
reversals	read-only	FR	n/a	Filtered to type REVERSAL
approvals	read-only	FR	n/a
reconciliation	read-only	FR	n/a
investments	read-only	FR	n/a	Funding records, kind INVESTMENT
loans	read-only	FR	n/a	Funding records, kind LOAN
grants	read-only	FR	n/a	Funding records, kind GRANT
exports	read-only	Any (own rows only)	n/a	Requester's own report jobs
notifications	read-only	Any (own rows only)	n/a	Recipient's own notifications
integrations	read-only	PSA, CSA, SUPPORT, AC	n/a	Integration jobs; input, output, error redacted
admin/providers	read-only	PSA, CSA	Configure: CSA (or PSA). Route-level write returns 501 after authorization	Secrets rejected; only id, activeProvider, reason, version, expectedVersion accepted
audit-events	read-only	PSA, CSA, AC	n/a	Excludes integrity rows; hash fields redacted
facilities	read-only	FR	n/a	Authoritative facility register
facility-versions	read-only	FR	n/a
facility-windows	read-only	FR	n/a
facility-allocations	read-only	FR	n/a
finance-applications	read-only (route has its own POST and GET)	FR, with application scope	n/a	Use the dedicated routes
financing-cases	read-only (dedicated routes)	FR, with case scope	n/a	Use the dedicated routes
conditions-precedent	read-only	FR, case scope	n/a
collateral	read-only	FR, case scope	n/a
insurance	read-only	FR, case scope	n/a
insurance-claims	read-only	FR, policy scope	n/a
disbursement-schedules	read-only	FR, case scope	n/a
repayment-schedules	read-only	FR, case scope	n/a
warehouses	read-only	FR	n/a
warehouse-receipts	read-only	FR, warehouse scope	n/a
inventory	read-only	FR	n/a	Inventory lots
warehouse-inspections	read-only	FR	n/a
inventory-movements	read-only	FR	n/a
offtake-agreements	read-only	FR, case scope	n/a
delivery-obligations	read-only	FR, agreement scope	n/a
projects	read-only	FR, project scope	n/a
spvs	read-only	FR, project scope	n/a	Special purpose vehicles
ppps	read-only	FR, project scope	n/a
project-milestones	read-only	FR, project scope	n/a
project-preparation	read-only	FR, case scope	n/a
equity-investments	read-only	FR, case scope	n/a
guarantees	read-only	FR, case scope	n/a
restructurings	read-only	FR, case scope	n/a
recoveries	read-only	FR, case scope	n/a
beneficiary-profiles	read-only	FR, case scope	n/a

Field rules for the nine crud resources (create fields; * marks required):

Resource	Create fields	Update fields (plus id)
organizations	parentId (UUID, nullable), name* (string 240), type* (string 80), registrationNumber (string 120, nullable), status (enum), metadata (JSON)	parentId, name, type, registrationNumber, status, metadata
programmes	code* (code), name* (string 240), description (string 5,000, nullable), startsOn (date, nullable), endsOn (date, nullable), status (enum)	code, name, description, startsOn, endsOn, status
sapzs	programmeId* (UUID), stateId* (UUID), code* (code), name* (string 240), status (enum)	programmeId, stateId, code, name, status
institutions	organizationId (UUID, nullable), type* (string 80), name* (string 240), licenseNumber (string 120, nullable), status (enum)	organizationId, type, name, licenseNumber, status
commodities	code* (code), name* (string 160), unit (string 60, nullable)	code, name, unit
value-chains	commodityId (UUID, nullable), name* (string 160), stage (string 80, nullable)	commodityId, name, stage
risk-assessments	subjectType* (PROGRAMME, STATE, SAPZ, INSTITUTION, BENEFICIARY), subjectId* (UUID), score (integer 0 to 100), rating (string 60, nullable), status (enum; forced to DRAFT), factors (JSON), assessedAt (datetime, nullable)	score, rating, status, factors, assessedAt
indicators	code* (code), name* (string 200), unit* (string 80), dimensions (JSON)	code, name, unit, dimensions
reports	code* (code), name* (string 200), format* (PDF, XLSX, CSV), querySpec* (JSON), schedule (string 120, nullable), active (boolean)	code, name, format, querySpec, schedule, active

Example response from a read-only resource when the actor lacks a role (for example GET /api/v1/disbursements as MONITORING_ANALYST):

{
  "data": null,
  "error": { "code": "FORBIDDEN", "message": "You are not permitted to access this resource" },
  "requestId": "<request-id>"
}