Proposal Handling Tool (PHT) REST API

A SwaggerUI for the latest main branch of the API is available at

https://k8s.stfc.skao.int/integration-ska-oso-services/oso/api/v2/ui/

The API provides proposal preparation and management resources that support proposal creation, submission, review, and decision processes. Outlined below are the endpoints grouped by different functionality of the PHT.

  • Proposal Preparation:

GET /ska-oso-services/oso/api/v5/pht/prsls/osd/{cycle}

Retrieve OSD data for a given cycle

This queries the OSD data by cycle id.

This data is made available for the PHT UI.

Returns:

OsdDataModel: The OSD data validated against the defined schema.

Parameters:

  • cycle (integer, required)

Status Codes:
POST /ska-oso-services/oso/api/v5/pht/prsls/create

Create a new proposal

Creates a new proposal in the ODA.

Request Headers:

  • X-Request-ID

Status Codes:
GET /ska-oso-services/oso/api/v5/pht/prsls/reviewable

Get a list of proposals by status

Function that requests to GET /prsls/reviewable are mapped to.

Retrieves the Proposals from the underlying data store, if available Return proposals, preferring UNDER_REVIEW over SUBMITTED. One latest proposal per prsl_id.

Returns:

list[Proposal]

Request Headers:

  • X-Request-ID

Status Codes:
GET /ska-oso-services/oso/api/v5/pht/prsls/mine

Get a list of proposals the user can access

List all proposals accessible to the authenticated user.

Request Headers:

  • X-Request-ID

Status Codes:

  • 200 OK – Successful Response

GET /ska-oso-services/oso/api/v5/pht/prsls/{prsl_id}

Retrieve an existing proposal

Retrieves the latest proposal by prsl_id. 1.) Check that the authenticated user has the permission to access the proposal.

Returns:
Proposal: Returns the latest version of the proposal for the supplied prsl_id,

including the metadata.

Request Headers:

  • X-Request-ID

Parameters:

  • prsl_id (string, required)

Status Codes:
PUT /ska-oso-services/oso/api/v5/pht/prsls/{prsl_id}

Update an existing proposal

Updates a proposal in the underlying data store.

Request Headers:

  • X-Request-ID

Parameters:

  • prsl_id (string, required)

Status Codes:
POST /ska-oso-services/oso/api/v5/pht/prsls/batch

Retrieve multiple proposals in batch

Batch retrieves proposals by accepting a list of proposal ids and returning the proposals for those ids.

Request Headers:

  • X-Request-ID

Status Codes:
GET /ska-oso-services/oso/api/v5/pht/prsls/reviews/{prsl_id}

Get all reviews for a particular proposal

Function that requests to GET /reviews/{prsl_id} are mapped to.

Get reviews for a given proposal ID from the underlying data store, if available.

Returns:

list[PanelReview]

Request Headers:

  • X-Request-ID

Parameters:

  • prsl_id (string, required)

Status Codes:
POST /ska-oso-services/oso/api/v5/pht/prsls/validate

Validate a proposal

Validates a submitted proposal via POST.

Returns:
dict: {

“result”: bool, “validation_errors”: list[str]}.

Request Headers:

  • X-Request-ID

Status Codes:
POST /ska-oso-services/oso/api/v5/pht/prsls/send-email/

Send an async email

Endpoint to send SKAO email asynchronously via SMTP.

Request Headers:

  • X-Request-ID

Status Codes:
POST /ska-oso-services/oso/api/v5/pht/prsls/signed-url/upload/{filename}

Create upload PDF URL

Generate a presigned S3 upload URL for the given filename.

Request Headers:

  • X-Request-ID

Parameters:

  • filename (string, required)

Status Codes:
POST /ska-oso-services/oso/api/v5/pht/prsls/signed-url/download/{filename}

Create download PDF URL

Generate a presigned S3 download URL for the given filename.

Request Headers:

  • X-Request-ID

Parameters:

  • filename (string, required)

Status Codes:
POST /ska-oso-services/oso/api/v5/pht/prsls/signed-url/delete/{filename}

Create delete PDF URL

Generate a presigned S3 delete URL for the given filename.

Request Headers:

  • X-Request-ID

Parameters:

  • filename (string, required)

Status Codes:
GET /ska-oso-services/oso/api/v5/pht/prsls/member/{email}

Retrieve user by email

Returns an MS Entra user by email from MS Graph.

Returns:

dict

Request Headers:

  • X-Request-ID

Parameters:

  • email (string, required)

Status Codes: