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:

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.

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¶

Field	Required	Notes
`name`	Yes	The study's unique name
`description`	Yes	Short summary of the study
`data_release_strategy`	Yes	One of `open`, `managed`, or `not applicable` — governs who can access the resulting data
`faculty_sponsor`	Yes	Full name of the sponsoring faculty member
`program`	Yes	The academic/research programme the study sits under
`data_release_study_type`	Yes	Data release classification
`type`	Yes	The study's type
`lims_id`	Yes	Identifier of the source LIMS
`study_id`	Yes	Numeric study identifier (digits only)
`uuid`	Yes	A unique identifier for this study record
`owner_name`	No	Full name of the study's owner
`title`	No	Human-readable display title
`abstract`	No	Extended description of the study's aims

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¶

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` (GET)	`name` query parameter missing, or shorter than 4 / longer than 50 characters	Check the parameter against the rules above and retry
`400 Bad Request` (POST)	A required field is missing, has an invalid value, or an unexpected field was included	Check the request body against the field list above — only the first invalid field is reported per request, so fix and retry rather than assuming that's the only problem
`422 Unprocessable Entity` (GET)	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
`202 Accepted`, but the study doesn't appear to exist	Creation is still in progress, or failed downstream	Check the tracking status endpoint — see Checking whether it worked

Support¶

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