Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/CCAFS/MARLO/llms.txt

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

MARLO exposes a versioned REST API built on Spring MVC, running alongside the traditional Struts 2 web interface. All REST endpoints return JSON and accept JSON request bodies. The API covers the core research-output resources — publications, innovations, projects, and partner institutions — and is used by quality-assurance tooling, external data consumers, and the CGIAR reporting pipeline.

​
Base URL

All REST v2 endpoints share the following path prefix: 
/api/v2/controllist/
Most resource endpoints are scoped to a CGIAR entity (the acronym of a CRP, Platform, or Center), so a typical path looks like: 
/api/v2/controllist/{CGIAREntity}/publications
/api/v2/controllist/{CGIAREntity}/innovations
/api/v2/controllist/{CGIAREntity}/project/{id}
A small number of endpoints are global (not entity-scoped): 
/api/v2/controllist/institutions
/api/v2/controllist/institution-types
/api/v2/controllist/publicationsWOS
/api/v2/controllist/qatoken/
Spring MVC vs Struts 2 boundary — MARLO runs two web frameworks side by side. Struts 2 handles all browser-facing page requests (URLs ending in .do or .json) and is configured in struts.xml and the module-specific struts-*.xml files. Spring MVC handles everything under /api/*; those paths are excluded from Struts via struts.action.excludePattern. When building integrations, use /api/v2/controllist/... paths exclusively. Never call .do endpoints from external systems.

​
API versioning

MARLO uses path-based versioning. The current stable version is v2. The version segment appears immediately after /api/: 
/api/v2/controllist/...
When a new major version is introduced it will live at /api/v3/... while v2 remains accessible. There is no header-based or query-string version negotiation.

​
Authentication

All endpoints require a valid QA token. Pass the token in the Authorization header: 
Authorization: Bearer <your-token>
See the Authentication page for how to obtain and use tokens.

​
Response format

All responses are application/json. Successful responses return the resource object or a numeric ID for create/update operations. Error response shape: 
{
  "code": "404",
  "message": "Deliverable not found for the given id and phase."
}
The code field is a stable string code. The message field is human-readable and may change between releases.

​
OpenAPI / Swagger

MARLO uses the Springdoc OpenAPI library (Springfox @Api/@ApiOperation annotations in the source). The interactive Swagger UI is available at: 
/swagger-ui/
The raw OpenAPI JSON specification is served at: 
/v2/api-docs
These paths are relative to your MARLO deployment root.

​
Available resource groups

Authentication

Obtain and use QA tokens to authenticate REST API requests.

Deliverables (Publications)

Create, read, update, and delete peer-reviewed publications and other deliverable types.

Innovations

Query and manage CRP innovation records, including scaling readiness and Sub-IDO linkages.

Projects

Look up MARLO project records by ID within a CGIAR entity.

Institutions

Browse partner institutions, submit new institution requests, and manage country office requests.

​
Other available controllers

The following additional Spring MVC controllers exist in the v2/controllist package. They follow the same authentication and response conventions described on this page.
ControllerTag / purpose
ARControlListsAnnual report reference lists
CrossCGIARCollaborationsCross-CGIAR collaboration records
ExpectedStudiesOutcome/Impact Case Reports (OICRs)
ExpendituresW1/W2 financial expenditure data
GeneralListsShared reference lists (countries, regions, etc.)
ImpactPathwayImpact pathway and outcome data
KeyExternalPartnershipKey external partnership entries
ParticipantsCapDevCapacity development participant records
PoliciesPolicy research output records
ProgressTowardsSRF progress-towards-target records
ProjectPageAggregated project page data
QATokenToken issuance endpoint
RelevantEvaluationsRelevant evaluation actions
SrfListsSRF reference lists (IDOs, Sub-IDOs, SLOs)
StatusPlannedOutcomesPlanned outcome status records
SubmissionToolsControlListsSubmission tool reference data

​
Pagination, filtering, and phase selection

Most list endpoints require two query parameters that act as mandatory filters:
ParameterTypeDescription
yearintegerThe reporting year (e.g., 2023)
phasestringThe reporting phase name. Valid values are AR (Annual Report) and POWB (Plan of Work and Budget)
There is no offset/limit pagination on list endpoints; all matching records for the given entity, year, and phase are returned in a single response array.

Build docs developers (and LLMs) love

Get started for freeTalk to us