API Reference

Clients

seqq's Python and JavaScript client libraries simplify interaction with the API. They have typed methods for every public API endpoint of the service. Instantiate the clients with the HTTP address of the seqq service.

seqq's RESTful HTTP API is also callable directly for runtimes without a client library.

pip install seqq

from seqq.configuration import Configuration
from seqq.api_client import ApiClient
from seqq.api.seqq_service_api import SeqqServiceApi

client = SeqqServiceApi(ApiClient(Configuration("http://localhost:8320")))

Collections

Collections contain Records, Searches, and Integrations.

Attributes

name

string

A globally unique name for the Collection. Format is collections/{collection_id} where collection_id is set during creation. This is not modifiable.

record_count

string

Count of all records.

letter_count

string

Summed length of all records in the collection.

{
  "name": "collections/my-collection",
  "display_name": "My Collection"
}

Create a Collection

Create a Collection.

Parameters

collection

Collection

Collection to create.

collection_id

string

required

ID of the collection to create. Must be unique. Must be between 3 and 64 characters long and can only contain alphanumeric characters and hyphens.

POST/v1alpha/collections

from seqq.api.seqq_service import seqq_service_create_collection
from seqq.models import V1AlphaCollection

collection = V1AlphaCollection(display_name="My Collection")
resp = seqq_service_create_collection.sync_detailed(
    collection=collection, client=client
)
if resp.status_code != 200:
    logging.error("failed to create a collection: %s", resp.parsed)
    sys.exit(1)
else:

Get a Collection

Get a Collection by its name.

Parameters

name

string

required

The name of the Collection to retrieve. Format: collections/{collection_id}.

GET/v1alpha/collections/:collection-id

from seqq.api.seqq_service import seqq_service_get_collection

resp = seqq_service_get_collection.sync_detailed(
    name="collections/my-collection", client=client
)
if resp.status_code != 200:
    logging.error("failed to get a collection: %s", resp.parsed)
    sys.exit(1)
else:

List Collections

List Collections.

Parameters

page_size

integer

The maximum number of Collections to return. If unset, at most 100 Collections will be returned. The maximum value is 1000.

page_token

string

A page token from a previous List Collections call. Provide this to retrieve the subsequent page.

GET/v1alpha/collections

from seqq.api.seqq_service import seqq_service_list_collections

resp = seqq_service_list_collections.sync_detailed(client=client)
if resp.status_code != 200:
    logging.error("failed to list collections: %s", resp.parsed)
    sys.exit(1)
else:

Delete a Collection

Delete a Collection by name.

This will only delete the Collection if it is empty. To delete a Collection and all its child resources, set force to true.

Parameters

name

string

required

The name of the collection to delete. Format: collections/{collection_id}.

DELETE/v1alpha/collections/:collection-id

from seqq.api.seqq_service import seqq_service_delete_collection

resp = seqq_service_delete_collection.sync_detailed(
    name="collections/my-collection", client=client
)
if resp.status_code != 200:
    logging.error("failed to delete a collection: %s", resp.parsed)
else:

Records

Record is a single entry containing nucleotides or amino acids and other optional metadata like a description, creation time, and taxonomy ID.

Attributes

name

string

Name of the Record. Format: collections/{collection_id}/records/{record_id}.

collection

string

The name of the Collection the Record belongs to. Format: collections/{collection_id}.

sequence

string

A sequence of nucleotides or amino acids. Only characters in the IUPAC alphabets are allowed.

code

Code

The code of the sequence. This is guessed from sequence when unset.

Possible enum values

NUCLEIC
PROTEIN

taxonomy_id

string

The taxonomy ID of the record in NCBI's Taxonomy database.

create_time

string

The time that the Record was created. This is assigned by the server.

etag

string

An opaque, server-assigned value that is a hash of all other fields in the Record resource. This is used during deletes to ensure stale Records are excluded from Search responses.

description

string

A description of the Record. For Records from FASTA files, this is the entire description line without the leading ">". For Records from GenBank files, this is from the Description field.

{
  "name": "collections/my-collection/records/fluorescent-proteins/gfp",
  "collection": "collections/my-collection",
  "sequence": "ACGATCTATCGTACGATCAGTGACT",
  "code": 1,
  "taxonomy_id": "6100",
  "create_time": {
    "seconds": 1702036800
  },
  "etag": "c7d48bbf2b960adc10b0aba11bf336a5"
}

Create a Record

Create a Record in a Collection.

Parameters

collection

string

required

The name of the Collection to create Records in. Format: collections/{collection_id}.

record

Record

required

The Record to create.

record_id

string

required

The ID of the Record to create. This is appended to the Collection name and /records/ to create the Record name. For example, if collection is collections/my-collection, and record_id is my-prefix/my-record, the Record name will be collections/my-collection/records/my-prefix/my-record. The / delimiter is encouraged to group Records by prefix.

POST/v1alpha/collections/:collection-id/record

from seqq.api.seqq_service import seqq_service_create_record
from seqq.models import V1AlphaRecord, V1AlphaCode

resp = seqq_service_create_record.sync_detailed(
    collection="collections/my-collection",
    record_id="fluorescent-proteins/gfp",
    body=V1AlphaRecord(
        sequence="ACGATCTATCGTACGATCAGTGACT",
        code=V1AlphaCode.NUCLEIC,
        taxonomy_id="6100",
    ),
    client=client,
)
if resp.status_code != 200:
    logging.error("failed to create a record: %s", resp.parsed)
else:

Get a Record

Get a Record by name.

Parameters

name

string

required

The name of the Record to retrieve. Format: collections/{collection_id}/records/{record_id}.

GET/v1alpha/collections/:collection-id/records/:sequence-id

from seqq.api.seqq_service import seqq_service_get_record

resp = seqq_service_get_record.sync_detailed(
    name_2="collections/my-collection/records/flourescent-proteins/gfp",
    client=client,
)

if resp.status_code != 200:
    logging.error("failed to get a record: %s", resp.parsed)
else:

List Records

List Records in a Collection.

Parameters

collection

string

required

The name of the Collection to list Records from. Format: collections/{collection_id}.

page_size

integer

The maximum number of Records to return. seqq may return fewer than this value. If unset, at most 50 records will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_token

string

A page token from a previous List Records call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to List Records must match the call that provided the page token.

GET/v1alpha/collections/:collection-id/records

from seqq.api.seqq_service import seqq_service_list_records

resp = seqq_service_list_records.sync_detailed(
    collection="collections/my-collection", client=client
)
if resp.status_code != 200:
    logging.error("failed to list records: %s", resp.parsed.records)
else:

Delete a Record

Delete a Record by name.

Parameters

name

string

required

The name of the Record to delete. Format: collections/{collection_id}/records/{record_id}.

force

boolean

Whether to return a successful response even if the Record does not exist.

DELETE/v1alpha/collections/:collection-id/records/:sequence-id

from seqq.api.seqq_service import seqq_service_delete_record

resp = seqq_service_delete_record.sync_detailed(
    name_1="collections/my-collection/records/flourescent-proteins/gfp",
    client=client,
)

if resp.status_code != 200:
    logging.error("failed to delete a record: %s", resp.parsed)
else:

Searches

A Search of the Records in a Collection.

searches run against a Collection using a chosen program. On reads, Searches contain the results of the query, including its current state and any hits.

Attributes

name

string

The globally unique name of the Search. Format is collections/{collection_id}/searches/{search_id}.

query

string

The sequence of nucleotides or amino acids to search the Collection for.

program

The program to search the database with.

Possible enum values

BLASTN
BLASTP
BLASTX
TBLASTN
TBLASTX

options

Options describing the search to run: program and configuration.

prefix

string

An optional "/" separated prefix to limit searches to.

query_time

string

The time a search is started.

query_duration

string

The duration of a search from start to completion.

hits

array

A list of hits from the Search. This is only set when state is SUCCEEDED.

{
  "query": "ACGATCTATCGTACGATCAGTGACT",
  "code": 1,
  "query_time": {
    "seconds": 1702036800
  },
  "query_duration": {
    "seconds": 1
  },
  "hits": [
    {}
  ],
  "state": 2,
  "strategy": {
    "Program": {
      "Blastn": null
    }
  }
}

Run a Search

Run a Search against a collection.

Parameters

collection

string

required

The name of the Collection to search against. Only Records in this Collection are queried. Format: collections/{collection_id}.

required

The search parameters to use.

POST/v1alpha/collections/:collection-id/searches

from seqq.api.seqq_service import seqq_service_start_search
from seqq.models import V1AlphaSearch

resp = seqq_service_start_search.sync_detailed(
    collection="collections/my-collection",
    body=V1AlphaSearch(query="ACGATCTATCGTACGATCAGTGACT"),
    client=client,
)
if resp.status_code != 200:
    logging.error("failed to start a search: %s", resp.parsed)
else:

Get a Search

Get a Search by name.

Parameters

name

string

required

The name of the Search to retrieve. Format: collections/{collection_id}/searches/{search_id}.

GET/v1alpha/collections/:collection-id/searches/:search-id

from seqq.api.seqq_service import seqq_service_get_search

resp = seqq_service_get_search.sync_detailed(
    name_2="collections/my-collection/searches/1", client=client
)
if resp.status_code != 200:
    logging.error("failed to get a search: %s", resp.parsed)
else:

List Searches

List Searches in a Collection.

Parameters

collection

string

required

The name of the Collection to list Searches from. Format: collections/{collection_id}.

page_size

integer

The maximum number of Searches to return. If unset, at most 50 Searches will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000.

page_token

string

A page token from a previous List Searches call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to List Searches must match the call that provided the page token.

GET/v1alpha/collections/:collection-id/searches

from seqq.api.seqq_service import seqq_service_list_searches

resp = seqq_service_list_searches.sync_detailed(
    collection="collections/my-collection", client=client
)
if resp.status_code != 200:
    logging.error("failed to list searches: %s", resp.parsed)
else:

Delete a Search

Delete a Search by name.

Parameters

name

string

required

The name of the Search to delete. Format: collections/{collection_id}/searches/{search_id}.

force

boolean

Whether to return a successful response even if the Search does not exist.

DELETE/v1alpha/collections/:collection-id/searches/:search-id

from seqq.api.seqq_service import seqq_service_delete_search

resp = seqq_service_delete_search.sync_detailed(
    name_2="collections/my-collection/searches/1", client=client
)
if resp.status_code != 200:
    logging.error("failed to delete a search: %s", resp.parsed)
else:

API Reference

Clients​

Collections​

Attributes

Create a Collection​

Parameters

Get a Collection​

Parameters

List Collections​

Parameters

Delete a Collection​

Parameters

Records​

Attributes

Create a Record​

Parameters

Get a Record​

Parameters

List Records​

Parameters

Delete a Record​

Parameters

Searches​

Attributes

Run a Search​

Parameters

Get a Search​

Parameters

List Searches​

Parameters

Delete a Search​

Parameters

Clients

Collections

Create a Collection

Get a Collection

List Collections

Delete a Collection

Records

Create a Record

Get a Record

List Records

Delete a Record

Searches

Run a Search

Get a Search

List Searches

Delete a Search