How to use¶

Current status

Only the GET /sapio/studies/v1 endpoint (look up a study by name) is currently implemented and going through UAT. This page focuses on that endpoint. POST /sapio/studies/v1 (creating a study record) is being implemented and once ready for UAT the usage guidance will be added.

Prerequisites¶

Credentials: an OAuth2 client_id and client_secret issued by the Sanger Integration Hub. See Authentication & Access for how to exchange these for a bearer token.
Network access: connectivity to the Integration Hub API Gateway for your target environment.
The study name (or part of it) you want to look up in Sequencescape.

Getting Started¶

Once you have a bearer token, call the endpoint with the study name as a query parameter:

curl 'https://api.example.com/sapio/studies/v1?name=Covid+Genomics' \
  --header 'Authorization: Bearer <access_token>'

A successful response returns a 200 with the matching study/studies:

{
  "data": [
    {
      "id": "225",
      "name": "Genomic variation in a global set of Salmonella Paratyphi A isolates",
      "uuid": "2b0754a0-a557-11df-8092-00144f01a414",
      "created_at": "2009-01-22T11:47:13+00:00",
      "updated_at": "2024-12-04T11:08:07+00:00",
      "blocked": false,
      "state": "active",
      "ethically_approved": null,
      "enforce_data_release": true,
      "enforce_accessioning": true
    }
  ]
}

Configuration¶

There is no client-side configuration beyond the request itself. The only input is the name query parameter, which is validated before the request reaches Sequencescape:

Rule	Constraint
Required	`name` must be present
Minimum length	at least 4 characters
Maximum length	at most 50 characters

A request that fails validation never reaches Sequencescape — it's rejected immediately by the XAPI layer.

Common Tasks¶

Look up a study by name¶

curl 'https://api.example.com/sapio/studies/v1?name=Covid+Genomics' \
  --header 'Authorization: Bearer <access_token>'

Sequencescape matches on a partial/fuzzy name match, so you don't need the exact, full study name — see Example Use Cases for a worked example.

Troubleshooting¶

Symptom	Likely cause	What to do
`401 Unauthorized`	Missing/expired bearer token	Re-authenticate via the OAuth2 flow described in Authentication & Access
`400 Bad Request`	`name` query parameter missing, or shorter than 4 / longer than 50 characters	Check the parameter against the rules above and retry
`422 Unprocessable Entity`	Results set is too large	Try a more specific search term
`200` with an empty `data` array	No study in Sequencescape matches the name given	Try a broader or different search term

Support¶

For questions, support, or further information, please contact the Sanger Integration Hub, integration-hub@sanger.ac.uk