Sequences

OpenAPI 3.1 ยท For Sequences 0.106.0

API reference

The routes a program uses to search sequences and read results, with their parameters and answers, from this server's OpenAPI description.

Sign in with an API token

On this server, a program signs in with an API token. Choose API tokens from your account button, name the token, pick how long it lasts, up to 90 days, and copy it: the page shows it only once.

Send it with every request:

curl -H "Authorization: Bearer <token>" https://sequences.conductscience.org/api/jobs

A token acts as its account, under the same rules. An account may have 10 live tokens. A token cannot make another token: that needs the browser. See Programs and API tokens in the user guide and API tokens for programs in the installation guide.

The OpenAPI description

GET /api/openapi.json gives this description as JSON, in OpenAPI 3.1, with every schema in full. It is open without sign-in and holds no data. Each route below gives its operation ID there after its path.

Errors

An error answers with JSON, { "message": "..." }, whose message says what went wrong.

  • 400: The request is not one the service can run; the message says why.
  • 401: Sign in: send a valid API token. The message says whether it is unknown, revoked or expired.
  • 403: This account may not do this, or the license or trial has ended.
  • 404: Not found, or it belongs to another account.
  • 409: Not ready, or the account is at its limit. A search this server asks about first answers 409 with confirm; the same request with "confirmed": true runs it.
  • 413: The request is too large.
  • 415: Send the body as application/json.
  • 429: The queue is full: wait for jobs to finish. Or the account's searches have used the CPU hours this server allows in a UTC day: Retry-After gives the seconds until 00:00 UTC.
  • 503: The service is stopping, or cannot check tokens right now.

System

The server, its sets and databases.

Whether the service can search

GET /api/health getHealth

Open without sign-in.

Answers

  • 200: ok is true when BLAST+ answers and, on a hosted server, a snapshot is installed.
  • Errors: 404, as under Errors above.

This description

GET /api/openapi.json getOpenApi

Open without sign-in.

Answers

  • 200: The OpenAPI 3.1 description of this server.
  • Errors: 404, as under Errors above.

What this server can do, and the signed-in account

GET /api/status getStatus

Answers

  • 200: The tools, limits and license, and on a hosted server the account.
  • Errors: 400, 401, 403, 404, as under Errors above.

Installed snapshots, their sources and the terms of each source

GET /api/snapshots listSnapshots

Answers

  • 200: The snapshots.
  • Errors: 400, 401, 403, 404, as under Errors above.

The sets and databases this server searches

GET /api/databases listDatabases

Answers

  • 200: Each snapshot set and database. A search names a set by snapshotId and set, or a database by databaseId.
  • Errors: 400, 401, 403, 404, as under Errors above.

Import a FASTA collection (local workbench only)

POST /api/databases importDatabase

A hosted server refuses with 403: it searches its own snapshot.

Body

JSON.

  • fasta, required: string. The sequences in FASTA or PIR (NBRF).
  • type, required: one of nucl, prot.
  • title: string. A name, up to 500 characters.
  • source: string. Where the sequences came from, up to 500 characters.

Answers

  • 202: The import job.
  • Errors: 400, 401, 403, 404, 413, 415, 429, 503, as under Errors above.

Searches

Start, follow and cancel searches.

The account's jobs, newest first

GET /api/jobs listJobs

Parameters

  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.
  • text, in the query: string, up to 200 characters. Text to find in a job's name, or in the name of the set or database it searched, in any case. Up to 200 characters.
  • status, in the query: a list of values, each one of queued, running, completed, failed, cancelled, interrupted. The states to keep, separated by commas, such as queued,running.

Answers

  • 200: One page of jobs.
  • Errors: 400, 401, 403, 404, as under Errors above.

Start a search

POST /api/jobs createJob

On a server with compute limits, a search estimated to take longer than the server's time for asking, or one of a large set, answers 409 with confirm and does not start: send it again with "confirmed": true. An account whose searches have used the CPU hours the server allows in a UTC day gets 429 until 00:00 UTC.

Body

JSON (SearchRequest). A search: the queries and where to search. Name a snapshot set (snapshotId and set) or a database (databaseId). Up to 20 queries, 20,000 letters in a query and 100,000 in all. The scoring settings (matrix, gapOpen, gapExtend, wordSize, lowComplexity and geneticCode) need a chosen engine, blast or a FASTA36 one: with auto, the default on a snapshot, any of them answers 400 with "Choose a method to change its settings.", and an exact or pattern search takes none. A setting the program cannot take answers 400 with the reason before anything is queued. The search record lists every setting each query ran with, defaults included, in queries[].settings, and those the request named in parameters.chosenSettings; Run again sends them again.

  • fasta: string. The queries in FASTA or PIR (NBRF), or one sequence as plain letters. A PIR record such as >P1;name has a description line after its header and ends with *; its header gives its type, which must match the search.
  • snapshotId: string. The snapshot, as GET /api/databases lists it.
  • set: string. The set in the snapshot, such as patent_prot.
  • deltas: a list of up to 1000 strings. Weekly additions to search with the snapshot, in order from the first.
  • databaseId: string. An attached or imported database, instead of a snapshot.
  • engine: one of auto, blast, exact, pattern, within, ssearch36, ggsearch36, glsearch36. auto (the default on a snapshot) picks the tool for each query. within (Within k changes) lists every sequence of a snapshot set of the query's own type within k changes of each query, DNA on both strands, with no score or E-value cut, where kscan is installed: queries of up to 64 letters, k up to 5, and up to 50,000 hits a query, the closest first. It takes k and changes, and refuses any other search setting. ssearch36 (Smith-Waterman), glsearch36 (global on the query) and ggsearch36 (global on both sequences) compare each query with every sequence of a snapshot set of its own type, DNA on both strands, where FASTA36 is installed. Each DNA query reads the whole set, so a DNA search whose estimate passes the server's time limit for one search answers 400 and does not start.
  • program: one of blastn, blastp, blastx, tblastn. The query type and direction.
  • task: string. A BLAST task, such as blastn-short. BLAST only.
  • evalue: number, 1e-20 to 1000.
  • maxHits: integer, 1 to 5000.
  • short: boolean. Settings for short queries.
  • matrix: one of BLOSUM45, BLOSUM50, BLOSUM62, BLOSUM80, BLOSUM90, PAM30, PAM70, PAM250. The protein scoring matrix, for blastp, blastx and tblastn and for ssearch36, glsearch36 and ggsearch36 on protein. Default BLOSUM62, or PAM30 for a blastp query of 30 residues or fewer. Gap costs start at BLAST's default pair for the matrix, and Query Match is scored under it.
  • gapOpen: integer, 0 or more. The cost to open a gap; a gap of n letters costs gapOpen plus n times gapExtend. BLAST takes only the pairs it lists for the matrix, or for blastn's match and mismatch scores, and a request with another pair answers 400 naming the pairs it takes. FASTA36 takes 0 to 99. A cost left out keeps its default.
  • gapExtend: integer, 0 or more. The cost of each letter in a gap. FASTA36 takes 1 to 99.
  • wordSize: integer, 2 to 100. BLAST only: the length of the words a search starts from, 4 to 100 for blastn and 2 to 7 for the others. Default 11 for blastn (7 under 50 bases), 3 for blastp (2 for 30 residues or fewer), and 3 for blastx and tblastn.
  • lowComplexity: boolean. BLAST only: the low-complexity filter, DUST for blastn and SEG for the others. Default on for blastn (off under 50 bases), blastx and tblastn, and off for blastp.
  • geneticCode: one of 1, 2, 3, 4, 5, 6, 9, 10, 11, 12, 13, 14, 15, 16, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 33. blastx and tblastn only: the genetic code that reads the DNA, the query in blastx and the stored sequences in tblastn, as NCBI numbers the codes. Default 1, Standard.
  • pattern: string. The pattern of a pattern search, in the syntax patternSyntax names.
  • patternSyntax: one of prosite, regex, default "prosite". How the pattern is written: prosite, such as AAGCTT-x(2,6)-GGATCC, or regex, a regular expression such as AAGCTT.{2,6}GGATCC or (GGATCC|AAGCTT). It is never guessed from the pattern. A regular expression takes letters, [AG], [^P], ., {m}, {m,n}, {m,}, ?, + (up to 1,000), * (up to 1,000), up to 8 choices and ^ and $; backreferences, lookarounds and repeats on a group are refused. The search record keeps the expression and its PROSITE translation.
  • strands: string. Which strands an exact or pattern search reads.
  • k: integer, 0 to 5. Within k changes only: the most changes a hit may have, below each query's length.
  • changes: one of substitutions, edits. Within k changes only: substitutions counts letters changed in place; edits also counts letters inserted or deleted. An N, an X or another IUPAC code in a query, or a code in a stored protein, matches any letter it stands for, so it is never a change. Stored DNA is read letter for letter: a stored N or other code matches only the same code.
  • title: string. A name for the search, up to 500 characters.
  • followUp: FollowUpFrom.
  • confirmed: boolean. true runs a search this server would ask about first: one estimated to take longer than its time for asking, or one of a large set. Without it, such a search answers 409 with confirm and does not start.

Answers

  • 202: The queued search. Ask GET /api/jobs/{id} until the search ends: completed, failed, cancelled or interrupted.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

POST /api/estimate estimateSearch

Body

JSON (SearchRequest). A search: the queries and where to search. Name a snapshot set (snapshotId and set) or a database (databaseId). Up to 20 queries, 20,000 letters in a query and 100,000 in all. The scoring settings (matrix, gapOpen, gapExtend, wordSize, lowComplexity and geneticCode) need a chosen engine, blast or a FASTA36 one: with auto, the default on a snapshot, any of them answers 400 with "Choose a method to change its settings.", and an exact or pattern search takes none. A setting the program cannot take answers 400 with the reason before anything is queued. The search record lists every setting each query ran with, defaults included, in queries[].settings, and those the request named in parameters.chosenSettings; Run again sends them again.

  • fasta: string. The queries in FASTA or PIR (NBRF), or one sequence as plain letters. A PIR record such as >P1;name has a description line after its header and ends with *; its header gives its type, which must match the search.
  • snapshotId: string. The snapshot, as GET /api/databases lists it.
  • set: string. The set in the snapshot, such as patent_prot.
  • deltas: a list of up to 1000 strings. Weekly additions to search with the snapshot, in order from the first.
  • databaseId: string. An attached or imported database, instead of a snapshot.
  • engine: one of auto, blast, exact, pattern, within, ssearch36, ggsearch36, glsearch36. auto (the default on a snapshot) picks the tool for each query. within (Within k changes) lists every sequence of a snapshot set of the query's own type within k changes of each query, DNA on both strands, with no score or E-value cut, where kscan is installed: queries of up to 64 letters, k up to 5, and up to 50,000 hits a query, the closest first. It takes k and changes, and refuses any other search setting. ssearch36 (Smith-Waterman), glsearch36 (global on the query) and ggsearch36 (global on both sequences) compare each query with every sequence of a snapshot set of its own type, DNA on both strands, where FASTA36 is installed. Each DNA query reads the whole set, so a DNA search whose estimate passes the server's time limit for one search answers 400 and does not start.
  • program: one of blastn, blastp, blastx, tblastn. The query type and direction.
  • task: string. A BLAST task, such as blastn-short. BLAST only.
  • evalue: number, 1e-20 to 1000.
  • maxHits: integer, 1 to 5000.
  • short: boolean. Settings for short queries.
  • matrix: one of BLOSUM45, BLOSUM50, BLOSUM62, BLOSUM80, BLOSUM90, PAM30, PAM70, PAM250. The protein scoring matrix, for blastp, blastx and tblastn and for ssearch36, glsearch36 and ggsearch36 on protein. Default BLOSUM62, or PAM30 for a blastp query of 30 residues or fewer. Gap costs start at BLAST's default pair for the matrix, and Query Match is scored under it.
  • gapOpen: integer, 0 or more. The cost to open a gap; a gap of n letters costs gapOpen plus n times gapExtend. BLAST takes only the pairs it lists for the matrix, or for blastn's match and mismatch scores, and a request with another pair answers 400 naming the pairs it takes. FASTA36 takes 0 to 99. A cost left out keeps its default.
  • gapExtend: integer, 0 or more. The cost of each letter in a gap. FASTA36 takes 1 to 99.
  • wordSize: integer, 2 to 100. BLAST only: the length of the words a search starts from, 4 to 100 for blastn and 2 to 7 for the others. Default 11 for blastn (7 under 50 bases), 3 for blastp (2 for 30 residues or fewer), and 3 for blastx and tblastn.
  • lowComplexity: boolean. BLAST only: the low-complexity filter, DUST for blastn and SEG for the others. Default on for blastn (off under 50 bases), blastx and tblastn, and off for blastp.
  • geneticCode: one of 1, 2, 3, 4, 5, 6, 9, 10, 11, 12, 13, 14, 15, 16, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 33. blastx and tblastn only: the genetic code that reads the DNA, the query in blastx and the stored sequences in tblastn, as NCBI numbers the codes. Default 1, Standard.
  • pattern: string. The pattern of a pattern search, in the syntax patternSyntax names.
  • patternSyntax: one of prosite, regex, default "prosite". How the pattern is written: prosite, such as AAGCTT-x(2,6)-GGATCC, or regex, a regular expression such as AAGCTT.{2,6}GGATCC or (GGATCC|AAGCTT). It is never guessed from the pattern. A regular expression takes letters, [AG], [^P], ., {m}, {m,n}, {m,}, ?, + (up to 1,000), * (up to 1,000), up to 8 choices and ^ and $; backreferences, lookarounds and repeats on a group are refused. The search record keeps the expression and its PROSITE translation.
  • strands: string. Which strands an exact or pattern search reads.
  • k: integer, 0 to 5. Within k changes only: the most changes a hit may have, below each query's length.
  • changes: one of substitutions, edits. Within k changes only: substitutions counts letters changed in place; edits also counts letters inserted or deleted. An N, an X or another IUPAC code in a query, or a code in a stored protein, matches any letter it stands for, so it is never a change. Stored DNA is read letter for letter: a stored N or other code matches only the same code.
  • title: string. A name for the search, up to 500 characters.
  • followUp: FollowUpFrom.
  • confirmed: boolean. true runs a search this server would ask about first: one estimated to take longer than its time for asking, or one of a large set. Without it, such a search answers 409 with confirm and does not start.

Answers

  • 200: Seconds, or null where the server has not yet timed this kind of search.
  • Errors: 400, 401, 403, 404, 413, 415, 429, 503, as under Errors above.

One job and its state

GET /api/jobs/{id} getJob

Parameters

  • id, in the path, required: string.

Answers

  • 200: The job.
  • Errors: 400, 401, 403, 404, as under Errors above.

Cancel a job that has not finished

DELETE /api/jobs/{id} cancelJob

Parameters

  • id, in the path, required: string.

Answers

  • 200: The job, cancelled, or as it ended.
  • Errors: 400, 401, 403, 404, as under Errors above.

The full search record

GET /api/jobs/{id}/result getJobResult

The record a search keeps: its database or snapshot, parameters, queries, every hit, and SHA-256 fingerprints. 409 until the search has completed. computed, beside the record, lists the measures Sequences computes when it reads the result; the record and its fingerprint stay as the search wrote them.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The record.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Run a search again as a new job

POST /api/jobs/{id}/again runJobAgain

A search that still waits or runs answers 409 with the code not-allowed-in-state: run it again once it has ended, or cancel it first.

Parameters

  • id, in the path, required: string.

Body

JSON. An empty object, or confirmed for a search this server asks about first.

  • confirmed: boolean. true runs a search this server would ask about first: one estimated to take longer than its time for asking, or one of a large set. Without it, such a search answers 409 with confirm and does not start.

Answers

  • 202: The new job, with the same query, settings, snapshot and deltas.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

The request a search was started with

GET /api/jobs/{id}/request getJobRequest

The fields the search was started with, query included: the ones Run again sends. Null for a search saved before searches kept them, and for a job that is not a search.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The request.
  • Errors: 400, 401, 403, 404, as under Errors above.

The searches a finished search suggests running next

GET /api/jobs/{id}/follow-ups getFollowUps

Fixed rules read the finished search and suggest the next searches, each with its rule, its reason from the result and the search it would run. No model takes part, so the same result gives the same suggestions. The rules, in order: few hits or none at the identity asked (a more sensitive method on the same sets, or a set not yet searched), the hit limit reached (more hits, or a narrower identity or coverage), part of the query unmatched (that part as a fragment), the other molecule type (a translated search) and an antibody chain (its CDRs). The first 3 not dismissed are listed, each recorded the first time it is. fill gives what the search form takes to run one. A search run from a case's plan lists none here: caseId names its case, which lists them (GET /api/cases/{id}/follow-ups).

Parameters

  • id, in the path, required: string.

Answers

  • 200: The suggestions, the search this one follows and the record.
  • Errors: 400, 401, 403, 404, as under Errors above.

Dismiss a suggested search, or record that its filter went on the list

POST /api/jobs/{id}/follow-ups answerFollowUp

dismiss hides a suggestion, and the next one that applies takes its place. apply records that a narrower identity or coverage, which only the hit limit rule suggests, went on the list as filters. To run a suggestion, start its search with followUp naming this search (POST /api/jobs, POST /api/groups or POST /api/antibody/searches): the record of each search then names the other. 404 for a suggestion this search did not show; 409 for a search run from a case's plan.

Parameters

  • id, in the path, required: string.

Body

JSON (FollowUpAction).

  • action, required: one of dismiss, apply.
  • key, required: string. The suggestion, as listed.

Answers

  • 200: The suggestions and the record after the change.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Results

Hits, patents, alignments, CSV files and marks.

One page of hits

GET /api/jobs/{id}/hits getHits

Parameters

  • id, in the path, required: string.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.
  • sort, in the query: one of score, bits, evalue, identity, identityX, coverage, queryIdentity, queryMatch, occurrences, default "score". identityX sorts by Identity with an X (N in DNA) in the stored sequence counted as a match.
  • order, in the query: one of asc, desc.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • species, in the query: string. Only hits with a record in one of these species groups or NCBI taxa, separated by commas, up to 50, such as human,10090. On the patents list, only the publications whose own record is. The groups: human, mouse, rat, other-rodents, other-primates, camelids, other-mammals, other-animals, plants, fungi, bacteria, viruses, other, artificial, not-stated, not-matched. 409 for a search whose records no taxa folder placed.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • claimed, in the query: one of only. only keeps the hits whose SEQ ID NO a claim of one of their US publications names, on a search the claimed sequences add-on wrote into. On the patents list, only the publications whose own claims name a hit's SEQ ID NO.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • area, in the query: string. Only hits inside an area of the Identity against coverage chart: identity from and to, then query coverage from and to, in percent, both ends included, such as 80,95,60,100. A hit with no identity, such as a pattern row, is outside every area.
  • xAsMatch, in the query: one of true, false, default "false". true holds identity to Identity, X as a match (identityXPct): an X in a stored protein, or an N in stored DNA, counts as a match. Exact and pattern searches keep their meaning.
  • publication, in the query: string. Only the hits whose sequence has a record in this publication, by its id from the patents list ("unknown" for records of no known publication). Each row then gains seqNos, its SEQ ID NOs there. 404 for a publication the search does not hold.

Answers

  • 200: The hits after filters and marks.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The numbers behind the three result charts

GET /api/jobs/{id}/charts getCharts

Identity against coverage, Where hits align on the query and Hits by year, from the rows the hits list reads with the same filters and marks. The cutoffs, the area and publishedBefore do not drop hits here: each hit keeps its date group and says whether it passes the cutoffs and the area, and listed counts the hits the list shows. Hits that publishedFrom leaves out of the list are left out here too. The alignment chart takes the list's first 20 hits of one query (query, or the first row's), in its sort and order, each with the runs of query positions where it differs, has a gap, or has the letter for any residue (X, or N in DNA). The years chart counts the Patents list's rows, later ones shown, by year of publication (group=family: each family by its first), or the hits by year of first publication on a database with no patents.

Parameters

  • id, in the path, required: string.
  • sort, in the query: one of score, bits, evalue, identity, identityX, coverage, queryIdentity, queryMatch, occurrences, default "score". identityX sorts by Identity with an X (N in DNA) in the stored sequence counted as a match.
  • order, in the query: one of asc, desc.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • species, in the query: string. Only hits with a record in one of these species groups or NCBI taxa, separated by commas, up to 50, such as human,10090. On the patents list, only the publications whose own record is. The groups: human, mouse, rat, other-rodents, other-primates, camelids, other-mammals, other-animals, plants, fungi, bacteria, viruses, other, artificial, not-stated, not-matched. 409 for a search whose records no taxa folder placed.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • claimed, in the query: one of only. only keeps the hits whose SEQ ID NO a claim of one of their US publications names, on a search the claimed sequences add-on wrote into. On the patents list, only the publications whose own claims name a hit's SEQ ID NO.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • area, in the query: string. Only hits inside an area of the Identity against coverage chart: identity from and to, then query coverage from and to, in percent, both ends included, such as 80,95,60,100. A hit with no identity, such as a pattern row, is outside every area.
  • xAsMatch, in the query: one of true, false, default "false". true holds identity to Identity, X as a match (identityXPct): an X in a stored protein, or an N in stored DNA, counts as a match. Exact and pattern searches keep their meaning.
  • group, in the query: one of family, publication, default "publication". family gives one row per patent family. Absent, one row per publication.

Answers

  • 200: The numbers of each chart.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The species and groups of a search's hits, with counts

GET /api/jobs/{id}/species getSpecies

The choices of the species filter: each group and each NCBI taxon that a record of a hit holds, with the hits that hold it, whatever the other filters. 409 for a search whose records no taxa folder placed: one run before the server had BIOSEQUENCE_TAXA.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The groups in the order the filter lists them, then the taxa by hits.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

One hit by its row number

GET /api/jobs/{id}/hits/{row} getHit

The hit with its measures, positions, records and mark, whatever the filters. A combined search's references name each match by its job and row, and the page's review pane reads the match here.

Parameters

  • id, in the path, required: string.
  • row, in the path, required: string.

Answers

  • 200: The hit and the search's queries.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The alignment of one hit

GET /api/jobs/{id}/hits/{row}/alignment getHitAlignment

Parameters

  • id, in the path, required: string.
  • row, in the path, required: string.

Answers

  • 200: The aligned query and subject.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The hits as CSV, or in an export format

GET /api/jobs/{id}/export.csv exportHits

Parameters

  • id, in the path, required: string.
  • sort, in the query: one of score, bits, evalue, identity, identityX, coverage, queryIdentity, queryMatch, occurrences, default "score". identityX sorts by Identity with an X (N in DNA) in the stored sequence counted as a match.
  • order, in the query: one of asc, desc.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • species, in the query: string. Only hits with a record in one of these species groups or NCBI taxa, separated by commas, up to 50, such as human,10090. On the patents list, only the publications whose own record is. The groups: human, mouse, rat, other-rodents, other-primates, camelids, other-mammals, other-animals, plants, fungi, bacteria, viruses, other, artificial, not-stated, not-matched. 409 for a search whose records no taxa folder placed.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • claimed, in the query: one of only. only keeps the hits whose SEQ ID NO a claim of one of their US publications names, on a search the claimed sequences add-on wrote into. On the patents list, only the publications whose own claims name a hit's SEQ ID NO.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • area, in the query: string. Only hits inside an area of the Identity against coverage chart: identity from and to, then query coverage from and to, in percent, both ends included, such as 80,95,60,100. A hit with no identity, such as a pattern row, is outside every area.
  • xAsMatch, in the query: one of true, false, default "false". true holds identity to Identity, X as a match (identityXPct): an X in a stored protein, or an N in stored DNA, counts as a match. Exact and pattern searches keep their meaning.
  • format, in the query: string, default "Built-in". The export format, by its name: Built-in, the CSV this export always gives, as when absent, or a format this server's export formats file defines for this export, as GET /api/status lists them under exports.formats. An external format leaves out every row a confidential set found. 400 for a name that serves no format of this export.

Answers

  • 200: Every hit that passes the filters. The search's exports list notes the export. As text/csv or text/tab-separated-values or application/x-ndjson.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

A portable result for the Lab Notebook Inbox

GET /api/jobs/{id}/labitem.zip exportNotebookItem

Completed paged sequence searches only. Includes the search record and all stored match rows, including excluded matches; query filters and external export formats do not apply. Expanded ZIP entries are limited to 32 MiB. The record may describe source files not included here; this is not a restorable search directory.

Parameters

  • id, in the path, required: string.

Answers

  • 200: A conductscience.lab-notebook.item/1 package, imported offline. As application/zip.
  • Errors: 400, 401, 403, 404, 409, 413, as under Errors above.

What a US publication says about its SEQ ID NOs

GET /api/patent-context getPatentContext

From the patent context folder the server names (BIOSEQUENCE_CONTEXT), built from the US patent office's weekly full-text files with the snapshot; a search adds no time and no outside site is asked. Without a folder the answer is installed: false, and a publication the folder does not hold answers found: false. A US publication answers context; one of another office answers other, where the folder holds what EPO's Open Patent Services gave for it (cli.mjs context ops). lines comes from fixed rules, such as "SEQ ID NO 1 is named in claims 1 and 3 and in paragraphs [0012] and [0040]."; the quotes are the document's own words, and a quote cut at its length says cut.

Parameters

  • publication, in the query, required: string. The publication by its id from the patents list: office|number|kind|published.
  • seq, in the query: string. The matching SEQ ID NOs, as 1,3,10; at most 200.

Answers

  • 200: What the pane shows for the publication.
  • Errors: 400, 401, 403, as under Errors above.

One page of patents with hits

GET /api/jobs/{id}/publications getPublications

Rows equal in the chosen measure go earliest publication first, undated last, then by ID. Under published, rows of one date go highest Query Match first, then highest identity, then by ID. group=family gives one row per patent family, and later=hide folds the publications from on or after publishedBefore and counts them. group=applicant, office or year gives one row per publication, in the sort, gathered under groups: by applicant as the applicants route groups them, by office most publications first, or by year of publication oldest first (newest first under sort=published&order=desc), with the rows of no applicant, office or date last. Each row then has groupKey, and groups says how many groups have a name, how many rows have none, and the groups the page shows.

Parameters

  • id, in the path, required: string.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.
  • sort, in the query: one of bestQueryMatch, bestIdentity, published, sequencesHit, hits.
  • order, in the query: one of asc, desc.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • species, in the query: string. Only hits with a record in one of these species groups or NCBI taxa, separated by commas, up to 50, such as human,10090. On the patents list, only the publications whose own record is. The groups: human, mouse, rat, other-rodents, other-primates, camelids, other-mammals, other-animals, plants, fungi, bacteria, viruses, other, artificial, not-stated, not-matched. 409 for a search whose records no taxa folder placed.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • claimed, in the query: one of only. only keeps the hits whose SEQ ID NO a claim of one of their US publications names, on a search the claimed sequences add-on wrote into. On the patents list, only the publications whose own claims name a hit's SEQ ID NO.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • area, in the query: string. Only hits inside an area of the Identity against coverage chart: identity from and to, then query coverage from and to, in percent, both ends included, such as 80,95,60,100. A hit with no identity, such as a pattern row, is outside every area.
  • xAsMatch, in the query: one of true, false, default "false". true holds identity to Identity, X as a match (identityXPct): an X in a stored protein, or an N in stored DNA, counts as a match. Exact and pattern searches keep their meaning.
  • group, in the query: one of family, publication, applicant, office, year, default "publication". family gives one row per patent family; applicant, office and year give one row per publication under a heading for each group. Absent, one row per publication.
  • later, in the query: one of hide, show, default "show". hide folds the publications from on or after publishedBefore and adds later to the answer. Absent, they show.
  • row, in the query: integer, 1 or more. Every publication of this hit's sequence, by the row number the alignment route takes, whatever the filters. The earliest comes first unless a sort is given, and undated publications come last. publishedBefore marks later publications and hides none. Each row keeps its mark, so excluded patents are listed too. 404 for a row the search does not hold.

Answers

  • 200: The patents after filters and marks.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The patents as CSV, or in an export format

GET /api/jobs/{id}/publications.csv exportPublications

One line per publication, the later ones too, whatever group and later say. The last four columns are family (the label of the family's earliest publication), family_size, family_basis and date_group (empty when no date is set).

Parameters

  • id, in the path, required: string.
  • sort, in the query: one of bestQueryMatch, bestIdentity, published, sequencesHit, hits.
  • order, in the query: one of asc, desc.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • species, in the query: string. Only hits with a record in one of these species groups or NCBI taxa, separated by commas, up to 50, such as human,10090. On the patents list, only the publications whose own record is. The groups: human, mouse, rat, other-rodents, other-primates, camelids, other-mammals, other-animals, plants, fungi, bacteria, viruses, other, artificial, not-stated, not-matched. 409 for a search whose records no taxa folder placed.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • claimed, in the query: one of only. only keeps the hits whose SEQ ID NO a claim of one of their US publications names, on a search the claimed sequences add-on wrote into. On the patents list, only the publications whose own claims name a hit's SEQ ID NO.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • area, in the query: string. Only hits inside an area of the Identity against coverage chart: identity from and to, then query coverage from and to, in percent, both ends included, such as 80,95,60,100. A hit with no identity, such as a pattern row, is outside every area.
  • xAsMatch, in the query: one of true, false, default "false". true holds identity to Identity, X as a match (identityXPct): an X in a stored protein, or an N in stored DNA, counts as a match. Exact and pattern searches keep their meaning.
  • format, in the query: string, default "Built-in". The export format, by its name: Built-in, the CSV this export always gives, as when absent, or a format this server's export formats file defines for this export, as GET /api/status lists them under exports.formats. An external format leaves out every row a confidential set found. 400 for a name that serves no format of this export.

Answers

  • 200: Every patent that passes the filters. The search's exports list notes the export. As text/csv or text/tab-separated-values or application/x-ndjson.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Every tab and the search record as one Excel workbook

GET /api/jobs/{id}/export.xlsx exportWorkbook

Sheets in the page's order: Patents (the rows of publications.csv), Families when group=family, Applicants (the rows of applicants.csv), Alignments (Matches for an exact or pattern search; the rows of export.csv), Aligned letters for a search that aligns (the first 10,000 rows of Alignments in its order, each with the aligned letters of the query, the match line and the subject, and those of its exact alignment where there is one), then Search record. The filters apply to every sheet. Text over 32,767 characters and rows past 1,048,575 are cut, and the Search record says so. X-Export-Rows counts every sheet but Aligned letters and the Search record. 413 when the file would pass 4 GiB. The search's exports list notes it as workbook.

Parameters

  • id, in the path, required: string.
  • hitSort, in the query: one of score, bits, evalue, identity, coverage, queryIdentity, queryMatch, occurrences. The sort of the Alignments or Matches sheet.
  • hitOrder, in the query: one of asc, desc.
  • patentSort, in the query: one of bestQueryMatch, bestIdentity, published, sequencesHit, hits. The sort of the Patents and Families sheets.
  • patentOrder, in the query: one of asc, desc.
  • group, in the query: one of family, publication, default "publication". family gives one row per patent family. Absent, one row per publication.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.

Answers

  • 200: The workbook. As application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.
  • Errors: 400, 401, 403, 404, 409, 413, as under Errors above.

The hits' stored sequences as FASTA

GET /api/jobs/{id}/hits.fasta exportHitsFasta

which=filtered, as when absent, holds the hits the list shows with the same filters, sort and marks, every page; kept, every row marked Keep; selected, the rows that rows names. The kept and the selected rows keep the list's order whatever its filters. Each stored sequence comes once, whole, from the search's snapshot, 60 letters a line, and the file stops before 100,000,000 letters. 409 for a search that read no snapshot, and when no hit is kept or none passes the filters. The search's exports list does not note it.

Parameters

  • id, in the path, required: string.
  • which, in the query: one of filtered, kept, selected, default "filtered". The hits a FASTA file holds: filtered, those the list shows; kept, those marked Keep; selected, the rows that rows names.
  • rows, in the query: string. Rows by the numbers the hits route gives, with runs, such as 12,15,40-49: 1 to 1,000 rows of the search.
  • sort, in the query: one of score, bits, evalue, identity, identityX, coverage, queryIdentity, queryMatch, occurrences, default "score". identityX sorts by Identity with an X (N in DNA) in the stored sequence counted as a match.
  • order, in the query: one of asc, desc.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • species, in the query: string. Only hits with a record in one of these species groups or NCBI taxa, separated by commas, up to 50, such as human,10090. On the patents list, only the publications whose own record is. The groups: human, mouse, rat, other-rodents, other-primates, camelids, other-mammals, other-animals, plants, fungi, bacteria, viruses, other, artificial, not-stated, not-matched. 409 for a search whose records no taxa folder placed.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • claimed, in the query: one of only. only keeps the hits whose SEQ ID NO a claim of one of their US publications names, on a search the claimed sequences add-on wrote into. On the patents list, only the publications whose own claims name a hit's SEQ ID NO.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • area, in the query: string. Only hits inside an area of the Identity against coverage chart: identity from and to, then query coverage from and to, in percent, both ends included, such as 80,95,60,100. A hit with no identity, such as a pattern row, is outside every area.
  • xAsMatch, in the query: one of true, false, default "false". true holds identity to Identity, X as a match (identityXPct): an X in a stored protein, or an N in stored DNA, counts as a match. Exact and pattern searches keep their meaning.

Answers

  • 200: One entry for each stored sequence: its accession and first publication, then the query it matched and how well, such as >A00003.1 EP 0238993-A2; published 1987-09-30, Example Pharma A/S; query cb1, identity 100.0%, query coverage 100.0%. As text/x-fasta.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The alignments of chosen rows as text

GET /api/jobs/{id}/alignments.txt exportAlignments

rows names 1 to 1,000 rows. Each row's alignment comes as the review pane's Copy alignment gives it, with its exact alignment where there is one, in the list's order. A row with no alignment, such as a row of an imported result file, says so. The search's exports list does not note it.

Parameters

  • id, in the path, required: string.
  • rows, in the query: string. Rows by the numbers the hits route gives, with runs, such as 12,15,40-49: 1 to 1,000 rows of the search.
  • sort, in the query: one of score, bits, evalue, identity, identityX, coverage, queryIdentity, queryMatch, occurrences, default "score". identityX sorts by Identity with an X (N in DNA) in the stored sequence counted as a match.
  • order, in the query: one of asc, desc.

Answers

  • 200: A head that names the search, then each row. As text/plain.
  • Errors: 400, 401, 403, 404, as under Errors above.

The kept publications as a reference list

GET /api/jobs/{id}/references.txt exportReferences

Every publication marked Keep, earliest first and undated last, each numbered with its number and kind, date, title and applicant. 409 when none is kept, or the search has no publication records. The search's exports list does not note it.

Parameters

  • id, in the path, required: string.

Answers

  • 200: A head that names the search, then one numbered line for each publication. As text/plain.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Each export of the hits and the patents

GET /api/jobs/{id}/exports listJobExports

Oldest first. Each names when and by whom, the export, the format's name, version, audience, type and SHA-256, the file's SHA-256 and size, its rows, and the rows and fields redacted. It never holds a value from the file.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The exports of the search.
  • Errors: 400, 401, 403, 404, as under Errors above.

One page of applicants with hits

GET /api/jobs/{id}/applicants getApplicants

The patents after the filters, by applicant: spellings that differ only in case, accents, punctuation or a legal ending such as Inc share a row, and the account's joins apply. 50 rows by default.

Parameters

  • id, in the path, required: string.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • species, in the query: string. Only hits with a record in one of these species groups or NCBI taxa, separated by commas, up to 50, such as human,10090. On the patents list, only the publications whose own record is. The groups: human, mouse, rat, other-rodents, other-primates, camelids, other-mammals, other-animals, plants, fungi, bacteria, viruses, other, artificial, not-stated, not-matched. 409 for a search whose records no taxa folder placed.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • claimed, in the query: one of only. only keeps the hits whose SEQ ID NO a claim of one of their US publications names, on a search the claimed sequences add-on wrote into. On the patents list, only the publications whose own claims name a hit's SEQ ID NO.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • area, in the query: string. Only hits inside an area of the Identity against coverage chart: identity from and to, then query coverage from and to, in percent, both ends included, such as 80,95,60,100. A hit with no identity, such as a pattern row, is outside every area.
  • xAsMatch, in the query: one of true, false, default "false". true holds identity to Identity, X as a match (identityXPct): an X in a stored protein, or an N in stored DNA, counts as a match. Exact and pattern searches keep their meaning.

Answers

  • 200: The applicants after the filters.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The applicants as CSV

GET /api/jobs/{id}/applicants.csv exportApplicants

Parameters

  • id, in the path, required: string.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • species, in the query: string. Only hits with a record in one of these species groups or NCBI taxa, separated by commas, up to 50, such as human,10090. On the patents list, only the publications whose own record is. The groups: human, mouse, rat, other-rodents, other-primates, camelids, other-mammals, other-animals, plants, fungi, bacteria, viruses, other, artificial, not-stated, not-matched. 409 for a search whose records no taxa folder placed.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • claimed, in the query: one of only. only keeps the hits whose SEQ ID NO a claim of one of their US publications names, on a search the claimed sequences add-on wrote into. On the patents list, only the publications whose own claims name a hit's SEQ ID NO.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • area, in the query: string. Only hits inside an area of the Identity against coverage chart: identity from and to, then query coverage from and to, in percent, both ends included, such as 80,95,60,100. A hit with no identity, such as a pattern row, is outside every area.
  • xAsMatch, in the query: one of true, false, default "false". true holds identity to Identity, X as a match (identityXPct): an X in a stored protein, or an N in stored DNA, counts as a match. Exact and pattern searches keep their meaning.

Answers

  • 200: Every applicant row that passes the filters. As text/csv.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Exact alignments of chosen hits

POST /api/jobs/{id}/align alignRows

Parameters

  • id, in the path, required: string.

Body

JSON.

  • rows, required: a list of 1 to 1000 integers, each 1 or more. Hit row numbers.
  • method: one of local, query. local (Smith-Waterman) or query (the whole query against a part of the subject).

Answers

  • 202: The alignment job.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

Keep or exclude a patent, a family or a hit

POST /api/jobs/{id}/marks markResult

Give id to mark one patent or hit. Give ids to mark up to 500 patents at once, as Keep or Exclude on a family row does with its family.ids: each gets its own mark entry, written together.

Parameters

  • id, in the path, required: string.

Body

JSON (MarkRequest).

  • target, required: one of publication, row.
  • id: any value. The patent ID or the hit row number.
  • ids: a list of 1 to 500 strings. Up to 500 patent IDs, such as a family row's family.ids. Each gets its own mark. target must be publication.
  • action, required: one of keep, exclude, clear.
  • reason: string. Why, up to 500 characters.

Answers

  • 201: The mark, or with ids the marks.
  • Errors: 400, 401, 403, 404, 415, as under Errors above.

The changes in force on a search's hits, and every change and undo

GET /api/jobs/{id}/transforms listTransforms

The changes in force on the search's hits, in the order they were added, each with what it does to the whole list, and every change and undo, oldest first, with its time. GET /api/jobs/{id}/hits (without publication), export.csv and the Alignments sheet of export.xlsx show the hits under the changes in force, and the Search record sheet lists them. The Patents and Applicants lists, a patent's own hits and a case report read the hits as the search left them. The changes are kept beside the search, so its record and its SHA-256 never change.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The changes in force and the history.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Change a search's hits: fold them, count X as a match, or keep some

POST /api/jobs/{id}/transforms addTransform

Adds one change, up to 12 in force at once. fold makes hits with the same alignment (the same query letters against the same letters) one row, the one first published, and its folded gives the count and the rows. countX counts an X in a protein hit, or an N in DNA, as a match: identity and query identity are counted again from the alignment, and Query Match too on a protein search; each row it changed carries counted. cover keeps the hits of one query whose alignment covers every query position between from and to, both included. differ keeps the hits of one query that differ from it, by another letter or a gap, at any of up to 50 positions, or with all at every one; a position outside a hit's alignment does not count, and under countX an X or N matches. intersect keeps the hits whose sequence each of up to 5 other finished searches also found: by subject on the same snapshot, set and weekly additions, else by the SHA-256 of the letters. fold, countX and differ read every alignment, on searches of up to 200,000 rows. 409 when a search it names has not finished or cannot be matched: it keeps its results only in its full record, it read another database, or the searches found more than 200,000 sequences to match by their letters.

Parameters

  • id, in the path, required: string.

Body

JSON (TransformRequest). One change. query names a query by its number, from 1; a search of one query needs none.

  • kind, required: one of fold, countX, cover, differ, intersect.
  • query: integer, 1 or more. cover and differ: the query.
  • from: integer, 1 or more. cover: the first query position.
  • to: integer, 1 or more. cover: the last query position.
  • positions: a list of 1 to 50 integers, each 1 or more, or a string. differ: up to 50 query positions, as an array or as text such as "3, 7, 12".
  • all: boolean. differ: true keeps the hits that differ at every position; false, the default, at any of them.
  • jobs: a list of 1 to 5 strings. intersect: the other finished searches.

Answers

  • 201: The change as kept, then the changes in force and the history.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Undo one change to a search's hits

POST /api/jobs/{id}/transforms/{n}/undo undoTransform

Takes back the change whose seq is n. The undo is kept as a change of its own, so the history holds both. 404 for a number the search never gave; 409 for a change already undone.

Parameters

  • id, in the path, required: string.
  • n, in the path, required: string.

Answers

  • 200: The undo as kept, then the changes in force and the history.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Two to six finished searches, matched by the sequences they found

GET /api/compare compareSearches

Each search is one the account can open, finished, with its results in pages, and is numbered by its place in jobs. Each sequence found falls in one part, named by the numbers of the searches that found it, lowest first: 1 holds the sequences only search 1 found, and 1,2 those searches 1 and 2 found. parts lists them one search first, then two and so on, each with its count. matchedBy says how sequences match: subject when every search read the same snapshot set and deltas, or the same database; sequence, by the SHA-256 of the letters the snapshots store, when they read different snapshots or sets, for at most 200,000 sequences over all the searches (400 past that); and target otherwise, so a sequence matches only within its own database. rows is one page of part, or of the first part when part is absent, by the best Query Match any search gives a sequence, then identity, then the earliest published, undated last. part=any lists every sequence any of the searches found, the union of the parts, in the same order. Each row's found holds an entry for each search in order, null where that search did not find the sequence: its best row for it (highest Query Match, then identity, bit score and lowest E-value) and how many rows it has. 404 for a search the account cannot open; 409 for one that is not a search, is waiting or running, ended without finishing, keeps its results in its full record, or read a snapshot no longer on this server.

Parameters

  • jobs, in the query, required: a list of 2 to 6 strings. 2 to 6 search job IDs, separated by commas, each named once. Their order numbers the searches.
  • part, in the query: string. The part to list, by the numbers of the searches that found its sequences, lowest first, such as 1 or 1,2, or any for every sequence any of them found. Absent, the first part.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500, default 50. Sequences in the page.

Answers

  • 200: The searches, their parts and one page of one part.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

A snapshot record's letters

GET /api/sequences getSequence

Name the record by accession, or by publication and SEQ ID NO; from and to give a stretch.

Parameters

  • snapshotId, in the query: string.
  • set, in the query: string.
  • accession, in the query: string.
  • publication, in the query: string.
  • seqIdNo, in the query: string.
  • from, in the query: integer, 1 or more.
  • to, in the query: integer, 1 or more.

Answers

  • 200: The record and its letters.
  • Errors: 400, 401, 403, 404, 413, as under Errors above.

Batches

Many searches in one request.

Start many searches at once

POST /api/batches createBatch

Takes 1 to 100 searches, each the body of POST /api/jobs, and checks every one before any job starts. If any cannot run, the answer is 400 with a problem for each, and nothing starts. A search this server would ask about first is a problem with status 409 until it has "confirmed": true. An account may have 200 batch searches waiting or running at once, and the server 1000. Batch jobs wait behind searches started from the page.

Body

JSON (BatchRequest).

  • searches, required: a list of 1 to 100 SearchRequest objects.

Answers

  • 202: The batch: its ID and one job ID for each search, in order.
  • Errors: 400, 401, 403, 404, 413, 415, 429, 503, as under Errors above.

Each job's state

GET /api/batches/{id} getBatch

Parameters

  • id, in the path, required: string.

Answers

  • 200: The batch and its jobs.
  • Errors: 400, 401, 403, 404, as under Errors above.

The publications or sequences that several of a batch's queries hit

GET /api/batches/{id}/multi-hits getBatchMultiHits

Counts the batch's finished searches together, a query group's among them: for each publication (by=publication, as each search's Patents tab groups its hits) or each stored sequence (by=sequence, from each search's Alignments list), how many of the batch's queries hit it. rows lists those that at least minQueries queries hit, most queries first, then by best Query Match, best identity and earliest date, each with the names of its queries in the batch's order and the numbers of the searches that found it. A query counts once, however many of the searches ran it: queries with the same letters are one query. identity, coverage, publishedFrom, publishedBefore and office apply to each search as they apply to its own lists, and what its marks exclude does not count. levels counts the rows each number of queries hit. A search that has not finished is in searches.waiting; one that did not finish, is no longer on the server, keeps its results in one record or, counting publications, has no publication records is in searches.notCounted with its reason. A stored sequence is one sequence within one set or database, so when the searches read more than one, matchedBy is target and a sequence counts the queries of its own set's searches. A query group's search is one batch: its ID is batchId in the group's searches. One count holds up to 200,000 publications or sequences; past that the answer is 409.

Parameters

  • id, in the path, required: string.
  • by, in the query: one of publication, sequence, default "publication". What to count: publication, each publication as the Patents tab lists it, or sequence, each stored sequence.
  • minQueries, in the query: integer, 1 to 1000000, default 2. Lists the rows that at least this many of the batch's queries hit.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500, default 50. Rows in the page.

Answers

  • 200: The count and one page of its rows.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Every row of that count as CSV

GET /api/batches/{id}/multi-hits.csv getBatchMultiHitsCsv

Every row that at least minQueries queries hit, in the order of the JSON answer, counted the same way. query_names joins the names with "; " and searches the numbers with spaces.

Parameters

  • id, in the path, required: string.
  • by, in the query: one of publication, sequence, default "publication". What to count: publication, each publication as the Patents tab lists it, or sequence, each stored sequence.
  • minQueries, in the query: integer, 1 to 1000000, default 2. Lists the rows that at least this many of the batch's queries hit.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.

Answers

  • 200: One row for each publication (by=publication): queries, query_names, office, number, kind, published, applicant, title, sequences_hit, best_query_match, best_identity, searches, link. Or one for each stored sequence (by=sequence): queries, query_names, subject, accession, title, set, first_published, publications, subject_length, best_query_match, best_identity, searches. As text/csv.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Combined searches

One search across several sets, and one list of what they found.

Search several sets at once

POST /api/groups createGroup

Takes the body of POST /api/jobs with targets in place of one set: 2 to 8 snapshot sets or attached databases, each once. Each target gets its own job, with the program the query's type and the set's type call for and the engine's usual choice of tool: a protein query searches a DNA set with tblastn, and such a job has no Query Match. Every target is checked before any job starts. One that cannot run, such as an unknown set, or a set of the other type under Exact text, Pattern, Smith-Waterman or a global method, answers 400 with a problem naming it, and nothing starts. The jobs take room in the queue as searches from the page do, whether the request came from the page or with an API token. With too little room the answer is 429 with room, and nothing starts. On a server with compute limits, a combined search that reads a large set, or whose jobs should take longer together than the server's time for asking, answers 409 with confirm: send it again with "confirmed": true.

Body

JSON (CombinedSearchRequest). The body of POST /api/jobs with targets in place of one set. program names the query type, and each target gets the program its own type calls for: DNA against a protein set runs blastx, protein against a DNA set runs tblastn. Exact text, Pattern, Smith-Waterman and the global methods compare like with like, so every target must hold the query's type; without program, the first target sets it.

  • fasta: string. The queries in FASTA or PIR (NBRF), or one sequence as plain letters. A PIR record such as >P1;name has a description line after its header and ends with *; its header gives its type, which must match the search.
  • engine: one of auto, blast, exact, pattern, within, ssearch36, ggsearch36, glsearch36. auto (the default on a snapshot) picks the tool for each query. within (Within k changes) lists every sequence of a snapshot set of the query's own type within k changes of each query, DNA on both strands, with no score or E-value cut, where kscan is installed: queries of up to 64 letters, k up to 5, and up to 50,000 hits a query, the closest first. It takes k and changes, and refuses any other search setting. ssearch36 (Smith-Waterman), glsearch36 (global on the query) and ggsearch36 (global on both sequences) compare each query with every sequence of a snapshot set of its own type, DNA on both strands, where FASTA36 is installed. Each DNA query reads the whole set, so a DNA search whose estimate passes the server's time limit for one search answers 400 and does not start.
  • program: one of blastn, blastp, blastx, tblastn. The query type and direction.
  • task: string. A BLAST task, such as blastn-short. BLAST only.
  • evalue: number, 1e-20 to 1000.
  • maxHits: integer, 1 to 5000.
  • short: boolean. Settings for short queries.
  • matrix: one of BLOSUM45, BLOSUM50, BLOSUM62, BLOSUM80, BLOSUM90, PAM30, PAM70, PAM250. The protein scoring matrix, for blastp, blastx and tblastn and for ssearch36, glsearch36 and ggsearch36 on protein. Default BLOSUM62, or PAM30 for a blastp query of 30 residues or fewer. Gap costs start at BLAST's default pair for the matrix, and Query Match is scored under it.
  • gapOpen: integer, 0 or more. The cost to open a gap; a gap of n letters costs gapOpen plus n times gapExtend. BLAST takes only the pairs it lists for the matrix, or for blastn's match and mismatch scores, and a request with another pair answers 400 naming the pairs it takes. FASTA36 takes 0 to 99. A cost left out keeps its default.
  • gapExtend: integer, 0 or more. The cost of each letter in a gap. FASTA36 takes 1 to 99.
  • wordSize: integer, 2 to 100. BLAST only: the length of the words a search starts from, 4 to 100 for blastn and 2 to 7 for the others. Default 11 for blastn (7 under 50 bases), 3 for blastp (2 for 30 residues or fewer), and 3 for blastx and tblastn.
  • lowComplexity: boolean. BLAST only: the low-complexity filter, DUST for blastn and SEG for the others. Default on for blastn (off under 50 bases), blastx and tblastn, and off for blastp.
  • geneticCode: one of 1, 2, 3, 4, 5, 6, 9, 10, 11, 12, 13, 14, 15, 16, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 33. blastx and tblastn only: the genetic code that reads the DNA, the query in blastx and the stored sequences in tblastn, as NCBI numbers the codes. Default 1, Standard.
  • pattern: string. The pattern of a pattern search, in the syntax patternSyntax names.
  • patternSyntax: one of prosite, regex, default "prosite". How the pattern is written: prosite, such as AAGCTT-x(2,6)-GGATCC, or regex, a regular expression such as AAGCTT.{2,6}GGATCC or (GGATCC|AAGCTT). It is never guessed from the pattern. A regular expression takes letters, [AG], [^P], ., {m}, {m,n}, {m,}, ?, + (up to 1,000), * (up to 1,000), up to 8 choices and ^ and $; backreferences, lookarounds and repeats on a group are refused. The search record keeps the expression and its PROSITE translation.
  • strands: string. Which strands an exact or pattern search reads.
  • k: integer, 0 to 5. Within k changes only: the most changes a hit may have, below each query's length.
  • changes: one of substitutions, edits. Within k changes only: substitutions counts letters changed in place; edits also counts letters inserted or deleted. An N, an X or another IUPAC code in a query, or a code in a stored protein, matches any letter it stands for, so it is never a change. Stored DNA is read letter for letter: a stored N or other code matches only the same code.
  • title: string. A name for the combined search, up to 500 characters. Each job is named after it, with its set.
  • followUp: FollowUpFrom.
  • confirmed: boolean. true runs a search this server would ask about first: one estimated to take longer than its time for asking, or one of a large set. Without it, such a search answers 409 with confirm and does not start.
  • targets, required: a list of 2 to 8 CombinedSearchTarget objects. Each set once. Where to search goes here, never beside targets.

Answers

  • 202: The combined search, with one job for each target, in order. Ask GET /api/groups/{id} until finished is true.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

The account's combined searches, newest first

GET /api/groups listGroups

Parameters

  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.

Answers

  • 200: One page of combined searches.
  • Errors: 400, 401, 403, 404, as under Errors above.

Each target's job, and the time left

GET /api/groups/{id} getGroup

Parameters

  • id, in the path, required: string.

Answers

  • 200: The combined search.
  • Errors: 400, 401, 403, 404, as under Errors above.

Cancel the jobs still waiting or running

DELETE /api/groups/{id} cancelGroup

Finished jobs stay, with their results.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The combined search after the cancel.
  • Errors: 400, 401, 403, 404, as under Errors above.

One page of what the sets found, joined

GET /api/groups/{id}/references getGroupReferences

The publications and database entries the completed jobs found, each once: a publication by its ID, whichever sets found it, and an entry by its accession, with or without its version. A row keeps the best Query Match and identity across the sets, the earliest date, the sets and queries that found it, its best match and its first matches, each naming its job and hit row. The hit filters, sort, order, publishedFrom, publishedBefore, office, group, later and excluded work as on the Patents list, and office keeps publications alone. set and kind choose among the rows. group=family forms families over the joined publications, so one family can hold publications that different sets found; entries stay rows of their own. A job still waiting or running adds nothing until it completes, and a failed one adds nothing; members says which jobs the list holds.

Parameters

  • id, in the path, required: string.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.
  • sort, in the query: one of bestQueryMatch, bestIdentity, published, sequencesHit, hits.
  • order, in the query: one of asc, desc.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • group, in the query: one of family, publication, default "publication". family gives one row per patent family. Absent, one row per publication.
  • later, in the query: one of hide, show, default "show". hide folds the publications from on or after publishedBefore and adds later to the answer. Absent, they show.
  • set, in the query: a list of strings. Only references this set found, named as members[].set names it. Give it again for more sets.
  • kind, in the query: one of patent, entry. patent keeps publications only, and entry database entries only.

Answers

  • 200: The references after filters and marks.
  • Errors: 400, 401, 403, 404, as under Errors above.

The references as CSV, or in an export format

GET /api/groups/{id}/references.csv exportGroupReferences

One line per reference, every one the filters keep, later and excluded ones too, whatever group, later and the page say. Beside the patents CSV's columns it has reference (patent or entry), id, accession, source, sets (the sets' names, joined by semicolons), queries, best_set, best_query, best_job and best_row.

Parameters

  • id, in the path, required: string.
  • sort, in the query: one of bestQueryMatch, bestIdentity, published, sequencesHit, hits.
  • order, in the query: one of asc, desc.
  • strand, in the query: one of plus, minus.
  • text, in the query: string, up to 200 characters. Text to find in a hit, up to 200 characters.
  • identity, in the query: number, 0 to 100. The lowest identity, in percent.
  • coverage, in the query: number, 0 to 100. The lowest query coverage, in percent.
  • query, in the query: integer, 1 to 20. One query, by its number.
  • publishedFrom, in the query: string, date. Only hits none of whose sequence's dates falls before this date: its first published date (firstPublishedBy where a row has it) and the earliest filing or priority date of its US and WO publications. A date known only to the month or year counts as its last day. With publishedBefore, the hits from this date up to that one. Hits with no date stay.
  • publishedBefore, in the query: string, date. Only hits first published before this date, and hits whose sequence has a US or WO publication filed or claiming priority before it (such a hit row has filedBefore: true). Hits with no date stay.
  • office, in the query: string. Only patents of this office, such as US or EP.
  • drugs, in the query: one of only. only keeps the hits that name a drug: those whose sequence is the same as a drug's chain, on a search the drug names add-on wrote into.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • set, in the query: a list of strings. Only references this set found, named as members[].set names it. Give it again for more sets.
  • kind, in the query: one of patent, entry. patent keeps publications only, and entry database entries only.
  • format, in the query: string, default "Built-in". The export format, by its name: Built-in, the CSV this export always gives, as when absent, or a format this server's export formats file defines for this export, as GET /api/status lists them under exports.formats. An external format leaves out every row a confidential set found. 400 for a name that serves no format of this export.

Answers

  • 200: Every reference that passes the filters. The combined search's exports list notes the export. As text/csv or text/tab-separated-values or application/x-ndjson.
  • Errors: 400, 401, 403, 404, as under Errors above.

Keep, exclude or clear references in every set that holds them

POST /api/groups/{id}/marks markGroupReferences

Give id for one reference, or ids for up to 500, such as a family row's family.ids. Each is marked in every completed job that holds it: a publication with the job's own publication mark, and a database entry by marking the job's hit rows that found it, so the mark shows in that job's own patents list and hits. Entries of one stored sequence share its rows, so they share a mark. Every ID is found before anything is written; an unknown one answers 404.

Parameters

  • id, in the path, required: string.

Body

JSON (ReferenceMarkRequest). Give id or ids, not both.

  • id: string. One reference ID, as the list gives it.
  • ids: a list of 1 to 500 strings. Up to 500 reference IDs, such as a family row's family.ids. Each gets its own mark.
  • action, required: one of keep, exclude, clear.
  • reason: string. Why, up to 500 characters.

Answers

  • 201: One mark for each reference, with the jobs it went to.
  • Errors: 400, 401, 403, 404, 415, as under Errors above.

Run every target again, or only some

POST /api/groups/{id}/again runGroupAgain

With an empty object, runs every target again as a new combined search, with the same request. With only, runs those targets again as new jobs of this combined search; the jobs they replace stay on the server, with their marks, and are listed under earlier. A target still waiting or running answers 409. The queue takes every new job or none, as when the combined search was made.

Parameters

  • id, in the path, required: string.

Body

JSON.

  • only: a list of 1 to 8 integers, each 0 or more. The targets to run again, by index, counting from 0.
  • confirmed: boolean. true runs a search this server would ask about first: one estimated to take longer than its time for asking, or one of a large set. Without it, such a search answers 409 with confirm and does not start.

Answers

  • 202: The new combined search, or with only this one.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

The searches a finished combined search suggests running next

GET /api/groups/{id}/follow-ups getGroupFollowUps

Fixed rules read the finished search and suggest the next searches, each with its rule, its reason from the result and the search it would run. No model takes part, so the same result gives the same suggestions. The rules, in order: few hits or none at the identity asked (a more sensitive method on the same sets, or a set not yet searched), the hit limit reached (more hits, or a narrower identity or coverage), part of the query unmatched (that part as a fragment), the other molecule type (a translated search) and an antibody chain (its CDRs). The first 3 not dismissed are listed, each recorded the first time it is. fill gives what the search form takes to run one. A search run from a case's plan lists none here: caseId names its case, which lists them (GET /api/cases/{id}/follow-ups). The rules read the sets' jobs together, once every one has ended: the hits they found added up, and the best match of any.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The suggestions, the search this one follows and the record.
  • Errors: 400, 401, 403, 404, as under Errors above.

Dismiss a suggested search, or record that its filter went on the list

POST /api/groups/{id}/follow-ups answerGroupFollowUp

dismiss hides a suggestion, and the next one that applies takes its place. apply records that a narrower identity or coverage, which only the hit limit rule suggests, went on the list as filters. To run a suggestion, start its search with followUp naming this search (POST /api/jobs, POST /api/groups or POST /api/antibody/searches): the record of each search then names the other. 404 for a suggestion this search did not show; 409 for a search run from a case's plan.

Parameters

  • id, in the path, required: string.

Body

JSON (FollowUpAction).

  • action, required: one of dismiss, apply.
  • key, required: string. The suggestion, as listed.

Answers

  • 200: The suggestions and the record after the change.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Tokens

API tokens for programs.

The account's API tokens

GET /api/tokens listTokens

Answers

  • 200: The tokens, never their secrets, with the longest a new one may last.
  • Errors: 400, 401, 403, 404, as under Errors above.

Make an API token (browser sign-in only)

POST /api/tokens createToken

A request signed in with a token gets 403: make tokens on the API tokens page. The answer holds the token once; the server keeps only its SHA-256 hash.

Body

JSON.

  • name, required: string. 1 to 100 characters, such as the program that will use it.
  • days: integer, 1 to 90. How long it lasts. The default and the most is the server's setting.

Answers

  • 201: The token record and the token itself.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Revoke one of the account's tokens

DELETE /api/tokens/{id} revokeToken

Parameters

  • id, in the path, required: string.

Answers

  • 200: The token, revoked.
  • Errors: 400, 401, 403, 404, as under Errors above.

Listings

WIPO ST.26 sequence listings.

The account's sequence listings

GET /api/listings listListings

Parameters

  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.

Answers

  • 200: One page of listings.
  • Errors: 400, 401, 403, 404, as under Errors above.

Upload a WIPO ST.26 sequence listing

POST /api/listings uploadListing

The import job reads the file once. A WIPO ST.26 XML file is checked against the standard as it is read: the listing keeps the verdict and the counts as st26 (checker, standard, verdict, errors, warnings, sequences, skipped, sequencesWithErrors, errorsOutsideSequences, stoppedAt and summary), never the problems themselves. A listing in another format, or one imported before the check, has no st26.

Parameters

  • name, in the query, required: string. The file name.

Body

The listing file: XML, or gzip.

The file itself, as application/xml or text/xml or application/gzip or application/octet-stream.

Answers

  • 202: The listing and its import job.
  • Errors: 400, 401, 403, 404, 413, 415, 429, 503, as under Errors above.

One listing

GET /api/listings/{id} getListing

Parameters

  • id, in the path, required: string.

Answers

  • 200: The listing.
  • Errors: 400, 401, 403, 404, as under Errors above.

Delete a listing

DELETE /api/listings/{id} deleteListing

Parameters

  • id, in the path, required: string.

Answers

  • 200: What was removed.
  • Errors: 400, 401, 403, 404, as under Errors above.

A listing's sequences

GET /api/listings/{id}/sequences listListingSequences

Parameters

  • id, in the path, required: string.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.

Answers

  • 200: One page of sequences.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

One sequence of a listing, by SEQ ID NO

GET /api/listings/{id}/sequences/{n} getListingSequence

Parameters

  • id, in the path, required: string.
  • n, in the path, required: string.

Answers

  • 200: The sequence.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Search a listing's sequences

POST /api/listings/{id}/searches searchListing

On a server with compute limits, searches that together are estimated to take longer than its time for asking, or that read a large set, answer 409 with confirm and none starts: send the request again with "confirmed": true.

Parameters

  • id, in the path, required: string.

Body

JSON. Which sequences, and the search settings, as on the page.

  • confirmed: boolean. true runs a search this server would ask about first: one estimated to take longer than its time for asking, or one of a large set. Without it, such a search answers 409 with confirm and does not start.

Answers

  • 202: The searches started.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

Query tools

Variants, windows, DNA patterns, modified residues and searches proposed from a claim phrase, and the query groups they save.

Variants from changes written as K26R

POST /api/query-tools/variants makeVariants

base is a sequence ({ sequence, type, name }), a saved fragment ({ fragmentId }) or a listing sequence ({ listingId, seqIdNo }). changes holds one variant to a line: K26R, Lys26Arg, K26R/Q (one variant each), A8Aib (a modified residue), 20-30A (a scan), des-B30, del1-3, M1_K3del, 20insR or K20_L21insR, with the changes on a line joined by spaces. first numbers the first residue (1 unless the sequence starts at another, as GLP-1(7-37) starts at 7). modified says how a modified residue is searched: parent, x or both, which makes two variants. Each line gets what it was read as, or a problem. With "save": true each variant is saved as a fragment whose edit step is its changes, after the base when it is not a fragment yet.

Body

JSON. The base sequence and the changes.

  • base, required: object. A sequence, a fragment or a listing sequence.
  • changes, required: string. One variant to a line.
  • first: integer.
  • modified: one of parent, x, both.
  • save: boolean.

Answers

  • 200: The variants, what each line was read as, the problems, and with save the fragments.
  • Errors: 400, 401, 403, 404, 413, 415, as under Errors above.

Searches for a claim phrase

POST /api/query-tools/proposals proposeSearches

Reads phrase with the claim rules a case uses, so a case and this route read it the same way, and drafts its searches as a case drafts its plan. listingId gives the SEQ ID NOs the phrase names their letters; base stands for the first one the listing does not hold, or for the sequence a phrase that names none speaks of. Each search gives its queries, method (engine), results filter, settings and the reasons for each, in words. At least 90% identical proposes Global on the query (glsearch36) with Minimum identity at 90 where FASTA36 runs, and the automatic choice elsewhere; at least 15 consecutive amino acids proposes every window of 15 letters as Exact text; up to 3 substitutions proposes Within k changes where the server offers it; X at position 26 is K or R proposes a Pattern search with [KR] at that position, with the sequences the choices make as queries. Nothing is searched: start a proposed search with POST /api/jobs, or save it as a query group.

Body

JSON. The phrase and where its sequences come from.

  • phrase, required: string. A claim, or part of one.
  • listingId: string. A listing that holds the SEQ ID NOs.
  • base: object. A sequence, a fragment or a listing sequence.
  • first: integer. The number of the base sequence's first residue, 1 unless given. A position in the phrase counts from it.

Answers

  • 200: What the phrase was read as, notes, and the proposed searches.
  • Errors: 400, 401, 403, 404, 413, 415, as under Errors above.

Windows of a sequence

POST /api/query-tools/windows cutWindows

Give one way to cut: length with step (every window of that length, and one more ending at the last letter), lengths { min, max } with step (each length, such as peptides of 8 to 15), around (positions) with flank (letters on each side), ranges ([{ name, from, to }]), or cdrs ({ scheme: kabat, chothia or imgt }) for the CDRs of an antibody chain where antibody numbering runs (409 where it does not). from and to keep the windows inside a stretch. Positions count from first. Up to 2,000 windows. searches says how the windows run: up to 20 queries and 100,000 letters in each search.

Body

JSON. The base sequence and how to cut it.

  • base, required: object. A sequence, a fragment or a listing sequence.
  • length: integer, 1 or more.
  • step: integer, 1 or more.
  • lengths: object. min and max.
  • around: a list of integers.
  • flank: integer, 0 or more.
  • ranges: a list of objects.
  • cdrs: object. scheme.

Answers

  • 200: The windows and the searches they make.
  • Errors: 400, 401, 403, 404, 409, 413, 415, as under Errors above.

A peptide as a DNA pattern

POST /api/query-tools/dna-pattern peptidePattern

A peptide of 4 to 200 amino acids as DNA with an IUPAC code for each codon, in genetic code geneticCode (1, the standard code, unless another NCBI table is named): K is AAR. pattern is the PROSITE pattern of those triplets, allowed says how many DNA sequences it allows and coding how many of them code for the peptide. Where one triplet allows more codons than the residue has, as YTN for L, exact gives a regular expression with a choice for each such residue (L is CTN or TTR) when it makes at most 8 choices. Search either with method Pattern on a DNA set, which reads both strands.

Body

JSON. The peptide.

  • peptide, required: string. One-letter amino acid codes.
  • geneticCode: integer, 1 to 33.

Answers

  • 200: The pattern, its counts and notes.
  • Errors: 400, 401, 403, 404, 415, as under Errors above.

A peptide with modified residues as queries

POST /api/query-tools/modified modifiedResidues

text is HELM (PEPTIDE1{H.[Aib].E.G}$$$$), one-letter codes with modified residues in square brackets (H[Aib]EG) or a side chain after a letter (K(palmitoyl-ฮณE)), or residues joined by hyphens (H-His-Aib-Glu-NH2). notes takes a listing's MOD_RES or MISC_FEATURE notes with one-letter text. Each modified residue gets its parent residue where its name gives one (Aib is alanine with a second methyl group, D-Ala is alanine, acylated lysine is K), or none. choice makes the queries: parent, x or both, which makes two queries. Each query's name says the choice, so the search record keeps it.

Body

JSON. The peptide and the choice.

  • text, required: string. HELM, bracketed or hyphenated residues.
  • notes: string. A listing's notes.
  • choice: one of parent, x, both.
  • name: string. The name the queries start with.

Answers

  • 200: The residues read and the queries.
  • Errors: 400, 401, 403, 404, 415, as under Errors above.

The account's query groups, newest first

GET /api/query-groups listQueryGroups

Parameters

  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.

Answers

  • 200: One page of query groups, without their letters.
  • Errors: 400, 401, 403, 404, as under Errors above.

Save queries as a query group

POST /api/query-groups createQueryGroup

A query group holds 1 to 2,000 queries of one type, up to 2,000,000 letters in all, each up to 20,000 letters. tool names what made it (variants, phrase for a claim phrase, windows, dna-pattern, modified or entered), read keeps what the tool read, and proposed the method, results filter and reasons of the proposed search it was saved from.

Body

JSON. The group.

  • name: string. Up to 200 characters.
  • type, required: one of nucl, prot.
  • queries, required: a list of objects.
  • tool: string. What made it.
  • read: a list of strings.
  • proposed: object. method, filters and why.

Answers

  • 201: The saved group.
  • Errors: 400, 401, 403, 404, 413, 415, as under Errors above.

One query group, with its queries and searches

GET /api/query-groups/{id} getQueryGroup

Parameters

  • id, in the path, required: string.

Answers

  • 200: The query group.
  • Errors: 400, 401, 403, 404, as under Errors above.

Delete a query group

DELETE /api/query-groups/{id} deleteQueryGroup

Its searches and their results stay.

Parameters

  • id, in the path, required: string.

Answers

  • 200: What was removed.
  • Errors: 400, 401, 403, 404, as under Errors above.

Search a query group's queries

POST /api/query-groups/{id}/searches searchQueryGroup

Takes the body of POST /api/jobs without fasta: the set and the method (engine) to search with, the method of the proposed search it was saved from unless another is named. The queries run in order, up to 20 and 100,000 letters in each search, as one batch (POST /api/batches): every search is checked before any starts, and the batch's limits apply. The group records the batch and which queries each search holds.

Parameters

  • id, in the path, required: string.

Body

JSON. The search settings, as for POST /api/jobs.

  • confirmed: boolean. true runs a search this server would ask about first: one estimated to take longer than its time for asking, or one of a large set. Without it, such a search answers 409 with confirm and does not start.

Answers

  • 202: The batch and the searches it holds.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

Antibodies

Antibody regions.

Number an antibody chain's regions

POST /api/antibody/number numberAntibody

Body

JSON.

  • sequence, required: string. One chain as letters, or up to 10 as FASTA.

Answers

  • 200: Each chain's domains, regions and numbering.
  • Errors: 400, 401, 403, 404, 413, 415, 429, 503, as under Errors above.

Search antibody regions

POST /api/antibody/searches searchAntibody

An antibody search has no estimate, so on a server with compute limits only a search of a large set answers 409 with confirm and does not start: send it again with "confirmed": true.

Body

JSON. A chain (sequence) or typed CDRs (cdrs), with the snapshot and settings.

  • sequence: string. A chain.
  • cdrs: a list of objects.
  • snapshotId: string. The snapshot.
  • set: string. The set.
  • followUp: FollowUpFrom.
  • confirmed: boolean. true runs a search this server would ask about first: one estimated to take longer than its time for asking, or one of a large set. Without it, such a search answers 409 with confirm and does not start.

Answers

  • 202: The antibody search.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

The groups of an antibody search

GET /api/jobs/{id}/antibody getAntibodyGroups

On a server with an antibody name table, each group's names lists the therapeutic antibodies whose variable domain or chain CDRs its stored sequence holds, from ChEMBL, and the answer's names gives ChEMBL's release, credit and license (CC BY-SA 3.0), or unread when the snapshot cannot be read.

Parameters

  • id, in the path, required: string.
  • by, in the query: one of sequence, publication.
  • identity, in the query: integer, 50 to 100.
  • complete, in the query: boolean.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500.

Answers

  • 200: The groups.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The groups as CSV

GET /api/jobs/{id}/antibody.csv exportAntibodyGroups

Parameters

  • id, in the path, required: string.

Answers

  • 200: A column for each CDR, then named_antibodies on a server with an antibody name table. As text/csv.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Watches

Searches and applicants followed through each weekly addition.

The account's watches

GET /api/watches listWatches

Answers

  • 200: The watches, newest first, each with its last run.
  • Errors: 400, 401, 403, 404, as under Errors above.

Watch a finished snapshot search, or an applicant

POST /api/watches createWatch

Give jobId to watch a search: each weekly addition runs it again and lists the matches it has not found before. Or give applicant to watch an applicant: each weekly addition lists the publications it adds whose applicant is that name or a name the account has joined to it. Give one of the two.

Body

JSON.

  • jobId: string. A finished snapshot search of the account.
  • newFrom: string, date. With jobId: count the matches dated on or after this day as new. The watch lists them at once, from the search it starts from, as its first run, which sends no email. The other matches, and those with no date, count as seen. A patent record is dated by its publication, and a database entry by its own date.
  • applicant: string. An applicant's name as its publications give it, up to 300 characters. Case, accents, punctuation and legal endings such as Inc do not matter.
  • snapshotId: string. With applicant: the snapshot to follow. The newest snapshot with patent sets when left out.
  • title: string. Up to 200 characters. A watch on an applicant takes its name when left out.

Answers

  • 201: The watch.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

One watch and its runs

GET /api/watches/{id} getWatch

Parameters

  • id, in the path, required: string.

Answers

  • 200: The watch.
  • Errors: 400, 401, 403, 404, as under Errors above.

Rename a watch

PATCH /api/watches/{id} renameWatch

Parameters

  • id, in the path, required: string.

Body

JSON.

  • title, required: string. Up to 200 characters.

Answers

  • 200: The watch.
  • Errors: 400, 401, 403, 404, 415, as under Errors above.

Delete a watch; its searches stay

DELETE /api/watches/{id} deleteWatch

Parameters

  • id, in the path, required: string.

Answers

  • 200: The removal.
  • Errors: 400, 401, 403, 404, as under Errors above.

Pause a watch

POST /api/watches/{id}/pause pauseWatch

A watch that is paused already stays as it is, with the reason it was paused for.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The watch.
  • Errors: 400, 401, 403, 404, as under Errors above.

Resume a watch

POST /api/watches/{id}/resume resumeWatch

A watch paused for its size (pausedBy size) answers 409 with the code not-allowed-in-state, since it would pause again at the next weekly addition: delete it, then watch a narrower search.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The watch.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Applicants

One applicant's publications with their sequences.

Export one applicant's publications with their sequences

POST /api/portfolios exportPortfolio

Starts a job of kind portfolio. It reads the patent sets of the snapshot and all its weekly additions for the publications whose applicant is the name given or a name the account has joined to it, and writes their sequences as CSV and FASTA: the oldest publications first, then by SEQ ID number, up to 100,000 sequences and 100 million letters. The finished job says how many it holds (exported) of how many there are (sequences), and limited is true when the export stopped at a limit.

Body

JSON.

  • applicant, required: string. An applicant's name as its publications give it, up to 300 characters.
  • snapshotId: string. The snapshot to read. The newest snapshot with patent sets when left out.

Answers

  • 202: The export job, queued.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

A finished export as CSV

GET /api/jobs/{id}/portfolio.csv downloadPortfolioCsv

Parameters

  • id, in the path, required: string.

Answers

  • 200: One row for each sequence: publication, published, applicant, seq_id_no, accession, molecule_type, length, sequence. As text/csv.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

A finished export as FASTA

GET /api/jobs/{id}/portfolio.fasta downloadPortfolioFasta

Parameters

  • id, in the path, required: string.

Answers

  • 200: One entry for each sequence, named by publication and SEQ ID number, such as >US11236170-B2/10947. As text/x-fasta.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Cases

Cases: claims, the search plan, searches, notes and reports.

One case

GET /api/cases/{id} getCase

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Change the name, listing, snapshot, application number or prior art date

PATCH /api/cases/{id} changeCase

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • title: string. Up to 200 characters.
  • listingId: string or null.
  • snapshotId: string or null.
  • applicationNumber: string or null. Up to 40 characters, such as US 17/123,456. Null clears it.
  • priorArtDate: string or null. YYYY-MM-DD. New plan searches look for what was published before it. Null clears it.
  • priorArtDateBasis: one of filing, priority, other. What the date is: the filing date, the earliest priority date, or another date (the default). Sent with priorArtDate.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Delete a demo case (its owner)

DELETE /api/cases/{id} deleteDemoCase

Deletes a demo case as DELETE /api/admin/cases/{id} deletes a case, but for the searches added to it by hand, which stay with the account. A demo case was started with demo: true and holds the demo files alone: every set of its claims was read from a demo claims file, every listing it names was imported from a demo listing, and every result file it imported is a demo result file. Its GET answers demo: true. The audit log's case.deleted event adds by: owner and demo: true. 409 for any other case, which only an admin deletes, and in the cases where the admin's delete answers 409.

Parameters

  • id, in the path, required: string.

Answers

  • 200: What was deleted, as the admin's delete answers it.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The claims

GET /api/cases/{id}/claims getClaims

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Add a set of claims: pasted text, a publication's XML, or a Word or text file

POST /api/cases/{id}/claims importClaims

Each import is a new set of claims; the case keeps every set. The answer names the set (n, label, date, current). When the set becomes current, the rules find features again, and a feature on a claim whose words did not change keeps its ID, decision, note and edit; changes counts the claims unchanged, amended, added and cancelled, and carried what came over. A locked plan stays locked and follows the older set until it is unlocked, with a reason, and drafted again. A set dated before the current one stays beside it, and current names the set that stays current. A second import of the same claims with the same label and date answers 409.

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • text: string. The claims.
  • xml: string. One publication's full-text XML, an application or a grant. Its description comes with it.
  • file: object.
  • label: one of filed, amended, published, granted. What the claims are. A publication's XML gives published or granted by its kind code when left out. Claims as amended need a date.
  • date: string. The date of the claims, YYYY-MM-DD. A publication's XML gives its publication date, or its filing date for claims as filed, when left out.
  • current: boolean. Whether the set becomes the current claims. Left out, it does, unless it is dated before the current set. A case's first set is always current.

Answers

  • 201: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The sets of claims, oldest first, each without its claims, and which is current

GET /api/cases/{id}/claims/sets listClaimSets

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

One set of claims, with its claims

GET /api/cases/{id}/claims/sets/{n} getClaimSet

Parameters

  • id, in the path, required: string.
  • n, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Make a set the current claims

POST /api/cases/{id}/claims/sets/{n}/current makeClaimSetCurrent

Finds features and carries them over as an import does, and logs a claims.current event with the note. A locked plan stays locked and follows the set it was drafted for.

Parameters

  • id, in the path, required: string.
  • n, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • note: string. Why, up to 500 characters.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

What changed from one set of claims to another, claim by claim

GET /api/cases/{id}/claims/changes compareClaimSets

Each claim is unchanged, amended (with the words added and removed), added or cancelled, with its number in each set. Claims that were renumbered but read the same, with their references to other claims renumbered, are unchanged.

Parameters

  • id, in the path, required: string.
  • from, in the query: integer, 1 or more. The older set. The set before to when left out.
  • to, in the query: integer, 1 or more. The newer set. The current set when left out.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

The claim features

GET /api/cases/{id}/features getFeatures

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Add a feature by hand

POST /api/cases/{id}/features addFeature

Takes claim, kind (seqId, identity, fragment, complement, fusion, cdr, region, sequence, changes, wildcard, choice), start, end, links and the kind's details in the field the service README names. changes is { max, values, kinds, conservative, unit }: the most changes the claim allows (1 to 10,000), the counts it writes, kinds from addition, deletion, substitution (a match meets it only through these), whether only conservative substitutions (not checked: every substitution counts), and amino acids, nucleotides or null. wildcard is { letters, type }: the capital letters the claim reads as any residue (Xaa reads as X), and nucl or prot. choice is { at, numbers, letters, named, absent }: what the numbers count (position, a position of the sequence; x, the claim's numbered X; or each, every X, with no numbers), the one-letter codes of the amino acids the claim allows there, other residues by name (such as Aib), and whether the position may be empty.

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

Answers

  • 201: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Accept or reject features

POST /api/cases/{id}/features/review reviewFeatures

features answers each feature as it stands after the review. A feature already accepted, or already rejected with no note or the same note, stays as it is and nothing is logged for it. A feature accepted after a rejection drops the rejection's note, which the case log keeps; a model suggestion gets the model's own note back.

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • accept: a list of strings.
  • reject: a list of strings.
  • note: string. Why.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Accept, reject or change one feature

POST /api/cases/{id}/features/{featureId} reviewFeature

A change takes start, end, links and the details of the feature's kind, checked as for adding one: changes for allowed changes, wildcard for letters the claim reads as any residue, choice for residues allowed at a position. An edit is always logged. Accepting an accepted feature, or rejecting a rejected one with no note or the same note, changes nothing and logs nothing.

Parameters

  • id, in the path, required: string.
  • featureId, in the path, required: string.

Body

JSON. The change, as the page sends it.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The state of the case's last call to the claims model

GET /api/cases/{id}/suggestions getSuggestionsState

state is none, asking (with seconds so far), done (with suggested, dropped and paragraphs), failed or interrupted (with error); busy is true while the model answers for another case.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Ask the claims model for features the rules missed

POST /api/cases/{id}/suggestions suggestFeatures

The model gets the claims, the features found and, for claims from publication XML, up to 40 description paragraphs. A server makes one call at a time; while one runs, another answers 409. Without background, a call that fails answers 502 with the reason.

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • background: boolean. True starts the call and answers 202 with its state at once; GET /api/cases/{id}/suggestions reads it until it ends. Left out, the request waits for the model and answers with suggestions, dropped and paragraphs; a proxy that stops waiting first ends the request, not the call, and the GET reads how it ended.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The case's sequences

GET /api/cases/{id}/sequences getCaseSequences

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

The search plan

GET /api/cases/{id}/plan getPlan

coverage.uncovered lists the features no search covers. Where the listing's letters that stand for more than one residue, such as X for any amino acid, lower the identity a search for one would keep, or a count of changes the claim allows sets it, its entry has filter: { identity, words }, as a draft gives it.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Edit the search plan

PUT /api/cases/{id}/plan editPlan

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Draft the plan from the features

POST /api/cases/{id}/plan/draft draftPlan

Each SEQ ID NO is searched once, at the lowest identity any claim gives it. A search's identity counts a letter that stands for more than one residue, such as X for any amino acid, as a difference, while the case's references read it as each residue it stands for. So where the listing gives a SEQ ID NO such letters, its search keeps less identity, by what those letters take away, and its reason says why. A count of changes a claim allows is an alternative too: N changes leave at least 100(L - N - W)/L identity over the alignment of L letters, W of them such letters, and the search keeps the lowest filter of its claims' alternatives. A count of changes on a SEQ ID NO of unknown length sets no filter.

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Lock the plan

POST /api/cases/{id}/plan/lock lockPlan

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Unlock the plan

POST /api/cases/{id}/plan/unlock unlockPlan

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • reason: string. Why, up to 500 characters. Needed while the plan follows an older set of claims than the current one.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

One locked version of the plan

GET /api/cases/{id}/plan/versions/{n} getPlanVersion

A lock writes the version and then the plan, so a version numbered above the plan's own version is what a stop left part-way through a lock and is not a version: it answers 404 here, a run or a search request that names it answers 404, the plan and the decisions export leave it out, and the next lock writes over it.

Parameters

  • id, in the path, required: string.
  • n, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Move SEQ ID NOs to another query group, split a group or join two

POST /api/cases/{id}/plan/groups changePlanGroups

The plan's query groups are its searches of SEQ ID NOs that share a query, an engine and thresholds, one search on each set; GET /api/cases/{id}/plan lists them in groups, with the plan's size against the server's limits and the runs it makes in size. A move or a join puts together groups on the same sets with the same E-value, hit count and date, and a join also needs the same engine; the group that takes SEQ ID NOs keeps the lower identity and coverage of the two. A split makes a new search beside each search of the group, under the next free numbers. The changed searches get new reasons, and the case log gets a plan.edited event with the change in group. Answers with the plan; 400 when the change does not fit, 409 when the plan is locked.

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • action: one of move, split, join.
  • from: string. For a move: a search of the group the SEQ ID NOs leave, such as P1.
  • to: string. For a move: a search of the group they join.
  • group: string. For a split: a search of the group to split. For a join: a search of the group that stays.
  • with: string. For a join: a search of the group that joins it.
  • seqIds: a list of integers, each 1 or more. For a move or a split: the SEQ ID NOs, each once.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Where plan searches can run: each set and attached database, with the searches and time a set offered on request adds

GET /api/cases/{id}/plan/targets listPlanTargets

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Add a copy of each fitting search on a set offered on request, or on an attached database

POST /api/cases/{id}/plan/targets addPlanTarget

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • snapshotId: string. The snapshot.
  • set: string. The set, such as trembl.
  • databaseId: string. An attached database, in place of snapshotId and set.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The plan runs, each with its progress and the searches it has not started yet

GET /api/cases/{id}/runs listRuns

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Run the plan, in several runs when it needs more jobs than the queue has room for

POST /api/cases/{id}/runs runPlan

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

Answers

  • 202: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, 429, as under Errors above.

Run one search of a run again

POST /api/cases/{id}/runs/{runId}/again runSearchAgain

Parameters

  • id, in the path, required: string.
  • runId, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • jobId: string. A failed, cancelled or interrupted job of the run.
  • unit: integer, 0 or more. A search of the run that could not start, in place of jobId.

Answers

  • 202: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, 429, as under Errors above.

One plan run, with its progress and the searches it has not started yet

GET /api/cases/{id}/runs/{runId} getRun

The run as GET /api/cases/{id}/runs lists it. progress counts total, done, failed (every job that ended without completing), cancelled and interrupted (those of the failed that were cancelled or cut off by a stop of the service), running, queued and pending. A cancelled run has cancelled: { at, user, dropped, runs }.

Parameters

  • id, in the path, required: string.
  • runId, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Cancel a plan run

POST /api/cases/{id}/runs/{runId}/cancel cancelRun

Drops the searches of the run that have not started, and the runs still to start after it when the plan was cut into runs, and cancels its searches that wait or run. Searches that finished keep their results, and each cancelled search can run again. Answers the run, whose cancelled names who cancelled it and when, and dropped and runs count what went; its progress counts the dropped searches as cancelled. Logs plan.cancelled with the jobs it stopped and the counts. A run that has ended answers 200 as it stands, with no event.

Parameters

  • id, in the path, required: string.
  • runId, in the path, required: string.

Body

JSON. The change, as the page sends it.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 415, as under Errors above.

The case's searches

GET /api/cases/{id}/searches listCaseSearches

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

POST /api/cases/{id}/searches addCaseSearch

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • jobId: string. A finished search of the account.

Answers

  • 201: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

POST /api/cases/{id}/searches/remove removeCaseSearch

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • jobId: string. The search.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The notes

GET /api/cases/{id}/notes listNotes

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Add a note

POST /api/cases/{id}/notes addNote

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • text: string. Up to 5,000 characters.

Answers

  • 201: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Withdraw a note

POST /api/cases/{id}/notes/{n}/withdraw withdrawNote

Parameters

  • id, in the path, required: string.
  • n, in the path, required: string.

Body

JSON. The change, as the page sends it.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The drafted sentences on why each reference counts, with their decisions

GET /api/cases/{id}/explanations listExplanations

Each sentence has n, kind, text, source, fingerprint (the SHA-256 of its text, which a decision sends back as ifFingerprint) and decision.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Accept, edit or reject a drafted sentence

POST /api/cases/{id}/explanations decideExplanation

The service drafts the sentence again from the facts as they are now and records the decision against that draft. Send ifFingerprint so that a decision never stands for words you did not read.

Parameters

  • id, in the path, required: string.

Body

JSON. The change, as the page sends it.

  • search: string. A search in the case.
  • publication: string. A publication with a draft in that search.
  • sentence: integer, 1 to 4. The sentence: 1 alignment, 2 plan, 3 date, 4 paper.
  • action: one of accept, edit, reject.
  • text: string. Your words for the sentence, for an edit. Up to 2,000 characters.
  • ifFingerprint: string. The fingerprint of the sentence you read, as GET /api/cases/{id}/explanations gives it. When the sentence reads differently now, because its facts changed, the answer is 409 with code changed-elsewhere and nothing is decided: read it again. Left out, the decision binds to the sentence as it reads when the service answers.

Answers

  • 201: The answer.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The event log

GET /api/cases/{id}/events listCaseEvents

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Check the event log's hash chain

GET /api/cases/{id}/events/verify verifyCaseEvents

Parameters

  • id, in the path, required: string.

Answers

  • 200: The answer.
  • Errors: 400, 401, 403, 404, as under Errors above.

Keep or exclude a result in the case

POST /api/cases/{id}/marks markCaseResult

Marks a result of a search in the case, as POST /api/jobs/{id}/marks does, and logs one mark.keep, mark.exclude or mark.clear event. With ids the event names every publication in ids, and its id is the first of them.

Parameters

  • id, in the path, required: string.

Body

JSON.

  • jobId, required: string. A search in the case.
  • target, required: one of publication, row.
  • id: any value. The patent ID or the hit row number.
  • ids: a list of 1 to 500 strings. Up to 500 patent IDs, such as a family row's family.ids. Each gets its own mark. target must be publication.
  • action, required: one of keep, exclude, clear.
  • reason: string. Why, up to 500 characters.

Answers

  • 201: The mark, or with ids the marks.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The account's cases

GET /api/cases listCases

Answers

  • 200: The cases, newest first.
  • Errors: 400, 401, 403, 404, as under Errors above.

Open a case

POST /api/cases createCase

Body

JSON. The case.

  • title: string. Up to 200 characters.
  • listingId: string. A listing of the account.
  • snapshotId: string. The snapshot to search.
  • applicationNumber: string. Up to 40 characters.
  • priorArtDate: string. YYYY-MM-DD.
  • priorArtDateBasis: one of filing, priority, other.
  • demo: boolean. true for a case started with Use demo data. Such a case answers demo: whether it still holds the demo files alone (GET /demo/README.md lists them), in which case its owner may delete it.

Answers

  • 201: The case.
  • Errors: 400, 401, 403, 404, 415, as under Errors above.

Hand the case to a colleague's account

POST /api/cases/{id}/handover handOverCase

The case changes owner and keeps everything it holds: its claims and sets of claims, plan, searches and their results, imported result files, references, decisions, summaries, notes and log. Nothing is copied. The colleague opens each search and listing the case holds, through the case and on its own; the account that handed it over no longer opens the case or them, unless the case comes back. Its other searches stay its own. A search still counts for the account that ran it. to names the colleague as they sign in: by email on the hosted service and on a server whose sign-in names accounts by email, where it must be at your own email domain, and otherwise by the name the sign-in gives. The colleague must have signed in here at least once and be let in by the sign-in rule now. The case log gets a case.handed_over event with from and to, and the service's audit log one with the case, from and to. 400 for your own account or a name that cannot be an account; 403 for an account at another email domain or one the sign-in rule does not let in now; 404 for an account that has not signed in here, or a case that is not yours; 409 while the claims model reads the case or its listing imports, or when two accounts signed in with that name on the same day. The local workbench has no accounts and answers 404.

Parameters

  • id, in the path, required: string.

Body

JSON.

  • to, required: string, up to 254 characters. The colleague's account: the email address or name they sign in with.

Answers

  • 200: Who handed the case to whom, and when.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The references under each claim feature, ranked

GET /api/cases/{id}/references listCaseReferences

Every reference the case's searches found, under the claim feature whose search found it. A feature is a SEQ ID reference of a kept feature, with the qualifiers linked to it, or a sequence written out in a claim with no SEQ ID. A plan's search serves the features its plan item covers, and keeps the identity, coverage and date it was locked with; a search added by hand serves every feature that recites its query's SEQ ID NO when the case's listing ran it, and the group "other" otherwise. A reference is a publication, by its ID, or a database entry, by its accession, joined across the searches. Inside a feature, references rank by meets, coverage, dateClass, queryMatch, evalue: whether the best match meets the feature's identity threshold over the query's whole length (as written means identical; with a fragment length, over at least that many letters of the alignment; a query letter that stands for more than one residue, such as X for any amino acid or R for A or G as WIPO ST.26 defines them, matches each residue it covers, and so does a letter the claim reads as any residue; a count of changes the claim allows is met by a match with that many changes or fewer, or by the identity where the claim gives one too), the coverage of the claimed region, the date class against the case's prior art date (before, filedBefore, undated, later; none when the case has no date), then Query Match and E-value. Ties go to the earliest date, then the ID. Each reference keeps its keys and the marks each search gives it; one that every search that found it excluded leaves the list and is counted. Without feature, each feature lists its first 20 references (or limit); with feature, that feature alone pages with offset and limit. Reading the list writes nothing.

Parameters

  • id, in the path, required: string.
  • feature, in the query: string. One feature alone, by its ID, such as F2, or other. 404 for a feature the list does not hold.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500, default 20. References per feature, 20 unless asked.

Answers

  • 200: Each feature with its ranked references, and the case's searches.
  • Errors: 400, 401, 403, 404, as under Errors above.

Every reference of every feature as CSV, or in an export format

GET /api/cases/{id}/references.csv exportCaseReferences

One line per reference in each feature, excluded ones last in their feature with no rank. The columns: feature, claim, claim_words, threshold, rank, meets, coverage, date_class, query_match, evalue, reference, id, label, office, number, kind, accession, source, published, filed, priority, application_number, applicant, title, link, matched, meeting, of, claimed_seq_ids, reference_seq_nos, best_search, best_set, best_job, best_row, best_query, best_seq_id_no, query_identity, identity, bits, align_length, matches, searches, sets, mark, marks, meets_words, date_words, matched_words. The case log gets an export.made event that names the format and the file's SHA-256.

Parameters

  • id, in the path, required: string.
  • format, in the query: string, default "Built-in". The export format, by its name: Built-in, the CSV this export always gives, as when absent, or a format this server's export formats file defines for this export, as GET /api/status lists them under exports.formats. An external format leaves out every row a confidential set found. 400 for a name that serves no format of this export.

Answers

  • 200: Every reference of every feature. As text/csv or text/tab-separated-values or application/x-ndjson.
  • Errors: 400, 401, 403, 404, as under Errors above.

All references: each reference once across the case

GET /api/cases/{id}/references/all listCaseAllReferences

Each publication or database entry the case's searches and imported result files found, once, with every feature, search, set and imported file that found it. Under each feature that lists it, a row gives its rank there among the references not excluded there, whether its best match meets the feature's threshold, the best match with its rank keys, and the marks. A row also gives the reference's dates, its patent family among the case's publications, and one overall mark only when the marks under every feature agree. Rows sort by the best rank they reach under any feature, then by how many claim features they meet, most first, then the earliest publication date, then the ID. A reference excluded under every feature that lists it leaves the list and is counted; with excluded=true the list holds those alone, with no rank. Pages with offset and limit. Reading the list writes nothing.

Parameters

  • id, in the path, required: string.
  • excluded, in the query: boolean. true shows the rows marked excluded instead.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500, default 20. References per page, 20 unless asked.

Answers

  • 200: One page of the list, with the case's searches.
  • Errors: 400, 401, 403, 404, as under Errors above.

All references as CSV, or in an export format

GET /api/cases/{id}/references/all.csv exportCaseAllReferences

One line per reference, those excluded under every feature last with no rank. A column with a value for each feature names the feature first, as in "F2 1; F3 excluded". The columns: rank, best_rank, features_met, features, reference, id, label, office, number, kind, accession, source, published, filed, priority, application_number, applicant, title, link, date_class, family, family_size, family_basis, feature_ranks, feature_meets, feature_best, feature_marks, mark, searches, sets, files, date_words. The case log gets an export.made event that names the format and the file's SHA-256.

Parameters

  • id, in the path, required: string.
  • format, in the query: string, default "Built-in". The export format, by its name: Built-in, the CSV this export always gives, as when absent, or a format this server's export formats file defines for this export, as GET /api/status lists them under exports.formats. An external format leaves out every row a confidential set found. 400 for a name that serves no format of this export.

Answers

  • 200: Each reference once across the case. As text/csv or text/tab-separated-values or application/x-ndjson.
  • Errors: 400, 401, 403, 404, as under Errors above.

The searches the case suggests adding to its plan

GET /api/cases/{id}/follow-ups listCaseFollowUps

Fixed rules suggest searches from the case's facts, with no model. Each claim feature whose plan searches have run gets them from its references, in this order: no reference meets the claim (a more sensitive method on the sets its searches read), the best references cover under 80% of the claimed sequence (the rest as a region), and a set the server holds for the feature's type that no search of it read. With job, one plan search's suggestions, by the rules a search outside a case follows, less the translated and CDR searches a plan does not hold; in a case with a prior art date, a search at its hit limit gets that date as its narrower search. The first 3 not dismissed are listed. A later version's run of the same plan search keeps what became of its suggestions: one added on an earlier run is listed as added, and one dismissed is left out. The case log gets a followup.shown event for each one the first time it is listed, with its rule, so reading this route writes to the log.

Parameters

  • id, in the path, required: string.
  • job, in the query: string. One of the case's plan searches, by its job: that search's suggestions in place of the features'.

Answers

  • 200: Each feature with suggestions, or with job that search's.
  • Errors: 400, 401, 403, 404, as under Errors above.

Add a suggested search to the plan, or dismiss it

POST /api/cases/{id}/follow-ups answerCaseFollowUp

add puts the suggestion's searches in the draft plan, one for each place it names, with the plan search or feature it came from and its rule as their reason. A locked plan is unlocked first, with that as its reason, so they go into its next version, which you lock to run them. The case log gets plan.edited and followup.added, with the version and the searches. dismiss hides it and logs followup.dismissed. 404 for a suggestion not listed for that search or feature; 409 for one dismissed or added already, from this job or an earlier run of the same plan search, or no longer suggested.

Parameters

  • id, in the path, required: string.

Body

JSON.

  • key, required: string. The suggestion, as listed.
  • action, required: one of add, dismiss.
  • job: string. The plan search the suggestion is for, by its job.
  • feature: string. The claim feature the suggestion is for, such as F2. Give job or feature.
  • user: string. Who, on the local workbench.

Answers

  • 200: With add, the plan version the searches go into and their IDs, or with dismiss the key; then the suggestions as GET /api/cases/{id}/follow-ups gives them, for the plan search or for the features.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

The summaries of the case, its results, the searches, the references and the claimed SEQ ID NOs, filled in from templates

GET /api/cases/{id}/summaries listCaseSummaries

Sequences fills in each summary from a fixed template and the case's facts each time it is read, with no model, so it says what the case holds now. Every case has its case summary: its application number and prior art date with where the date came from, its claims (how many, the independent ones, and the sets of claims it holds), its features by kind, its listing's sequences by molecule type with their lengths and organisms and the listing's ST.26 check, its claimed SEQ ID NOs, and its plan with its groups, sets and the features no search covers, ending with where the case stands. Once a search adds references, the results summary says how many references the case has, how many meet a claim feature's threshold, how many came before the prior art date, the top references in the list across the case, the features no reference meets, and the searches and files behind them. There is one for each search that adds references; for each feature's first 5 references and its kept ones; and for each claimed SEQ ID NO, with the claims that recite it and the paragraphs of the description that cite it. Each sentence names its source. A subject that has a decision keeps its summary while it is in the case. A decision holds while the template, its words, the facts and the draft all match what is filled in now. After a change in the case, decision.current is false and the report leaves the summary out until a new decision. Reading the summaries writes nothing.

Parameters

  • id, in the path, required: string.
  • seqIds, in the query: integer, 0 to 200, default 10. How many claimed SEQ ID NOs, from the first, get a summary: 0 to 200, 10 unless asked. One with a decision always has its summary.

Answers

  • 200: The summaries, with the templates and the claimed SEQ ID NOs.
  • Errors: 400, 401, 403, 404, as under Errors above.

Accept, edit or reject a summary, or a model's draft of one

POST /api/cases/{id}/summaries/decisions decideCaseSummary

The decision binds to the summary as it is filled in now. It names the template, the SHA-256 of the template's words and of the facts, and the draft it answers, and for an edit your words. The case keeps every decision, and the case log gets summary.accepted, summary.edited or summary.rejected with the same fields. 404 when the case no longer has the subject. 409 when its facts changed after you read it (send the factsSha256 you read), when it has nothing to summarize, or when it failed its checks. The report prints each summary accepted or edited while its decision holds. A decision on a model's draft sends its draftId in place of factsSha256 and names the draft's model, prompt ID and prompt SHA-256; 409 when a newer draft replaced it or the case changed after it was made. While an accept or an edit of a draft holds, the report prints it in place of the template's summary, marked as drafted by the model (Pilot). A rejected draft never reaches the report.

Parameters

  • id, in the path, required: string.

Body

JSON (CaseSummaryDecision). Name the summary by its kind and its subject: search; feature and reference; seqId; or the kind alone for case and results. A decision on a model's draft names the draft by draftId, and a kept publication's by explanation with search and reference.

  • kind, required: one of search, reference, seqId, case, results, explanation.
  • search: string, uuid. For a summary of a search: its job ID.
  • feature: string. For a summary of a reference: the claim feature, such as F2, or other.
  • reference: string. For a summary of a reference: its ID, as GET /api/cases/{id}/references gives it.
  • seqId: integer, 1 or more. For a summary of a claimed SEQ ID NO: the number.
  • action, required: one of accept, edit, reject.
  • factsSha256: string. For a template's summary: the factsSha256 of the summary you read. When its facts changed since, the answer is 409: read it again.
  • draftId: string. For a model's draft: the id of the draft you read, such as D3.
  • text: string. For an edit: your summary, one paragraph of up to 3,000 characters. Line breaks and runs of spaces read as one space.
  • user: string. On a server of your own with no sign-in, your name, up to 100 characters. A hosted server names the signed-in account.

Answers

  • 201: The summary with its decision, or for a draft its subject with modelDraft and modelTry.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Ask the model for a draft of a summary (Pilot)

POST /api/cases/{id}/summaries/drafts draftCaseSummary

Off unless the server names a model with the claims model settings: then the answer is 409 and nothing is sent. Drafting happens only on this request. The model gets one fixed prompt for the kind and the facts the kind's template reads, each part with its source, up to 20,000 characters, and the request asks for at most 2,048 answer tokens within the claims model's time limit. A server makes one call at a time, shared with claim suggestions; while one runs, another answers 409. Each span in quotation marks must appear in the text of a source in the facts, and each number in the facts, a percent matching one there to one decimal place; a draft that fails either check is dropped, with the check it failed. Every try is kept in the case with its model, prompt ID, prompt SHA-256, seconds and tokens, and the case log gets summary.drafted, summary.dropped or model.failed. The draft sits beside the template's text, which stays the default. With background, the answer is 202 with drafting, and GET /api/cases/{id}/summaries reads it until it ends. Without it, a call that fails answers 502 with the reason.

Parameters

  • id, in the path, required: string.

Body

JSON (CaseSummaryDraftRequest). Name what to draft: the case, its results, a claimed SEQ ID NO, or a publication kept in a search.

  • kind, required: one of case, results, seqId, explanation.
  • search: string, uuid. For a kept publication: the search's job ID.
  • reference: string. For a kept publication: its ID, as GET /api/cases/{id}/explanations gives it.
  • seqId: integer, 1 or more. For a claimed SEQ ID NO: the number.
  • background: boolean. True starts the call and answers 202 with drafting at once; GET /api/cases/{id}/summaries reads it until it ends.
  • user: string. On a server of your own with no sign-in, your name, up to 100 characters. A hosted server names the signed-in account.

Answers

  • 201: The try: passed with its text, or dropped with the checks it failed and why, without its words.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Every decision in the case, tied to the case's log

GET /api/cases/{id}/decisions.json exportCaseDecisions

Each claim feature as it stands, with where it came from; each accept, reject, edit and feature added by hand, with who and when, and for an edit the feature before and after; each call to the claims model with each suggestion kept or dropped and why; each decision on a drafted sentence and on a summary; and the plan's locked versions with each draft, edit, lock and unlock. Each decision names its event in the log by seq and hash, and log gives the chain's check. Reading it writes nothing. The file comes as an attachment.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The decisions.
  • Errors: 400, 401, 403, 404, as under Errors above.

Every decision in the case as CSV

GET /api/cases/{id}/decisions.csv exportCaseDecisionsCsv

One row for each claims import, switch from one set of claims to another, feature, decision on a feature, call to the claims model, suggestion kept or dropped, sentence decision, summary decision, plan event and locked plan version, named in record. A row on claims names their set, and current_set says whether it is the current set. The columns: record, seq, at, user, action, feature, source, rule, claim, kind, quote, start, end, details, links, status, note, before_quote, before_start, before_end, before_details, before_links, model, prompt_id, prompt_sha256, request_sha256, template_id, template_sha256, facts_sha256, checks, reason, kept, dropped, search, publication, sentence, subject, label, draft, text, latest, plan_version, plan_sha256, items, uncovered, rules_version, claims_sha256, hash, claim_set, set_label, set_date, current_set.

Parameters

  • id, in the path, required: string.

Answers

  • 200: The decisions. As text/csv.
  • Errors: 400, 401, 403, 404, as under Errors above.

The case report as PDF or Word

POST /api/cases/{id}/reports makeCaseReport

The file comes with its SHA-256 in the X-Report-Sha256 header.

Parameters

  • id, in the path, required: string.

Body

JSON.

  • format, required: one of pdf, docx.

Answers

  • 200: The report. As application/pdf or application/vnd.openxmlformats-officedocument.wordprocessingml.document.
  • Errors: 400, 401, 403, 404, 415, as under Errors above.

A locked plan version's search request, as Word or JSON

POST /api/cases/{id}/plan/versions/{n}/request downloadSearchRequest

What a search team or another system needs to run the version's searches: the case, its application number and prior art date, then each query group with its sequences in FASTA, its searches with their method and set, its thresholds and reasons, and the claims and features it serves, and last the version and the SHA-256 its lock recorded. The JSON file has format sequences-search-request and its version. The file comes with its own SHA-256 in the X-Report-Sha256 header, and the case log gets a plan.request event with it and the plan's SHA-256. 409 when the version no longer matches its fingerprint or its listing is gone.

Parameters

  • id, in the path, required: string.
  • n, in the path, required: string.

Body

JSON.

  • format, required: one of docx, json.

Answers

  • 200: The search request. As application/vnd.openxmlformats-officedocument.wordprocessingml.document.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Import a result file from BLAST+, FASTA36 or another program

POST /api/cases/{id}/imports importResultFile

Reads the file a program wrote on your own machine: BLAST+ tabular (-outfmt 6, or 7 with its # Fields: line), XML (-outfmt 5) or JSON (-outfmt 15); FASTA36 -m 8, with or without its comment lines; or CSV with a header row, such as a CSV of Sequences' own. Any other comma- or tab-separated file with a header row reads by the column map that columns gives (column map 1.0.0): every other column is kept with its row, as the row's file.extra, and the job's record keeps the import report, which GET /api/cases/{id}/imports/{jobId}/report gives; the case, the job and the log keep the map. The start of the file is checked at once, so a file the service cannot read is refused before it takes a place in the queue. Then a job joins each row's subject to the patent sequences of the case's snapshot and its weekly additions, by accession, by publication and SEQ ID NO, or by place (cb26) when the file names its database by a path that holds the case's snapshot, as a search of the snapshot's own databases does, and keeps the rows as a search of the case, of kind imported, that opens in the review view as any search does. Rows that do not join stay in its list; GET /api/cases/{id}/imports/{jobId}/unresolved gives the reason for each. The case log gets a results.imported event with the file's name, size, format and SHA-256. Up to 200 MB and 1,000,000 rows. A case holds up to 100 searches added by hand or imported.

Parameters

  • id, in the path, required: string.
  • name, in the query, required: string, up to 200 characters. The file name.
  • set, in the query: one of patent_nucl, patent_prot. The patent set to join to. Left out, the program a file names decides, and a file that names none is joined to both.
  • packed, in the query: one of page. page when the sender compressed the file only to send it: the case then records the unpacked file as the one chosen.
  • columns, in the query: string. For a file read by its columns: a JSON object of each field and the name of its column in the header row, such as {"hit":"Subject","identity":"% identity"}. The fields are query, hit, publication, seqNo, identity, coverage and score, and a map names the hit, or the publication and the SEQ ID NO. A header row has up to 1,000 columns. 400 when a name is not a column of the header row, or a column fills two fields.
  • header, in the query: integer, 1 or more. With columns: the line of the header row, counting from 1, in the first 64 KB of the file. Left out, the first line that is not blank.
  • delimiter, in the query: one of comma, tab. With columns: what splits the columns. Left out, the header row decides.

Body

The file as the program wrote it, or gzip compressed.

The file itself, as application/octet-stream or application/gzip.

Answers

  • 202: The search the import adds to the case, and its job, queued. Read GET /api/jobs/{id} until it ends.
  • Errors: 400, 401, 403, 404, 409, 413, 415, 429, 503, as under Errors above.

The rows of an imported file that did not join a stored patent sequence

GET /api/cases/{id}/imports/{jobId}/unresolved listImportUnresolved

Parameters

  • id, in the path, required: string.
  • jobId, in the path, required: string.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 500, default 50.

Answers

  • 200: One page of rows, in file order.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Every row of an imported file that did not join, as CSV

GET /api/cases/{id}/imports/{jobId}/unresolved.csv downloadImportUnresolved

Parameters

  • id, in the path, required: string.
  • jobId, in the path, required: string.

Answers

  • 200: One line per row: row, line, query, subject, publication, seq_id_no, reason. As text/csv.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

The column map and import report of an imported file

GET /api/cases/{id}/imports/{jobId}/report getImportReport

For a file read by its columns: the map it was read with, and what was read and skipped, and why, as the Report step shows it. A file read by its format has a null columnMap and report, and no sentences. 409 while the file is still being read.

Parameters

  • id, in the path, required: string.
  • jobId, in the path, required: string.

Answers

  • 200: The import report.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Connectors

Documents another system sends into cases, with a connector token.

Send a document set into a case (connector tokens)

POST /api/connector/imports importDocuments

For another system, such as a document system, with a connector token an admin made on the API tokens page; any other sign-in gets 403. Send multipart/form-data: first the part manifest, the JSON object ConnectorManifest, then a part named file for each file it lists, with the manifest's name for the file as the part's filename. The whole request is read before anything goes in: a manifest that cannot be read, an owner the token may not name, or a file that is missing, extra, too large or not the file its SHA-256 names answers 400, 403 or 413 and imports nothing. Then a listing goes in as an upload does, the case is made with it, and each file of claims or publication XML goes in as a set of claims; a publication's XML that holds its listing gives the listing too when the manifest lists none. A source and sourceId sent before add to the case they made, so the same manifest and files sent again change nothing and answer 200 with each file already. The answer gives a line for each file: imported, already or refused, with the reason. 409 when that case belongs to another account now; 429 with Retry-After when the queue has no room for the listing.

Body

The manifest, then its files.

The file itself, as multipart/form-data.

Answers

  • 200: The case these documents went into before, with a line for each file.
  • 201: A new case, made from the documents, with a line for each file.
  • 415: Send the manifest and its files as multipart/form-data.
  • Errors: 400, 401, 403, 404, 409, 413, 429, 503, as under Errors above.

Admin

For the admins of a hosted server.

Searches and other work by account and day, with the compute of the searches (admins)

GET /api/admin/usage getUsage

Parameters

  • days, in the query: integer, 1 to 90, default 30.

Answers

  • 200: The usage.
  • Errors: 400, 401, 403, 404, as under Errors above.

The searches and their compute by day, account and set, as CSV (admins)

GET /api/admin/usage.csv downloadUsage

One row for each UTC day, account and set a search ran on, newest day first, with the columns day, account, account_ref, set, searches, cpu_seconds, wall_seconds, peak_memory_bytes, bytes_read. A measure no search recorded is empty, and peak_memory_bytes is the most one search held.

Parameters

  • days, in the query: integer, 1 to 90, default 30.

Answers

  • 200: The CSV. As text/csv.
  • Errors: 400, 401, 403, 404, as under Errors above.

Every account's API tokens (admins)

GET /api/admin/tokens listAllTokens

Answers

  • 200: The tokens.
  • Errors: 400, 401, 403, 404, as under Errors above.

Revoke any token (admins)

DELETE /api/admin/tokens/{id} revokeAnyToken

Parameters

  • id, in the path, required: string.

Answers

  • 200: The token, revoked.
  • Errors: 400, 401, 403, 404, as under Errors above.

The connector tokens (admins)

GET /api/admin/connector-tokens listConnectorTokens

Answers

  • 200: The tokens, never their secrets, with the limits for a new one.
  • Errors: 400, 401, 403, 404, as under Errors above.

Make a connector token (admins, browser sign-in only)

POST /api/admin/connector-tokens createConnectorToken

A token for another system to send documents into cases (POST /api/connector/imports). It calls only that route, makes cases only for the accounts named here, and works only while the admin who made it is an admin. Each account must have signed in here and be let in now. A request signed in with a token gets 403. The answer holds the token once; the server keeps only its SHA-256 hash. 409 at 20 live connector tokens.

Body

JSON.

  • name, required: string. 1 to 100 characters, such as the system that will use it.
  • days: integer, 1 to 90. How long it lasts. The default and the most is the server's setting.
  • owners, required: a list of 1 to 50 strings, or a string. 1 to 50 accounts it may make cases for, as each signs in: a list, or one text with commas or new lines between them.

Answers

  • 201: The token record and the token itself.
  • Errors: 400, 401, 403, 404, 409, 415, as under Errors above.

Revoke a connector token (admins)

DELETE /api/admin/connector-tokens/{id} revokeConnectorToken

Parameters

  • id, in the path, required: string.

Answers

  • 200: The token, revoked.
  • Errors: 400, 401, 403, 404, as under Errors above.

The workers that run searches for this server (admins)

GET /api/admin/workers listWorkers

On a coordinator (BIOSEQUENCE_ROLE=coordinator), each worker that joined it, by name: in contact, lost, or refused while it had the worker key. Any other server lists none. A lost worker stays listed until a worker of its name joins or the coordinator starts again; a refused worker that stops saying hello leaves the list after 60 seconds. Times are this server's.

Answers

  • 200: The role and the workers.
  • Errors: 400, 401, 403, 404, as under Errors above.

Delete a case with its searches (admins)

DELETE /api/admin/cases/{id} deleteCase

Deletes the case and everything it holds: its claims, plan, runs, decisions, notes, reports, log and imported result files, every search its plan ran, and each search added to it that no other case holds, with their exact alignments. Each plan run that still waits or runs is cancelled first, with its plan.cancelled event in the case's log, which events and lastEvent then count, and so is any other search still queued or running. Listings stay. A deletion cannot be undone. The service's audit log keeps a case.deleted event with the case ID, its owner, its log's last event by number and SHA-256, the count of searches deleted and the bytes. 404 for a case that does not exist; 409 while the claims model reads the case, or while one of its searches is still stopping.

Parameters

  • id, in the path, required: string.

Answers

  • 200: What was deleted.
  • Errors: 400, 401, 403, 404, 409, as under Errors above.

Every case's decisions, to measure the claim rules and prompts (admins)

GET /api/admin/decisions.json exportAllDecisions

One row for each claim feature, call to the claims model, dropped suggestion, sentence decision and summary decision in every case, with the case ID and the account by the start of its ID, and totals. A drop reason is in fixed words. It holds no claim words, quotes, details, notes or edits: claims pasted into a case can be from an unpublished application. A case that cannot be read is listed under skipped. The file comes as an attachment.

Answers

  • 200: The rows and their totals.
  • Errors: 400, 401, 403, 404, as under Errors above.

Every case's decisions as CSV (admins)

GET /api/admin/decisions.csv exportAllDecisionsCsv

The rows of GET /api/admin/decisions.json, and a row for each case that could not be read. The columns: record, case, account_ref, at, claims_source, rules_version, feature, source, rule, claim, kind, status, edited, action, latest, model, prompt_id, prompt_sha256, template_id, template_sha256, checks, kept, dropped, seconds, reason, claim_set.

Answers

  • 200: The rows. As text/csv.
  • Errors: 400, 401, 403, 404, as under Errors above.

The audit log for a day or a time range, as JSON lines for a SIEM (admins)

GET /api/admin/audit.jsonl exportAudit

Give day, a UTC date, or from and to, ISO 8601 times with a time zone (from is in the range and to is not). Each line is one JSON object, and its record says what it is. An event line gives one event of one log: the service's own (sign-ins, sign-outs, API tokens, trials, starts with their settings, invite list changes, audit exports, deleted working files and records, and deleted cases), a case's, or an account's applicant joins. Its event holds the stored event whole for the service's log, and otherwise its type, time, user, IDs, counts and hashes, with the fields left out named in withheld: claims pasted into a case can be from an unpublished application. A log's events in the file follow one another in its chain, from the first in the range to the last, and a chain line after them gives the first and last event numbers, the hash before the first, the log's head and the server's check of the whole log. The export line comes last, with the counts. Each export is noted in the service's log. The file comes as an attachment.

Parameters

  • day, in the query: string, date.
  • from, in the query: string, date-time.
  • to, in the query: string, date-time.

Answers

  • 200: The lines. As application/x-ndjson.
  • Errors: 400, 401, 403, 404, as under Errors above.

Known variants

Where a protein query differs from a reviewed human protein it hits, each change ClinVar records, and the protein changes ClinVar records on that protein, from ClinVar, RefSeq and UniProt.

The ClinVar variations placed on a reference protein

GET /api/variants/references/{sha256} getVariantsReference

The protein is named by the SHA-256 of its letters, in lowercase, as a hit row's variants.sha256 gives it: a reviewed human UniProtKB/Swiss-Prot sequence whose letters are exactly those of a RefSeq protein ClinVar names. One page of the ClinVar variations whose protein changes are placed on it, by position, then change, then variation, and each classification with how many changes have it. significance keeps one classification, and an empty value those ClinVar leaves unclassified. 25 a page by default. 400 for text that is not a SHA-256; 404 when no reviewed human protein in this server's release has those letters.

Parameters

  • sha256, in the path, required: string.
  • offset, in the query: integer, 0 or more, default 0.
  • limit, in the query: integer, 1 to 200, default 25.
  • significance, in the query: string. One germline classification, as significances gives it. Empty keeps the changes ClinVar leaves unclassified.

Answers

  • 200: The protein and one page of its ClinVar variations.
  • Errors: 400, 401, 403, 404, as under Errors above.