Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AllianceBioversityCIAT/onecgiar_pr/llms.txt

Use this file to discover all available pages before exploring further.

The administration surfaces in PRMS span several independent API groups, each serving a distinct operational concern. Most endpoints require a valid JWT in the custom auth header (not an Authorization: Bearer prefix). Write operations on globally impactful resources additionally require the Admin (RoleEnum.ADMIN = 1) or Lead (RoleEnum.LEAD = 3) role enforced by ValidRoleGuard.
Admin endpoints that modify global parameters, delete results, or change runtime configuration have portfolio-wide or irreversible effects. Always verify the scope of an operation before calling these endpoints in production.
The role hierarchy is numeric — lower values represent greater privilege:
RoleIDScope
Admin1Full administrative access across all modules
Lead3Initiative lead; limited admin operations
Co-Lead4Co-lead on an initiative
Coordinator5Initiative coordinator
Member6Standard initiative member
Guest2Read-only access
Action Area Global Director7Action area oversight
Action Area Coordinator8Action area coordination
ValidRoleGuard authorizes a request when userRole <= requiredRole — a user with a lower ID (higher privilege) always satisfies a role requirement for a higher ID.
The ad-users endpoints expose the CGIAR Active Directory via a local cache backed by ldapts. Results are returned from the cache first; AD is queried only on a cache miss. Use these endpoints to look up and validate users before assigning them roles on initiatives.Auth: JWT required. No additional role guard — all authenticated users may call these endpoints.

​
Search users

GET /api/ad-users/search
Searches for users by name, email, username, title, department, or company. The query is applied against the local cache first; an AD lookup is performed if the cache has no matching results.
​
query
string
required
Search string. Minimum 2 characters. Searches across name, email, username, title, department, and company fields.Example: john.doe
Response: 200 with a SearchUsersResponseDto containing matched user records. 400 if query is shorter than 2 characters.

​
Validate an email address

GET /api/ad-users/validate
Checks whether an email address exists in Active Directory and returns the user’s details if found. Use this to confirm a lead contact person before saving their details to a result.
​
email
string
required
Email address to validate. Example: [email protected]
Response: 200 with a ValidateEmailResponseDto. 400 if the email parameter is missing.
Global parameters are runtime-tunable key-value pairs stored in the global_parameters table. They control platform-wide behaviour such as feature flags, thresholds, and system text. Values are cached in-process by GlobalParameterCacheService; writing a parameter via PUT /api/global-parameters/update/variable invalidates the cache.Auth: JWT required for all endpoints. Write operations should be restricted to admin users — there is no explicit role guard on these endpoints, so callers must ensure access control at the application level.

​
List all parameters

GET /api/global-parameters
Returns every global parameter record including id, name, description, value, and global_parameter_category_id.

​
Get parameters by category

GET /api/global-parameters/category/:categoryId
Returns all parameters belonging to a given category.
​
categoryId
number
required
Category ID from the global_parameter_category table.

​
Get platform global variables

GET /api/global-parameters/platform/global/variables
Returns the subset of global parameters that apply across the entire PRMS platform. Use this endpoint to retrieve configuration values needed by the frontend on startup.

​
Get parameter by name

GET /api/global-parameters/name/:name
Looks up a single parameter by its unique name (up to 64 characters, unique index in the database).
​
name
string
required
Exact parameter name as stored in global_parameters.name.

​
Update a parameter

PUT /api/global-parameters/update/variable
Updates the value of an existing global parameter and invalidates the in-process cache. The calling user is recorded in the audit columns.
​
name
string
required
Name of the parameter to update.
​
value
string
required
New value to persist. All parameter values are stored as text regardless of their semantic type.
Parameter changes take effect immediately across all running server instances (the cache is invalidated synchronously). Incorrect values can break platform-wide features. Test in a non-production environment first.
The manage-data endpoints provide soft-delete and result-type migration operations. Deletion is tracked in the result_deletion_audit table; recovery is possible by reversing the soft-delete flag. These endpoints are restricted to admin and PMU users.Auth: JWT required. Admin or lead access expected — ValidRoleGuard is applied per operation.

​
Soft-delete a result

DELETE /api/manage-data/result/:id/delete
Marks a result as deleted (is_active = false) and creates an audit record in result_deletion_audit. The result is hidden from all standard queries but remains in the database and can be recovered.
​
id
number
required
Result ID to soft-delete.
​
justification
string
Optional free-text reason for deletion. Stored in the audit record.
Although soft-deletes are technically reversible, all linked data (contributions, evidence, partners, budget entries) is also deactivated. Recovery requires a manual re-activation flow — contact the PMU team before proceeding.

​
Change a result type

PATCH /api/manage-data/change/result/:id
Migrates a result from one type/level combination to another. This operation re-classifies the result and may clear type-specific data that is incompatible with the new type. A justification is required.
​
id
number
required
Result ID to reclassify.
Request body:
​
result_level_id
number
required
Target result level ID (for example Output, Outcome).
​
result_type_id
number
required
Target result type ID matching ResultTypeEnum (for example 1 = Policy Change, 7 = Innovation Development).
​
justification
string
required
Reason for the type change. Stored in the audit trail.
​
new_name
string
Optional new title for the result after reclassification.
Changing a result type is not fully reversible. Type-specific fields populated under the old type may be permanently cleared. Confirm with the result owner before proceeding.
Global narratives are PMU-curated text blocks stored in the global_narratives table. Each narrative has a unique name slug and a value field containing the narrative content. These are read by the frontend to populate shared narrative sections in reports.Auth: JWT required. These are read-only endpoints — write access to narratives must be performed directly by the PMU team via database tooling or a separate admin interface.

​
Get narrative by ID

GET /api/global-narratives/:id
Returns a single global narrative by its primary key.
​
id
number
required
Narrative ID (global_narratives.id).
Response fields:
​
id
number
Primary key.
​
name
string
Unique slug identifying the narrative block (up to 255 characters).
​
value
string
Full narrative text content.
​
is_active
boolean
Whether the narrative is active. Inactive narratives are excluded from standard queries.
​
created_date
string
ISO timestamp of creation.
​
last_updated_date
string
ISO timestamp of last modification.

​
Get narrative by name

GET /api/global-narratives/name/:name
Looks up a narrative by its unique name slug. Prefer this endpoint when the frontend references narratives by a known identifier rather than a database ID.
​
name
string
required
Unique name slug for the narrative.
The initiative entity map defines which organizational entities (for example, centers or partners) are associated with each CGIAR initiative. These mappings govern contribution eligibility and data access rules across the platform.Auth: JWT required. The calling user’s token is used for audit purposes on write operations.

​
Get all mappings

GET /api/initiatives-entity
Returns all current initiative-to-entity mappings, including the related initiative and entity objects.Response: 200 with an array of InitiativeEntityMap records containing each mapping’s initiativeId, entityIds, and related objects.
POST /api/initiatives-entity/link
Creates or updates the entity associations for an initiative. Accepts a single initiative ID and a list of entity IDs; the service saves the full set of mappings atomically.Auth: JWT required. User token is recorded in audit columns.Request body:
​
initiativeId
number
required
ID of the CGIAR initiative to configure. Example: 1
​
entityIds
number[]
required
Array of entity IDs to associate with the initiative. Example: [30, 32, 45]
Response: 201 with the saved mapping records.
The ai endpoints provide AI-assisted authoring support for result descriptions and other free-text fields. They are gated by JWT authentication and forward the calling user’s token to the underlying AI service.Auth: JWT required. The @UserToken() decorator extracts the user context from the auth header and passes it downstream. No additional role guard is applied — all authenticated users may call these endpoints.
AI helper endpoints consume the user’s session token when communicating with the AI backend. Do not expose these endpoints to unauthenticated clients. Response quality depends on the quality of the input provided by the caller.
Refer to the api/ai/ module source and its dto/responses/ directory for the exact request and response shapes for each AI operation, as the surface evolves with AI model iterations.
The home endpoints return landing-page aggregates used to populate the PRMS dashboard. They provide submission progress metrics, result counts by phase and status, and other portfolio-level summaries.Auth: JWT required. No additional role restriction — all authenticated users may access dashboard data.These endpoints are intentionally read-only and do not accept write parameters. The data is computed from the current state of results in the active phase and returned as a structured summary object.

​
Common patterns

​
Authentication header

All admin endpoints use the same custom authentication header: 
auth: <JWT token>
Do not use Authorization: Bearer. The JwtMiddleware explicitly rejects Basic and Bearer schemes.

​
Response envelope

Most admin endpoints wrap their response in the standard PRMS envelope via ResponseInterceptor: 
{
  "response": { ... },
  "statusCode": 200,
  "message": "...",
  "timestamp": "2024-06-15T12:00:00.000Z",
  "path": "/api/global-parameters"
}
Endpoints that return raw arrays (such as the initiative entity map) pass through the interceptor unchanged.

​
Error responses

StatusMeaning
400Validation error or missing required parameter
401Missing or expired JWT
403Authenticated but insufficient role
404Requested resource not found
500Internal server error (check server logs)

Build docs developers (and LLMs) love

Get started for freeTalk to us