Gencove sample API
The sample API from Gencove — 17 operation(s) for sample.
OpenAPI Specification
openapi: 3.0.3
info:
title: Gencove Back array sample API
version: v2
contact:
email: support@gencove.com
license:
name: Proprietary
description: API for Gencove REST service. Visit <a href='https://enterprise.gencove.com/'>enterprise.gencove.com</a> and <a href='https://docs.gencove.com/'>docs.gencove.com</a> for more information. <br><hr><p>To work with Insomnia, you can generate a Gencove API key by <a target='_blank' href='https://web.gencove.com/account?filter=api-keys'>clicking here</a>. Once you have the API key and have imported the project in Insomnia as a <i>Request Collection</i>, enter the key in Insomnia under <i>Manage Environment</i>.</p><a href='https://insomnia.rest/run/?label=back_api2&uri=https%3A%2F%2Fv2-api-files-prod.s3.amazonaws.com%2Fpublic%2Finsomnia%2Finsomnia_gencove_prod.json' target='_blank'>Run in Insomnia</a><hr>
servers:
- url: https://api.gencove.com
tags:
- name: sample
paths:
/api/v2/sample-ancestry/{sample_id}:
get:
operationId: sample_ancestry_retrieve
parameters:
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleAncestry'
description: ''
/api/v2/sample-consumer-report/{sample_id}:
post:
operationId: sample_consumer_report_create
description: "Generate presigned URL for consumer report.\n\nArgs:\n request: HTTP request\n\nReturns:\n Response with presigned URL and expiration time"
parameters:
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SampleConsumerReportCreate'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SampleConsumerReportCreate'
multipart/form-data:
schema:
$ref: '#/components/schemas/SampleConsumerReportCreate'
security:
- JWT: []
- API key: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleConsumerReportResponse'
description: ''
/api/v2/sample-genomic-variants/{sample_id}:
get:
operationId: sample_genomic_variants_list
description: 'Return variant-level results from a sample''s imputed VCF.
Provide exactly one of the three query modes:
- point: `?chromosome=chr11&position=<pos>`
- range: `?chromosome=chr11&start_position=<start>&end_position=<end>`
- rsid: `?rsid=rs1,rs2,...`
`chromosome` must be an h38 contig name with the `chr` prefix
(chr1..chr22, chrX, chrY, chrM).'
parameters:
- in: query
name: chromosome
schema:
type: string
description: h38 contig name with the `chr` prefix, e.g. `chr1`, `chr11`, `chrX`, `chrY`, `chrM` (point and range queries)
- in: query
name: end_position
schema:
type: integer
description: Range end (1-based); use with `start_position`. The span may not exceed 100000 bp.
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: query
name: position
schema:
type: integer
description: 1-based position for a point query
- in: query
name: rsid
schema:
type: string
description: Comma-separated rsIDs, e.g. `rs429358,rs7412` (at most 50 per request).
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
- in: query
name: start_position
schema:
type: integer
description: Range start (1-based); use with `end_position`
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedGenomicVariantList'
description: ''
/api/v2/sample-kit/:
post:
operationId: sample_kit_create
description: Order a new kit for a sample
tags:
- sample
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SampleKit'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SampleKit'
multipart/form-data:
schema:
$ref: '#/components/schemas/SampleKit'
required: true
security:
- JWT: []
- API key: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleKitResponse'
description: ''
/api/v2/sample-kit-form/:
post:
operationId: sample_kit_form_create
description: 'Create a temporary, payment-free kit-order session.
Auth-gated to ``consumer_provider`` orgs and the ``sample_kit_create`` role
(project-scoped). Creates a placeholder ``samples.Sample`` (status
``consumer_awaiting_kit_order``), pins the JWT ``jti`` on it for replay
protection, and returns a tokenized URL the partner hands to an end user.
The ``Kit`` is only created once the end user submits the form.'
tags:
- sample
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SampleKitFormCreate'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SampleKitFormCreate'
multipart/form-data:
schema:
$ref: '#/components/schemas/SampleKitFormCreate'
required: true
security:
- JWT: []
- API key: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleKitFormResponse'
description: ''
/api/v2/sample-manifests-csv-template/:
get:
operationId: sample_manifests_csv_template_retrieve
description: Download a sample manifest CSV template file based on the template_type parameter.
parameters:
- in: query
name: template_type
schema:
type: string
enum:
- 384_well
- 96_well
- tube
description: Type of the sample manifest CSV template. Options are 96_well, 384_well, tube.
tags:
- sample
security:
- JWT: []
- API key: []
- {}
responses:
'200':
description: No response body
/api/v2/sample-manifests-xlsx-template/:
get:
operationId: sample_manifests_xlsx_template_retrieve
description: Download a sample manifest XLSX template file.
tags:
- sample
security:
- JWT: []
- API key: []
- {}
responses:
'200':
description: No response body
/api/v2/sample-manifests/{sample_manifest_id}:
get:
operationId: sample_manifests_retrieve
parameters:
- in: path
name: sample_manifest_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleManifest'
description: ''
/api/v2/sample-metadata/{sample_id}:
get:
operationId: sample_metadata_retrieve
description: Return sample metadata.
parameters:
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleMetadata'
description: ''
post:
operationId: sample_metadata_create
description: Create sample metadata.
parameters:
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SampleMetadata'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/SampleMetadata'
multipart/form-data:
schema:
$ref: '#/components/schemas/SampleMetadata'
security:
- JWT: []
- API key: []
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleMetadata'
description: ''
/api/v2/sample-parentage/{sample_id}:
get:
operationId: sample_parentage_retrieve
parameters:
- in: query
name: display_results
schema:
type: string
enum:
- all
- checks
- matches
description: 'Display mode for parentage records. Options are:
- ''matches'': Only display records where a parent has been identified (default)
- ''checks'': Only display records where no parent has been identified
- ''all'': Display all parentage records'
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleParentage'
description: ''
/api/v2/sample-quality-controls/{sample_id}:
get:
operationId: sample_quality_controls_list
parameters:
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedQualityControlList'
description: ''
/api/v2/sample-restore-group/{restore_group_id}:
get:
operationId: sample_restore_group_list
parameters:
- in: query
name: archive_status
schema:
type: string
enum:
- all
- archived
- available
- restore_requested
description: Filter samples by their archive status
- in: query
name: created_after
schema:
type: string
description: Filter samples by created timestamp; use ISO8601 format
- in: query
name: created_before
schema:
type: string
description: Filter samples by created timestamp; use ISO8601 format
- in: query
name: hidden_status
schema:
type: string
enum:
- all
- hidden
- visible
description: Filter samples by their hidden status
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- in: query
name: modified_after
schema:
type: string
description: Filter samples by modified timestamp; use ISO8601 format
- in: query
name: modified_before
schema:
type: string
description: Filter samples by modified timestamp; use ISO8601 format
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: path
name: restore_group_id
schema:
type: string
format: uuid
required: true
- in: query
name: search
schema:
type: string
description: Search samples by id or client id or metadata content
- in: query
name: status
schema:
type: string
enum:
- all
- completed
- failed
- running
- succeeded
description: Filter samples by their status
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSampleListList'
description: ''
/api/v2/sample-sheet/:
get:
operationId: sample_sheet_list
description: Return generated sample sheet.
parameters:
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: query
name: search
schema:
type: string
description: gncv:// notated sample path to search for
- in: query
name: sort_by
schema:
type: string
enum:
- created
- modified
description: Sort results
- in: query
name: sort_order
schema:
type: string
enum:
- asc
- desc
description: Sort direction
- in: query
name: status
schema:
type: string
enum:
- all
- assigned
- unassigned
description: 'One of: assigned, unassigned, all; default is ''all'''
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSampleSheetList'
description: ''
/api/v2/sample-stats/{sample_id}:
get:
operationId: sample_stats_retrieve
parameters:
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleStats'
description: ''
/api/v2/sample-statuses/{sample_id}:
get:
operationId: sample_statuses_list
parameters:
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedSampleStatusListList'
description: ''
/api/v2/sample-trait-scores/{sample_id}:
get:
operationId: sample_trait_scores_list
parameters:
- name: limit
required: false
in: query
description: Number of results to return per page.
schema:
type: integer
- name: offset
required: false
in: query
description: The initial index from which to return the results.
schema:
type: integer
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PaginatedTraitScoreList'
description: ''
/api/v2/samples/{sample_id}:
get:
operationId: samples_retrieve
description: Retrieve sample model. Overridden to store audit action.
parameters:
- in: path
name: sample_id
schema:
type: string
format: uuid
required: true
tags:
- sample
security:
- JWT: []
- API key: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SampleDetails'
description: ''
components:
schemas:
SampleStatusList:
type: object
properties:
status:
type: string
note:
type: string
created:
type: string
format: date-time
required:
- status
SampleManifest:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
file_name:
type: string
maxLength: 256
file:
type: string
readOnly: true
project:
type: string
format: uuid
readOnly: true
created:
type: string
format: date-time
required:
- file
- file_name
- id
- project
PaginatedGenomicVariantList:
type: object
required:
- results
properties:
meta:
type: object
properties:
count:
type: integer
next:
type: string
format: uri
nullable: true
previous:
type: string
format: uri
nullable: true
required:
- count
results:
type: array
items:
$ref: '#/components/schemas/GenomicVariant'
TraitScore:
type: object
description: 'Serializer trait score and associated trait metadata models.
This is not really optimal, since it pulls data from multiple parent tables
for objects.'
properties:
trait_score:
$ref: '#/components/schemas/TraitScoreSelfNested'
trait_distribution:
$ref: '#/components/schemas/TraitDistribution'
trait:
$ref: '#/components/schemas/Trait'
trait_unit:
$ref: '#/components/schemas/TraitUnit'
risk:
type: string
nullable: true
description: "Return risk level for the trait score.\n\nReturns:\n Optional[str]: \"high_risk\" if the value is greater than or equal to the risk threshold,\n \"not_high_risk\" otherwise. If the risk threshold or percentile is None, return None."
readOnly: true
required:
- risk
- trait
- trait_distribution
- trait_score
- trait_unit
SampleStats:
type: object
properties:
total_size:
type: integer
required:
- total_size
PaginatedTraitScoreList:
type: object
required:
- results
properties:
meta:
type: object
properties:
count:
type: integer
next:
type: string
format: uri
nullable: true
previous:
type: string
format: uri
nullable: true
required:
- count
results:
type: array
items:
$ref: '#/components/schemas/TraitScore'
TraitUnit:
type: object
properties:
key:
type: string
maxLength: 254
required:
- key
SampleKitFormResponse:
type: object
description: Response body for ``POST /api/v2/sample-kit-form/``.
properties:
sample_id:
type: string
format: uuid
description: UUID of the placeholder ``samples.Sample`` created for the order.
url:
type: string
format: uri
description: Tokenized kit-order form URL for the end-user.
expires_at:
type: string
format: date-time
description: When the embedded JWT expires (ISO-8601).
required:
- expires_at
- sample_id
- url
ArchiveSampleStatus:
type: object
properties:
id:
type: string
status:
type: string
created:
type: string
transition_cutoff:
type: string
format: date-time
nullable: true
description: Denotes the transition time for calculated states
required:
- created
- id
- status
PaginatedSampleListList:
type: object
required:
- results
properties:
meta:
type: object
properties:
count:
type: integer
next:
type: string
format: uri
nullable: true
previous:
type: string
format: uri
nullable: true
required:
- count
results:
type: array
items:
$ref: '#/components/schemas/SampleList'
SampleStatusNested:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
status:
type: string
note:
type: string
created:
type: string
format: date-time
required:
- id
- status
PaginatedQualityControlList:
type: object
required:
- results
properties:
meta:
type: object
properties:
count:
type: integer
next:
type: string
format: uri
nullable: true
previous:
type: string
format: uri
nullable: true
required:
- count
results:
type: array
items:
$ref: '#/components/schemas/QualityControl'
AncestrySelfNested:
type: object
description: Serializer used to nest ancestry data within other ancestry serializer.
properties:
value: {}
SampleFileNested:
type: object
description: 'Sets sample.id as filename in file download_url and skips displaying
download url if file is not available.'
properties:
id:
type: string
format: uuid
readOnly: true
s3_path:
type: string
description: S3 object key
maxLength: 1024
size:
type: integer
maximum: 9223372036854775807
minimum: -9223372036854775808
format: int64
nullable: true
description: Size as reported by AWS in bytes
download_url:
type: string
format: uri
readOnly: true
description: Download url
file_type:
type: string
description: File extension
readOnly: true
checksum_sha256:
type: string
description: Object's sha256 Checksum
maxLength: 64
shadow_mode:
type: boolean
nullable: true
description: If true, file is only accessible by organizations with shadow mode access enabled.
required:
- download_url
- file_type
- id
SampleAncestry:
type: object
properties:
ancestry:
$ref: '#/components/schemas/AncestrySelfNested'
metadata:
$ref: '#/components/schemas/AncestryMetadata'
required:
- ancestry
- metadata
QualityControlSelfNested:
type: object
description: Serializer used to nest QC data within other QC serializer.
properties:
value_expected:
type: number
format: double
nullable: true
value_measured:
type: number
format: double
nullable: true
value_string:
type: string
maxLength: 128
status:
$ref: '#/components/schemas/QualityControlSelfNestedStatusEnum'
required:
- status
TraitDistribution:
type: object
properties:
value: {}
version:
type: string
maxLength: 100
required:
- version
SampleList:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
run:
type: string
format: uuid
nullable: true
created:
type: string
format: date-time
hidden:
type: boolean
description: Flag to hide the sample.
modified:
type: string
format: date-time
client_id:
type: string
description: 'Legacy: external_id'
maxLength: 250
physical_id:
type: string
description: 'Legacy: external_id, external_barcode and sample_barcode'
maxLength: 250
legacy_id:
type: string
description: 'Legacy: sample_id/member_id. Matching sample_ids from back_api app.'
maxLength: 250
last_status:
allOf:
- $ref: '#/components/schemas/SampleStatusNested'
readOnly: true
archive_last_status:
allOf:
- $ref: '#/components/schemas/ArchiveSampleStatus'
readOnly: true
failed_qc:
type: string
readOnly: true
description: Description of failed_qc status if present
required:
- archive_last_status
- client_id
- failed_qc
- id
- last_status
- legacy_id
- modified
- physical_id
SampleKit:
type: object
description: Serializer for creating kit orders in consumer mode.
properties:
project_id:
type: string
format: uuid
writeOnly: true
metadata:
writeOnly: true
nullable: true
sample_id:
type: string
format: uuid
readOnly: true
recipient_address_name:
type: string
maxLength: 255
recipient_address_line1:
type: string
maxLength: 50
recipient_address_line2:
type: string
maxLength: 50
recipient_address_line3:
type: string
maxLength: 50
recipient_address_city:
type: string
maxLength: 50
recipient_address_postal_code:
type: string
maxLength: 20
recipient_address_state_region:
type: string
maxLength: 50
recipient_address_country_code:
$ref: '#/components/schemas/RecipientAddressCountryCodeEnum'
recipient_phone:
type: string
maxLength: 128
recipient_email:
type: string
format: email
maxLength: 254
recipient_instructions:
type: string
maxLength: 255
test_mode:
type: boolean
default: false
description: Set to true to create a test order that will not be shipped. Defaults to false.
required:
- project_id
- recipient_address_city
- recipient_address_country_code
- recipient_address_line1
- recipient_address_name
- recipient_address_postal_code
- recipient_address_state_region
- recipient_email
- recipient_phone
- sample_id
PaginatedSampleSheetList:
type: object
required:
- results
properties:
meta:
type: object
properties:
count:
type: integer
next:
type: string
format: uri
nullable: true
previous:
type: string
format: uri
nullable: true
required:
- count
results:
type: array
items:
$ref: '#/components/schemas/SampleSheet'
SampleKitResponse:
type: object
properties:
sample_id:
type: string
format: uuid
readOnly: true
required:
- sample_id
Trait:
type: object
properties:
key:
type: string
maxLength: 254
required:
- key
QualityControlSelfNestedStatusEnum:
enum:
- succeeded
- failed
- skipped
type: string
description: '* `succeeded` - succeeded
* `failed` - failed
* `skipped` - skipped'
UploadStatusNested:
type: object
properties:
id:
type: string
format: uuid
readOnly: true
status:
type: string
note:
type: string
created:
type: string
format: date-time
required:
- id
- status
AncestryMetadata:
type: object
properties:
value: {}
SampleConsumerReportResponse:
type: object
properties:
url:
type: string
format: uri
description: Presigned URL for accessing the consumer report
expires_at:
type: string
format: date-time
description: When the presigned URL will expire
required:
- expires_at
- url
QualityControlType:
type: object
properties:
key:
type: string
maxLength: 254
type:
type: string
name:
type: string
readOnly: true
description_markdown:
type: string
readOnly: true
display_type:
type: string
readOnly: true
display_only_if_failed:
type: string
readOnly: true
required:
- description_markdown
- display_only_if_failed
- display_type
- key
- name
- type
RecipientAddressCountryCodeEnum:
enum:
- AF
- AX
- AL
- DZ
- AS
- AD
- AO
- AI
- AQ
- AG
- AR
- AM
- AW
- AU
- AT
- AZ
- BS
- BH
- BD
- BB
- BY
- BE
- BZ
- BJ
- BM
- BT
- BO
- BQ
- BA
- BW
- BV
- BR
- IO
- BN
- BG
- BF
- BI
- CV
- KH
- CM
- CA
- KY
- CF
- TD
- CL
- CN
- CX
- CC
- CO
- KM
- CG
- CD
- CK
- CR
- CI
- HR
- CU
- CW
- CY
- CZ
- DK
- DJ
- DM
- DO
- EC
- EG
- SV
- GQ
- ER
- EE
- SZ
- ET
- FK
- FO
- FJ
- FI
- FR
- GF
- PF
- TF
- GA
- GM
- GE
- DE
- GH
- GI
- GR
- GL
- GD
-
# --- truncated at 32 KB (48 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gencove/refs/heads/main/openapi/gencove-sample-api-openapi.yml