Querying innovations and scaling readiness via API

MARLO tracks research innovations in the “Table 4 - CRP Innovations” reporting section. An innovation record captures the stage of scaling reached, the organisations involved, geographic coverage, contributing milestones, and CGIAR Sub-IDO linkages. The innovations API exposes four endpoints for full CRUD access scoped to a CGIAR entity and reporting phase. All endpoints require a valid QA token. See Authentication for details.

List all innovations

Retrieve all innovations for a CGIAR entity within a reporting year and phase.

GET /api/v2/controllist/{CGIAREntity}/innovations

Path parameters

CGIAREntity

string

required

Acronym of the CGIAR program, platform, or center (e.g., CCAFS).

Query parameters

year

integer

required

Reporting year (e.g., 2023).

phase

string

required

Reporting phase: AR (Annual Report) or POWB (Plan of Work and Budget).

Response

Returns a JSON array of ProjectInnovationARDTO objects — a flattened summary representation used for Annual Report exports.

number

Internal MARLO innovation ID.

title

string

Name of the innovation.

project

number

ID of the associated MARLO project.

year

number

Reporting year.

narrative

string

Description of the innovation.

stageOfInnovation

object

Show StageOfInnovationDTO fields

number

Stage identifier.

name

string

Stage name (e.g., “Scaling Readiness Assessment”).

descriptionStage

string

Description of the stage reached.

innovationType

object

Show InnovationTypeDTO fields

number

Innovation type identifier.

name

string

Type name.

innovationNumber

number

Count of individual improved lines/varieties (where applicable).

otherInnovationType

string

Free-text description when innovation type is “Other”.

nextUserOrganizationTypes

object[]

List of organisation types that are the next users of this innovation.

geographicScopes

object[]

List of geographic scope objects (global, regional, national, etc.).

regions

object[]

List of region objects applicable when scope includes regional coverage.

countries

object[]

List of country objects applicable when scope includes national coverage.

equitativeEffort

boolean

Whether this is an equitable effort across partners.

leadOrganization

object

The lead organisation driving this stage of the innovation.

contributingInstitutions

object[]

Up to five contributing organisations.

evidenceLink

string

URL to supporting evidence.

contributingCGIAREntities

object[]

Contributing CRPs or platforms.

milestonesList

object[]

Associated contributing milestones.

srfSubIdoList

object[]

Linked CGIAR Sub-IDOs from the SRF framework.

projectExpetedStudyList

object[]

Linked Outcome/Impact Case Reports (OICRs).

Example:

curl --request GET \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/innovations?year=2023&phase=AR' \
  --header 'Authorization: Bearer <your-token>'

Get an innovation by ID

Retrieve a single innovation with full detail.

GET /api/v2/controllist/{CGIAREntity}/innovations/{id}

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

number

required

MARLO innovation ID.

Query parameters

year

integer

required

Reporting year.

phase

string

required

Reporting phase (AR or POWB).

Example:

curl --request GET \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/innovations/512?year=2023&phase=AR' \
  --header 'Authorization: Bearer <your-token>'

Returns a full InnovationDTO object (same fields as the list response plus a nested project object with an id field). Returns 404 if not found.

Create an innovation

Create a new innovation record.

POST /api/v2/controllist/{CGIAREntity}/innovations

Requires FULL_CREATE_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

Request body (`NewInnovationDTO`)

title

string

required

Name of the innovation.

narrative

string

Description of the innovation.

project

object

Project reference object. Provide { "id": <project-id> }.

stageOfInnovation

object

Stage of innovation reference. Provide { "id": <stage-id> }.

descriptionStage

string

Description of the stage reached.

innovationType

object

Innovation type reference. Provide { "id": <type-id> }.

innovationNumber

number

Count of improved lines/varieties (where applicable).

otherInnovationType

string

Free-text description when innovation type is “Other”.

nextUserOrganizationTypes

object[]

List of organisation type references.

geographicScopes

object[]

List of geographic scope references.

regions

object[]

List of region code references.

countries

object[]

List of country code references.

equitativeEffort

boolean

Whether effort is equitable across partners.

leadOrganization

object

Lead institution reference. Provide { "code": <institution-code> }.

contributingInstitutions

object[]

List of up to five contributing institution references.

evidenceLink

string

URL to supporting evidence.

contributingCGIAREntities

object[]

List of contributing CRP/platform references.

milestonesCodeList

object[]

List of NewMilestonesDTO references linking contributing milestones.

srfSubIdoList

object[]

List of NewSrfSubIdoDTO references linking CGIAR Sub-IDOs.

projectExpectedStudyList

string[]

List of OICR identifier strings to link.

phase

object

required

Show PhaseDTO fields

name

string

required

Phase name (AR or POWB).

year

integer

required

Phase year.

Example:

curl --request POST \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/innovations' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Drought-tolerant maize variety DT-WEMA-2023",
    "narrative": "A drought-tolerant open-pollinated maize variety released for smallholder farmers in East Africa.",
    "project": { "id": 8432 },
    "stageOfInnovation": { "id": 3 },
    "descriptionStage": "Released and adopted by over 50,000 farmers in Kenya and Tanzania.",
    "innovationType": { "id": 1 },
    "innovationNumber": 1,
    "geographicScopes": [{ "id": 4 }],
    "countries": [{ "isoAlpha2": "KE" }, { "isoAlpha2": "TZ" }],
    "equitativeEffort": false,
    "leadOrganization": { "code": 122 },
    "evidenceLink": "https://hdl.handle.net/10568/example",
    "phase": { "name": "AR", "year": 2023 }
  }'

Returns the numeric ID (Long) of the newly created innovation.

Update an innovation

Update an existing innovation record.

PUT /api/v2/controllist/{CGIAREntity}/innovations/{id}

Requires FULL_CREATE_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

number

required

MARLO innovation ID to update.

Request body

Same fields as POST /innovations (NewInnovationDTO). Supply all fields you want to retain. Example:

curl --request PUT \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/innovations/512' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Drought-tolerant maize variety DT-WEMA-2023 (updated)",
    "narrative": "Updated narrative with additional country coverage.",
    "stageOfInnovation": { "id": 3 },
    "innovationType": { "id": 1 },
    "geographicScopes": [{ "id": 4 }],
    "countries": [{ "isoAlpha2": "KE" }, { "isoAlpha2": "TZ" }, { "isoAlpha2": "UG" }],
    "equitativeEffort": false,
    "phase": { "name": "AR", "year": 2023 }
  }'

Returns the numeric ID of the updated innovation.

Delete an innovation

Delete an innovation record by ID.

DELETE /api/v2/controllist/{CGIAREntity}/innovations/{id}

Requires FULL_READ_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

number

required

MARLO innovation ID.

Query parameters

year

integer

required

Reporting year.

phase

string

required

Reporting phase (AR or POWB).

Example:

curl --request DELETE \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/innovations/512?year=2023&phase=AR' \
  --header 'Authorization: Bearer <your-token>'

Returns an InnovationDTO object on success. Returns 404 if not found.

Common error codes

HTTP status	Meaning
`200`	Success
`404`	Innovation not found for the given ID, entity, year, and phase
`401`	Missing or expired token
`403`	Token valid but insufficient permissions or wrong program scope
`400`	Request body validation failed

Setup & Build

Architecture Patterns

API Reference

Querying innovations and scaling readiness via API

List all innovations

Path parameters

Query parameters

Response

Get an innovation by ID

Path parameters

Query parameters

Create an innovation

Path parameters

Request body (`NewInnovationDTO`)

Update an innovation

Path parameters

Request body

Delete an innovation

Path parameters

Query parameters

Common error codes

Build docs developers (and LLMs) love

Setup & Build

Architecture Patterns

API Reference

Documentation Index

​List all innovations

​Path parameters

​Query parameters

​Response

​Get an innovation by ID

​Path parameters

​Query parameters

​Create an innovation

​Path parameters

​Request body (NewInnovationDTO)

​Update an innovation

​Path parameters

​Request body

​Delete an innovation

​Path parameters

​Query parameters

​Common error codes

Build docs developers (and LLMs) love

List all innovations

Path parameters

Query parameters

Response

Get an innovation by ID

Path parameters

Query parameters

Create an innovation

Path parameters

Request body (`NewInnovationDTO`)

Update an innovation

Path parameters

Request body

Delete an innovation

Path parameters

Query parameters

Common error codes