How to use¶

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 — for looking up an existing study.
• The study's details (name, description, faculty sponsor, and the other fields listed under Creating a Study) — for creating a new one.

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:

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

Creating a Study¶

POST /sapio/studies/v1 is asynchronous: it hands the request off for processing and returns immediately, rather than waiting for the study to actually exist in Sequencescape and MLWH before responding.

curl -X POST 'https://api.example.com/sapio/studies/v1' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "Covid Genomics Surveillance",
    "description": "Genomic surveillance of SARS-CoV-2 variants",
    "data_release_strategy": "open",
    "faculty_sponsor": "Dr. Jane Smith",
    "program": "Pathogen Genomics",
    "data_release_study_type": "genomic data",
    "type": "whole genome sequencing",
    "lims_id": "SAPIO",
    "study_id": "123456",
    "uuid": "2b0754a0-a557-11df-8092-00144f01a414"
  }'

A successful request returns a 202 Accepted with a tracking ID — this only confirms the request was received, not that the study has been created yet:

{
  "event_uuid": "8f14e45f-ceea-467e-b1a1-9d8c1e2f4a3b"
}

Required and optional fields¶

Any field not in this list is rejected — the request body only accepts exactly these fields.

Checking whether it worked¶

Because the 202 only means "received," the way to confirm a study actually exists is to poll its tracking ID:

curl 'https://api.example.com/sapio/studies_status/v1?event_uuid=8f14e45f-ceea-467e-b1a1-9d8c1e2f4a3b' \
  --header 'Authorization: Bearer <access_token>'

• If creation is still in progress or has fully succeeded, this won't show an error status — there's currently no explicit "success" state to poll for, so the absence of a failure is the best available signal alongside checking the study directly in Sequencescape (GET /sapio/studies/v1?name=...).
• If a downstream step failed (in Sequencescape, MLWH, or the final confirmation back to Sapio), the status will show which stage failed, and an email alert is sent automatically to the relevant team — you don't have to be the one to notice.

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.

Create a new study¶

curl -X POST 'https://api.example.com/sapio/studies/v1' \
  --header 'Authorization: Bearer <access_token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "...", "description": "...", ... }'

See Creating a Study above for the full field list, and Example Use Cases for a worked example including how to check the result.

Troubleshooting¶

Support¶

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