Gencove REST API docs

Summary

Resource Operation Description
misc GET / Basic no-auth functionality
  GET /health Backend health
  GET /welcome-api-key API key functionality
projects POST /projects Create project
  GET /projects Fetch my projects
  PUT /projects/(int:project_id) Update project
  GET /projects/(int:project_id) Get project
  GET /projects/(int:project_id)/stats Project stats
  POST /projects/(int:project_id)/image/v2 Image upload
  GET /projects/(int:project_id)/samples Get samples
  GET /projects/(int:project_id)/samples/(int:sample_id) Get single sample
  POST /projects/(int:project_id)/raw-data Get project raw data
  GET /projects/(int:project_id)/samples/(int:sample_id)/order Get sample status
  POST /projects/(int:project_id)/samples/orders Get multiple sample status
samples POST /samples Join project
  GET /samples/projects Get projects for sample
  POST /samples/projects/(int:project_id) Rejoin project
  DELETE /samples/projects/(int:project_id) Leave project
  GET /samples/projects/(int:project_id) Get project info

API Conventions

HTTP responses

A standard response from the Gencove backend will have Content-Type: application/json. It will also typically have a message field with straightforward feedback intended for the user and a message_details field with more detailed information. Unless explicitly modified, this convention can be assumed for all classes of HTTP responses (2xx, 4xx, 5xx, etc.)

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "Message intended for user",
    "message_details": "More detailed message"
}

In order to avoid denoting specific responses for these two fields, the documentation will display them as follows:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "message": "...",
    "message_details": "..."
}

Date and other

In some cases, an API response contains a date field. This is an example of a date field:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "created": {
        "year": 2017,
        "month": 2,
        "month_name": "February",
        "day": 6,
        "hour": 19,
        "minute": 30,
        "second": 36,
        "datetime_string": "February 06, 2017 at 7:30 PM",
        "date_string": "February 06, 2017",
        "time_string": "7:30 PM",
        "iso8601": "2017-02-06T19:30:36"
    }
}

In order to declutter the documentation, date fields (and other irrelevant fields) will be shown as follows in order to maintain valid JSON formatting:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "created": {
        "...": "..."
    }
}

Endpoints

GET /

Endpoint for testing basic unauthenticated access.

Example request:

GET / HTTP/1.1
Host: rest.gencove.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "...",
  "message_details": "..."
}
GET /health

Endpoint for checking backend health.

Example request:

GET /health HTTP/1.1
Host: rest.gencove.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "...",
  "message_details": "..."
}
GET /welcome-api-key

Endpoint for testing API key functionality.

Request Headers:
 

Example request:

GET /welcome-api-key HTTP/1.1
Host: rest.gencove.com
Authorization: GENCOVE-API-KEY my-api-key

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "...",
  "message_details": "..."
}
POST /projects

Create project.

Request JSON Object:
 
  • name (string) – name [required]
  • author (string) – author [required]
  • href (string) – link to information [required]
  • description (string) – description (max 200 chars) [required]
  • enabled (bool) – initial state
  • discoverable (bool) – initial discoverability
  • webhook_url (string) – URL for sample status update webhook
  • sample_url (string) – Redirect to this URL once sample becomes part of the project. May contain “{external_id}”, which will be replaced with the external_id provided in JWT when user joined.
  • direct_url (string) – URL for direct access. Newly generated sample id and link to select raw data files may be optionally interpolated.
  • urlencode_interpolations (bool) – URL encode interpolations setting
Response JSON Object:
 
  • project (dict) – new project data
Request Headers:
 

Example request:

POST /projects HTTP/1.1
Host: rest.gencove.com
Content-Type: application/json
Authorization: JWT my-tmp-access-token

{
  "name": "Test Project",
  "author": "Gencove",
  "href": "http://research.gencove.com",
  "description": "This is a test project for demonstration purposes",
  "enabled": true,
  "discoverable": true
}

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "project": {
    "id": 4,
    "user_id": 3,
    "name": "Test Project",
    "author": "Gencove",
    "description": "This is a test project for demonstration purposes",
    "href": "http://research.gencove.com",
    "discoverable": true,
    "enabled": true,
    "featured": true,
    "approved": true,
    "subsidy_enabled": false,
    "note": null,
    "signing_key": "my_signing_key_4",
    "webhook_url": null,
    "sample_url": null,
    "direct_url": null,
    "urlencode_interpolations": true,
    "file": {
      "url_s3": "...",
      "...": "..."
    },
    "created": {
      "...": "..."
    },
    "modified": {
      "...": "..."
    }
  },
  "message": "...",
  "message_details": "..."
}
GET /projects

Fetch my projects.

Fetch all projects created/owned by user.

Response JSON Object:
 
  • projects (list[dict]) – list of projects
Request Headers:
 

Example request:

GET /projects HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "projects": [
    {
      "id": 2,
      "user_id": 3,
      "name": "Test project 1",
      "author": "Gencove",
      "description": "Description",
      "href": "https://www.test.com",
      "discoverable": false,
      "featured": true,
      "approved": true,
      "enabled": true,
      "subsidy_enabled": false,
      "note": null,
      "signing_key": "my_signing_key_2",
      "webhook_url": null,
      "sample_url": null,
      "direct_url": null,
      "urlencode_interpolations": true,
      "file": {
        "url_s3": "...",
        "...": "..."
      },
      "created": {
        "...": "..."
      },
      "modified": {
        "...": "..."
      }
    },
    {
      "id": 4,
      "user_id": 3,
      "name": "Test Project",
      "description": "This is a test project for demonstration purposes",
      "href": "http://research.gencove.com",
      "discoverable": true,
      "enabled": true,
      "featured": true,
      "approved": true,
      "subsidy_enabled": false,
      "note": null,
      "signing_key": "my_signing_key_4",
      "webhook_url": null,
      "sample_url": null,
      "direct_url": null,
      "urlencode_interpolations": true,
      "file": {
        "url_s3": "...",
        "...": "..."
      },
      "created": {
        "...": "..."
      },
      "modified": {
        "...": "..."
      }
    }
  ],
  "message": "...",
  "message_details": "..."
}
PUT /projects/(int: project_id)

Update project.

Request JSON Object:
 
  • name (string) – name
  • author (string) – author
  • href (string) – link to project information
  • description (string) – project description (max 200 chars)
  • subsidy_enabled (bool) – subsidy state
  • enabled (bool) – project state
  • discoverable (bool) – project discoverability
  • webhook_url (string) – URL for sample status update webhook
  • sample_url (string) – Redirect to this URL once sample becomes part of the project. May contain “{external_id}”, which will be replaced with the external_id provided in JWT when user joined.
  • direct_url (string) – URL for direct access. Newly generated sample id and link to select raw data files may be optionally interpolated.
  • urlencode_interpolations (bool) – URL encode interpolations setting
Response JSON Object:
 
  • project (dict) – updated project
Request Headers:
 

Example request:

PUT /projects/4 HTTP/1.1
Host: rest.gencove.com
Content-Type: application/json
Authorization: JWT my-tmp-access-token

{
  "name": "Test Project Edit",
}

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "project": {
    "id": 4,
    "user_id": 3,
    "name": "Test Project Edit",
    "author": "Gencove",
    "description": "This is a test project for demonstration purposes",
    "href": "http://research.gencove.com",
    "discoverable": true,
    "enabled": true,
    "subsidy_enabled": false,
    "note": null,
    "signing_key": "my_signing_key_4",
    "webhook_url": null,
    "member_url": null,
    "direct_url": null,
    "urlencode_interpolations": true,
    "file": {
      "url_s3": "...",
      "...": "..."
    },
    "created": {
      "...": "..."
    },
    "modified": {
      "...": "..."
    }
  },
  "message": "...",
  "message_details": "..."
}
GET /projects/(int: project_id)

Get project info.

Response JSON Object:
 
  • project (dict) – project data
Request Headers:
 

Example request:

GET /projects/4 HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "project": {
    "id": 4,
    "user_id": 3,
    "name": "Test project",
    "author": "Gencove",
    "description": "This is a test project for demonstration purposes",
    "href": "http://research.gencove.com",
    "discoverable": true,
    "enabled": true,
    "subsidy_enabled": false,
    "note": null,
    "signing_key": "my_signing_key_4",
    "webhook_url": null,
    "member_url": null,
    "direct_url": null,
    "urlencode_interpolations": true,
    "file": {
      "url_s3": "...",
      "...": "..."
    },
    "created": {
      "...": "..."
    },
    "modified": {
      "...": "..."
    }
  },
  "message": "...",
  "message_details": "..."
}
GET /projects/(int: project_id)/stats

Project stats.

Response JSON Object:
 
  • subsidies_offered (int) – total amount of subsidies offered
  • subsidies_used (int) – total amount of subsidies used
  • subsidies_offered_unused (int) – total amount of subsidies offered, but unused
  • signups_total (int) – total samples associated with project
  • signups_participating (int) – total samples associated and participating
  • signups_not_participating (int) – total samples associated and not participating
  • signups_participating_kit_ordered (int) – total samples associated, participating, and have ordered a kit
  • signups_participating_kit_returned (int) – total samples associated, participating, and have returned their kit
  • signups_participating_results_ready (int) – total samples associated, participating, and have results ready
Request Headers:
 

Example request:

GET /projects/4/stats HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "subsidies_offered": 25000,
  "subsidies_used": 8000,
  "subsidies_offered_unused": 15000,
  "signups_total": 10,
  "signups_participating": 8,
  "signups_not_participating": 2,
  "signups_participating_kit_ordered": 6,
  "signups_participating_kit_returned": 4,
  "signups_participating_results_ready": 0,
  "message": "...",
  "message_details": "..."
}
POST /projects/(int: project_id)/image/v2

Upload project image

Request Headers:
 

Example request:

POST /projects/4/image HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token
Content-Length: 1022
Content-Type: multipart/form-data; boundary=----WebKitFormBoundaryePkpFF7tjBAqx29L

------WebKitFormBoundaryePkpFF7tjBAqx29L
Content-Disposition: form-data; name="uploadedfile"; filename="image.jpg"
Content-Type: application/x-object

... contents of file goes here ...
------WebKitFormBoundaryePkpFF7tjBAqx29L--

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "...",
  "message_details": "..."
}
GET /projects/(int: project_id)/samples

Get samples in project

If a sample is not “participating” in a project, their info will not be provided here.

Response JSON Object:
 
  • samples (list[dict]) – list of samples
Request Headers:
 

Example request:

GET /projects/4/samples HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "samples": [
    {
      "id": 3,
      "project_id": 4,
      "external_id": "user-1",
      "participating": true,
      "subsidy_in_cents": 0,
      "subsidy_used_date": null,
      "subsidy_used_in_cents": null,
      "jwt_log": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHVkeV9pZCI6NCwic3Vic2lkeV9pbl9jZW50cyI6MCwiZXh0ZXJuYWxfaWQiOiJ1c2VyLTEifQ.2R2f4jn6a1X_E9qsaZbRIw2gkxtOcoSacG3ddA1csWE",
      "created": {
        "...": "..."
      },
      "modified": {
        "...": "..."
      }
    },
    {
      "id": 4,
      "project_id": 4,
      "external_id": "user-2",
      "participating": true,
      "subsidy_in_cents": 0,
      "subsidy_used_date": null,
      "subsidy_used_in_cents": null,
      "jwt_log": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHVkeV9pZCI6NCwic3Vic2lkeV9pbl9jZW50cyI6MCwiZXh0ZXJuYWxfaWQiOiJ1c2VyLTIifQ.NLpRVWvTQWSry6oaMjQ9Gtw5vVTF-i5JnXcc151QHSk",
      "created": {
        "...": "..."
      },
      "modified": {
        "...": "..."
      }
    },
  ],
  "message": "...",
  "message_details": "..."
}
GET /projects/(int: project_id)/samples/(int: sample_id)

Get single sample in project

If a sample is not “participating” in a project, their info will not be provided here.

Response JSON Object:
 
  • sample (dict) – sample
Request Headers:
 

Example request:

GET /projects/4/samples/3 HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "sample": {
    "id": 3,
    "project_id": 4,
    "external_id": "user-1",
    "participating": true,
    "subsidy_in_cents": 0,
    "subsidy_used_date": null,
    "subsidy_used_in_cents": null,
    "jwt_log": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHVkeV9pZCI6NCwic3Vic2lkeV9pbl9jZW50cyI6MCwiZXh0ZXJuYWxfaWQiOiJ1c2VyLTEifQ.2R2f4jn6a1X_E9qsaZbRIw2gkxtOcoSacG3ddA1csWE",
    "created": {
      "...": "..."
    },
    "modified": {
      "...": "..."
    }
  },
  "message": "...",
  "message_details": "..."
}
POST /projects/(int: project_id)/raw-data

Get project raw data.

If sample_ids and external_ids are omitted or set to null, data for all samples is returned. Setting sample_ids or external_ids to [] yields an empty list as a response.

sample ids are guaranteed to be unique, external ids are not. This may result in multiple objects returned for the same external id.

Request JSON Object:
 
  • sample_ids (list) – list of sample ids (not external ids). Id is silently skipped if it is not found or data is not available. Omit or set to null to avoid filtering by this argument.
  • external_ids (list) – list of external ids (not sample ids). Id is silently skipped if it is not found or data is not available. Omit or set to null to avoid filtering by this argument
Response JSON Object:
 
  • raw_data (list[dict]) – list of raw data dictionaries
  • trait_descriptions (dict) – dictionary of trait descriptions
Request Headers:
 

Example request:

POST /projects/4/raw-data HTTP/1.1
Host: rest.gencove.com
Content-Type: application/json
Authorization: JWT my-tmp-access-token

{
  "sample_ids": [3, 4]
}

Example response:

HTTP/1.1 200 OK
Content-type: projectlication/json

{
  "raw_data": [
    {
      "sample_id": 4,
      "external_id": "dummy-id",
      "project_id": 4,
      "url_s3": "https://s3.amazonaws.com/production.bam/2016-10-17-123456789012.bam?AWSAccessKeyId=123&Expires=1486593291&Signature=321",
      "fastq_r1_url_s3": null,
      "fastq_r2_url_s3": null,
      "bam_url_s3": "https://s3.amazonaws.com/production.bam/2016-10-17-123456789012.bam?AWSAccessKeyId=123&Expires=1486593291&Signature=321",
      "bai_url_s3": "https://s3.amazonaws.com/production.bai/2016-10-17-123456789012.bam.bai?AWSAccessKeyId=123&Expires=1486593291&Signature=321",
      "fastq_nongrch37_url_s3": null,
      "ancestry_url_s3": null,
      "microbiome_url_s3": null,
      "vcf_url_s3": null,
      "tbi_url_s3": null,
      "csi_url_s3": null,
      "snp_url_s3": null,
      "trait_values": {
        "sleep": 0.0123,
        "swb": 0.3210
      },
      "traits_url_s3": null,
      "ancestry_url_suffix": "user?NEUROPE=0.7&NEEUROPE=0.1&SEASIA=0.2"
    }
  ],
  "trait_descriptions": {
    "swb": {
      "description": "Subjective well-being.",
      "unit": {
        "description": "Beta from linear regression",
        "unit": null,
        "name": "beta"
      }
    },
    "sleep": {
      "description": "Sleep, chronotype, morningness/eveningness.",
      "unit": {
        "description": "Log odds",
        "unit": null,
        "name": "log_odds"
      }
    }
  },
  "message": "...",
  "message_details": "..."
}
GET /projects/(int: project_id)/samples/(int: sample_id)/order

Get single sample status

If a sample is not “participating” in a project, their info will not be provided here.

Response JSON Object:
 
  • order (dict) – order
Request Headers:
 

Example request:

GET /projects/4/samples/3/order HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "order": {
    "...": "..."
  },
  "message": "...",
  "message_details": "..."
}
POST /projects/(int: project_id)/samples/orders

Get multiple sample status

If a sample is not “participating” in a project, their info will not be provided here.

Request JSON Object:
 
  • sample_ids (list) – list of sample ids (not external ids). Id is silently skipped if it is not found or data is not available. [required]
Response JSON Object:
 
  • orders (dict) – order
Request Headers:
 

Example request:

POST /projects/4/samples/orders HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

{
  "sample_ids": [3, 4, 5]
}

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "orders": {
    3: {
      ...": "..."
    },
    4: {
      ...": "..."
    }
  },
  "message": "...",
  "message_details": "..."
}
POST /samples

Join sample to project.

Request JSON Object:
 
  • jwt (string) – JSON Web Token (JWT) [required]
Request Headers:
 

Example request:

POST /samples HTTP/1.1
Host: rest.gencove.com
Content-Type: application/json
Authorization: JWT my-tmp-access-token

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdHVkeV9pZCI6NCwic3Vic2lkeV9pbl9jZW50cyI6MCwiZXh0ZXJuYWxfaWQiOiJ1c2VyLTIifQ.NLpRVWvTQWSry6oaMjQ9Gtw5vVTF-i5JnXcc151QHSk"
}

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "message": "...",
  "message_details": "..."
}
GET /samples/projects

Get projects sample is “participating” in or has participated in the past.

Response JSON Object:
 
  • sample_projects (list[dict]) – projects currently participating in
  • sample_projects_log (list[dict]) – projects not participating in anymore
Request Headers:
 

Example request:

GET /samples/projects HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "sample_projects": [
    {
      "sample": {
        "id": 3,
        "user_id": 3,
        "project_id": 4,
        "participating": true,
        "subsidy_in_cents": 0,
        "subsidy_used_date": null,
        "subsidy_used_in_cents": null,
        "created": {
          "...": "..."
        },
        "modified": {
          "...": "..."
        }
      },
      "project": {
        "id": 4,
        "name": "Test project",
        "author": "Gencove",
        "description": "This is a test project for demonstration purposes",
        "href": "http://research.gencove.com",
        "discoverable": true,
        "featured": true,
        "approved": true,
        "enabled": true,
        "subsidy_enabled": false,
        "created": {
          "...": "..."
        },
        "modified": {
          "...": "..."
        }
      }
    }
  ],
  "sample_projects_log": [
  ],
  "message": "...",
  "message_details": "..."
}
POST /samples/projects/(int: project_id)

Rejoin project.

Request Headers:
 

Example request:

POST /samples/projects/4 HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "message": "...",
  "message_details": "..."
}
DELETE /samples/projects/(int: project_id)

Leave project.

Request Headers:
 

Example request:

DELETE /samples/projects/4 HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "message": "...",
  "message_details": "..."
}
GET /samples/projects/(int: project_id)

Get project info as sample.

Response JSON Object:
 
  • project (dict) – project data
Request Headers:
 

Example request:

GET /samples/projects/4 HTTP/1.1
Host: rest.gencove.com
Authorization: JWT my-tmp-access-token

Example response:

HTTP/1.1 200 OK
Content-type: application/json

{
  "project": {
    "id": 4,
    "user_id": 3,
    "name": "Test project",
    "author": "Gencove",
    "description": "This is a test project for demonstration purposes",
    "href": "http://research.gencove.com",
    "discoverable": true,
    "featured": true,
    "approved": true,
    "enabled": true,
    "subsidy_enabled": false,
    "note": null,
    "file": {
      "url_s3": "...",
      "...": "..."
    },
    "created": {
      "...": "..."
    },
    "modified": {
      "...": "..."
    }
  },
  "message": "...",
  "message_details": "..."
}