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:
	Authorization – GENCOVE-API-KEY can be used to authenticate

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 href (string) – link to information 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 pipeline_configuration_id (int) – Pipeline configuration id
Response JSON Object:
	project (dict) – new project data
Request Headers:
	Content-Type – must be `application/json` Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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,
  "pipeline_configuration_id": 1
}

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,
    "pipeline_configuration_id": 1,
    "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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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,
      "pipeline_configuration_id": 1,
      "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,
      "pipeline_configuration_id": 1,
      "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 pipeline_configuration_id (int) – Pipeline configuration id
Response JSON Object:
	project (dict) – updated project
Request Headers:
	Content-Type – must be `application/json` Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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,
    "pipeline_configuration_id": 1,
    "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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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,
    "pipeline_configuration_id": 1,
    "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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Content-Type – must be `application/json` Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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,
      "local_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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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 sample_ids are set to null, data for all samples is returned. 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. Omit or set to null to avoid filtering by this argument. [required]
Response JSON Object:
	orders (dict) – order
Request Headers:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Content-Type – must be `application/json` Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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:
	Authorization – JWT (access token) can be used to authenticate Authorization – GENCOVE-API-KEY can be used to authenticate

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": "..."
}