Introduction

Base URL: http://localhost

This documentation aims to provide all the information you need to work with our API.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>

Authenticating requests

This API is not authenticated.

Endpoints

GET api/user

Example request:

curl --request GET \
    --get "http://localhost/api/user" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://localhost/api/user"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (401):

Show headers

cache-control: no-cache, private
content-type: application/json
access-control-allow-origin: *


{
    "message": "Unauthenticated."
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

GA4GH DRS API v1.2

Implementation of the GA4GH Data Repository Service (DRS) API specification v1.2. This API provides methods to retrieve data objects and their metadata, as well as service information.

Get Service Info

Returns information about the DRS service including the version, supported API versions, and other service-specific information.

Example request:

curl --request GET \
    --get "http://localhost/api/ga4gh/drs/v1/service-info" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://localhost/api/ga4gh/drs/v1/service-info"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "id": "com.example.drs",
    "name": "GA4GH DRS Demo Service",
    "type": {
        "group": "org.ga4gh",
        "artifact": "drs",
        "version": "1.2.0"
    },
    "description": "A demonstration implementation of the GA4GH DRS specification for genomic neuroscience datasets",
    "organization": {
        "name": "Genomic Neuroscience Research Center",
        "url": "https://example.com"
    },
    "version": "1.0.0",
    "contactUrl": "mailto:support@example.com",
    "documentationUrl": "https://example.com/docs",
    "createdAt": "2025-01-01T00:00:00Z",
    "updatedAt": "2025-01-01T00:00:00Z",
    "environment": "production"
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

List Objects

Returns a list of DRS objects. This is a custom endpoint not part of the core DRS spec but useful for browsing available datasets.

Example request:

curl --request GET \
    --get "http://localhost/api/ga4gh/drs/v1/objects?page=1&per_page=20&public_only=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://localhost/api/ga4gh/drs/v1/objects"
);

const params = {
    "page": "1",
    "per_page": "20",
    "public_only": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "data": [
        {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "name": "brain_scan_subject_001.nii",
            "size": 2147483648,
            "mime_type": "application/octet-stream",
            "description": "fMRI scan of subject 001",
            "created_time": "2025-01-01T10:00:00Z"
        }
    ],
    "meta": {
        "current_page": 1,
        "per_page": 20,
        "total": 50
    }
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/ga4gh/drs/v1/objects

Headers

Content-Type

Example: application/json

Accept

Example: application/json

Query Parameters

page integer optional

The page number for pagination. Example: 1

per_page integer optional

Number of items per page. Example: 20

public_only boolean optional true false

Filter to only show public objects. Example: true

Get Object

Returns object metadata and a list of access methods that can be used to fetch the object bytes. Method is guaranteed to return a single object or an error.

Example request:

curl --request GET \
    --get "http://localhost/api/ga4gh/drs/v1/objects/550e8400-e29b-41d4-a716-446655440000?expand=1" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://localhost/api/ga4gh/drs/v1/objects/550e8400-e29b-41d4-a716-446655440000"
);

const params = {
    "expand": "1",
};
Object.keys(params)
    .forEach(key => url.searchParams.append(key, params[key]));

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "brain_scan_subject_001.nii",
    "self_uri": "drs://example.com/550e8400-e29b-41d4-a716-446655440000",
    "size": 2147483648,
    "created_time": "2025-01-01T10:00:00Z",
    "updated_time": "2025-01-01T10:30:00Z",
    "version": "1.0",
    "mime_type": "application/octet-stream",
    "checksums": [
        {
            "type": "md5",
            "checksum": "a1b2c3d4e5f6"
        },
        {
            "type": "sha256",
            "checksum": "1234567890abcdef"
        }
    ],
    "access_methods": [
        {
            "type": "https",
            "access_url": {
                "url": "https://example.com/storage/brain_scan_subject_001.nii"
            }
        }
    ],
    "description": "fMRI scan of subject 001",
    "aliases": [
        "subject_001_fmri",
        "scan_001"
    ]
}

Example response (401):


{
    "msg": "Unauthorized - authentication is required",
    "status_code": 401
}

Example response (403):


{
    "msg": "Forbidden - you do not have permission to access this object",
    "status_code": 403
}

Example response (404):


{
    "msg": "The requested DRS object was not found",
    "status_code": 404
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/ga4gh/drs/v1/objects/{object_id}

Headers

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

object_id string

The DRS object identifier. Example: 550e8400-e29b-41d4-a716-446655440000

Query Parameters

expand boolean optional true false

Optional. If false and the object_id refers to a bundle, the response will not include the contents array. If true and the object_id refers to a bundle, the response will include the contents array. Example: true

Get Access URL

Returns a URL that can be used to fetch the bytes of a DRS object. This method only works for objects with a single access method that supports direct download.

Example request:

curl --request GET \
    --get "http://localhost/api/ga4gh/drs/v1/objects/550e8400-e29b-41d4-a716-446655440000/access/architecto" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"

const url = new URL(
    "http://localhost/api/ga4gh/drs/v1/objects/550e8400-e29b-41d4-a716-446655440000/access/architecto"
);

const headers = {
    "Content-Type": "application/json",
    "Accept": "application/json",
};

fetch(url, {
    method: "GET",
    headers,
}).then(response => response.json());

Example response (200):


{
    "url": "https://example.com/storage/brain_scan_subject_001.nii?token=abc123&expires=1234567890",
    "headers": {
        "Authorization": "Bearer token123"
    }
}

Example response (401):


{
    "msg": "Unauthorized - authentication is required",
    "status_code": 401
}

Example response (403):


{
    "msg": "Forbidden - you do not have permission to access this object",
    "status_code": 403
}

Example response (404):


{
    "msg": "The requested DRS object or access method was not found",
    "status_code": 404
}

Received response:

Request failed with error:



Tip: Check that you're properly connected to the network.
If you're a maintainer of ths API, verify that your API is running and you've enabled CORS.
You can check the Dev Tools console for debugging information.

Request

GET api/ga4gh/drs/v1/objects/{object_id}/access/{access_id?}

Headers

Content-Type

Example: application/json

Accept

Example: application/json

URL Parameters

object_id string

The DRS object identifier. Example: 550e8400-e29b-41d4-a716-446655440000

access_id string optional

Optional The access method ID if multiple access methods exist. Example: architecto

Introduction

Authenticating requests

Endpoints

GET api/user

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

GA4GH DRS API v1.2

Get Service Info

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

List Objects

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

Query Parameters

Get Object

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Query Parameters

Get Access URL

Request Try it out ⚡ Cancel 🛑 Send Request 💥

Headers

URL Parameters

Request

Request

Request

Request

Request