Querying and submitting deliverables via REST API

MARLO tracks research deliverables as publications in two categories: peer-reviewed publications (ISI journal articles and open-access outputs) and other publication types (reports, datasets, and other deliverable formats). The deliverables API maps to the “Table 6 - Peer-reviewed publications” reporting section and exposes five CRUD endpoints plus a Web of Science (WOS) validation utility. All publication endpoints are scoped to a CGIAR entity and require a valid QA token. See Authentication for token setup.

List all publications

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

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

Path parameters

CGIAREntity

string

required

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

Query parameters

year

integer

required

Reporting year (e.g., 2023).

phase

string

required

Reporting phase. Use AR for Annual Report or POWB for Plan of Work and Budget.

Response

Returns a JSON array of PublicationDTO objects.

number

Internal MARLO deliverable ID.

title

string

Title of the publication.

journal

string

Journal or publisher name.

volume

string

Volume identifier.

issue

string

Issue number.

npages

string

Number of pages.

isOpenAccess

boolean

Whether the publication is open access.

isISIJournal

boolean

Whether this is an ISI-indexed journal article.

doi

string

Digital Object Identifier.

handle

string

Handle repository URL.

articleURL

string

Direct URL to the article.

authors

string

Free-text authors field.

authorlist

object[]

Structured list of DeliverableUserDTO author objects.

year

number

Year of publication.

phase

object

Show PhaseDTO fields

name

string

Phase name (AR or POWB).

year

number

Phase year.

Example:

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

Get a publication by ID

Retrieve a single publication record.

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

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

number

required

MARLO deliverable 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/publications/1024?year=2023&phase=AR' \
  --header 'Authorization: Bearer <your-token>'

Returns a single PublicationDTO object (same schema as the list endpoint). Returns 404 if no deliverable matches the ID, entity, year, and phase combination.

Create a publication

Create a new peer-reviewed publication record.

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

Requires FULL_CREATE_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

Request body (`NewPublicationDTO`)

title

string

Title of the publication.

journal

string

Journal or publisher name.

volume

string

Volume identifier.

issue

string

Issue number.

npages

string

Number of pages.

isOpenAccess

boolean

Whether the publication is open access.

isISIJournal

boolean

Whether this is an ISI-indexed journal article.

doi

string

Digital Object Identifier.

handle

string

Handle repository URL.

articleURL

string

Direct URL to the article.

authors

string

Free-text authors field.

authorlist

object[]

Structured list of author objects. Each object is a DeliverableUserDTO.

year

integer

Year of publication.

phase

object

required

Phase object identifying the reporting cycle.

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/publications' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Climate-smart agriculture adoption in sub-Saharan Africa",
    "journal": "Nature Food",
    "volume": "4",
    "issue": "2",
    "npages": "12",
    "isOpenAccess": true,
    "isISIJournal": true,
    "doi": "10.1038/s43016-023-00123-4",
    "year": 2023,
    "phase": {
      "name": "AR",
      "year": 2023
    }
  }'

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

Update a publication

Update an existing peer-reviewed publication.

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

Requires FULL_READ_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

number

required

MARLO deliverable ID to update.

Request body

Same fields as POST /publications (NewPublicationDTO). Provide all fields you want to retain — omitted fields may be cleared. Example:

curl --request PUT \
  --url 'https://your-marlo-host/api/v2/controllist/CCAFS/publications/1024' \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "title": "Climate-smart agriculture adoption in sub-Saharan Africa (revised)",
    "journal": "Nature Food",
    "doi": "10.1038/s43016-023-00123-4",
    "isOpenAccess": true,
    "isISIJournal": true,
    "year": 2023,
    "phase": { "name": "AR", "year": 2023 }
  }'

Returns the numeric ID of the updated deliverable.

Delete a publication

Delete a publication record by ID.

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

Requires FULL_READ_REST_API_PERMISSION.

Path parameters

CGIAREntity

string

required

CGIAR entity acronym.

number

required

MARLO deliverable 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/publications/1024?year=2023&phase=AR' \
  --header 'Authorization: Bearer <your-token>'

Returns the deleted PublicationDTO on success. Returns 404 if the record is not found.

Create an “other” publication

Create a publication of a non-peer-reviewed deliverable type (reports, datasets, etc.).

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

Requires FULL_CREATE_REST_API_PERMISSION.

Request body (`NewPublicationOtherDTO`)

title

string

Title of the deliverable.

type

number

Deliverable type ID. Use the GeneralLists controller to look up valid type codes.

authorlist

object[]

Structured list of DeliverableUserDTO author objects.

authors

string

Free-text authors field.

year

integer

Year of publication.

isOpenAccess

boolean

Whether the deliverable is open access.

doi

string

Digital Object Identifier.

handle

string

Handle repository URL.

articleURL

string

Direct URL to the deliverable.

phase

object

required

Show PhaseDTO fields

name

string

required

Phase name.

year

integer

required

Phase year.

Returns the numeric ID of the created deliverable.

Update an “other” publication

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

Requires FULL_READ_REST_API_PERMISSION. Same request body as POST /publicationsOther. Returns the numeric ID of the updated deliverable.

Validate a publication against Web of Science

Look up a WOS record by URL to validate metadata before submission.

GET /api/v2/controllist/publicationsWOS

This endpoint is not entity-scoped.

Query parameters

url

string

required

The Web of Science article URL to validate.

Example:

curl --request GET \
  --url 'https://your-marlo-host/api/v2/controllist/publicationsWOS?url=https%3A%2F%2Fwww.webofscience.com%2Fwos%2Fwoscc%2Ffull-record%2FWOS%3A000123456789' \
  --header 'Authorization: Bearer <your-token>'

Returns a PublicationsWOSDTO object with enriched metadata from the WOS index. Returns 404 if the URL is not found in WOS.

Common error codes

HTTP status	Meaning
`200`	Success
`404`	Deliverable not found for the given ID, entity, year, and phase
`401`	Missing or expired token
`403`	Token valid but insufficient permissions
`400`	Request body validation failed (e.g., missing required `phase` field)

Setup & Build

Architecture Patterns

API Reference

Querying and submitting deliverables via REST API

List all publications

Path parameters

Query parameters

Response

Get a publication by ID

Path parameters

Query parameters

Create a publication

Path parameters

Request body (`NewPublicationDTO`)

Update a publication

Path parameters

Request body

Delete a publication

Path parameters

Query parameters

Create an “other” publication

Request body (`NewPublicationOtherDTO`)

Update an “other” publication

Validate a publication against Web of Science

Query parameters

Common error codes

Build docs developers (and LLMs) love

Setup & Build

Architecture Patterns

API Reference

Documentation Index

​List all publications

​Path parameters

​Query parameters

​Response

​Get a publication by ID

​Path parameters

​Query parameters

​Create a publication

​Path parameters

​Request body (NewPublicationDTO)

​Update a publication

​Path parameters

​Request body

​Delete a publication

​Path parameters

​Query parameters

​Create an “other” publication

​Request body (NewPublicationOtherDTO)

​Update an “other” publication

​Validate a publication against Web of Science

​Query parameters

​Common error codes

Build docs developers (and LLMs) love

List all publications

Path parameters

Query parameters

Response

Get a publication by ID

Path parameters

Query parameters

Create a publication

Path parameters

Request body (`NewPublicationDTO`)

Update a publication

Path parameters

Request body

Delete a publication

Path parameters

Query parameters

Create an “other” publication

Request body (`NewPublicationOtherDTO`)

Update an “other” publication

Validate a publication against Web of Science

Query parameters

Common error codes