Sign in

v1

latestOpenAPI 3.0.1Apache 2.02026-07-1783686.1 KB
query

Initiate a query and wait to receive a Response

post/query

Request body

log_level'ERROR' | 'WARNING' | 'INFO' | 'DEBUG'

Logging level

submitterstring nullable

Any string for self-identifying the submitter of a query. The purpose of this optional field is to aid in the tracking of the source of queries for development and issue resolution.

bypass_cacheboolean

Set to true in order to request that the agent obtain fresh information from its sources in all cases where it has a viable choice between requesting fresh information in real time and using cached information. The agent receiving this flag MUST also include it in TRAPI sent to downstream sources (e.g., ARS -> ARAs -> KPs).

stream_progressboolean

Set to true in order to receive a stream of LogEntry objects as the query is progressing

enforce_edge_directionalityboolean

Set to true in order to enforce edge directionality during queries. By default, edge directionality can be reversed without penalty.

return_minimal_metadataboolean

Set to true in order to return only the most minimal metadata. By default, rich metadata for nodes and edges are supplied, which may cause a very large and slower Response.

max_resultsinteger

Maximum number of individual results to return

page_sizeinteger

Split the results into pages with this number of results each

page_numberinteger

Page number of results when the number of results exceeds the page_size, with page 1 as the first page

Example request

{
  "message": {
    "query_graph": {
      "edges": {
        "e00": {
          "subject": "n00",
          "object": "n01",
          "predicates": [
            "biolink:physically_interacts_with"
          ]
        }
      },
      "nodes": {
        "n00": {
          "ids": [
            "CHEMBL.COMPOUND:CHEMBL112"
          ]
        },
        "n01": {
          "categories": [
            "biolink:Protein"
          ]
        }
      }
    }
  },
  "log_level": "DEBUG",
  "max_results": 100,
  "page_size": 100,
  "page_number": 1,
  "operations": {
    "message_uris": [
      "https://arax.ncats.io/api/arax/v1.3/response/38"
    ],
    "messages": [
      {
        "query_graph": {
          "edges": {
            "e00": {
              "subject": "n00",
              "object": "n01",
              "predicates": [
                "biolink:physically_interacts_with"
              ]
            }
          },
          "nodes": {
            "n00": {
              "ids": [
                "CHEMBL.COMPOUND:CHEMBL112"
              ]
            },
            "n01": {
              "categories": [
                "biolink:Protein"
              ]
            }
          }
        }
      }
    ],
    "actions": [
      "add_qnode(name=acetaminophen, key=n00)",
      "add_qnode(category=biolink:Protein, key=n01)",
      "add_qedge(subject=n01, object=n00, key=e00)",
      "expand(edge_key=e00)",
      "resultify()",
      "filter_results(action=limit_number_of_results, max_results=10)"
    ],
    "options": {
      "halt_on_warning": false
    }
  }
}

Response

OK. There may or may not be results. Note that some of the provided identifiers may not have been recognized.

statusstring nullable

One of a standardized set of short codes, e.g. Success, QueryNotTraversable, KPsNotAvailable

descriptionstring nullable

A brief human-readable description of the outcome

submitterstring nullable

Any string for self-identifying the submitter of a query. The purpose of this optional field is to aid in the tracking of the source of queries for development and issue resolution.

job_idstring nullable

An identifier for the submitted job that can be used with /async_query_status to receive an update on the status of the job.

resource_idstring nullable

Identifier string of the resource that provided this response (one of ARAX, Aragorn, etc.)

tool_versionstring

Version label of the tool that generated this response

schema_versionstring

Version label of this TRAPI schema

biolink_versionstring

Version label of the Biolink model used in this document

datetimestring

Datetime string for the time that this response was generated

table_column_namesstring[]

List of column names that corresponds to the row_data for each result

original_questionstring

The original question text typed in by the user

restated_questionstring

A precise restatement of the question, as understood by the Translator, for which the answer applies. The user should verify that the restated question matches the intent of their original question (it might not).

query_optionsobject

Dict of options that can be sent with the query. Options are tool specific and not stipulated here

contextstring

JSON-LD context URI

typestring

Entity type of this response

idstring

URI for this response

validation_resultobject

Validation results and other summary stats computed for this Response.

total_results_countinteger nullable

The total number of results that were generated prior to any filtering.

infostring nullable

A placholder for including some additional information

Example response

{
  "original_question": "what proteins are affected by sickle cell anemia",
  "validation_result": "{}",
  "submitter": "submitter",
  "workflow": [
    "",
    ""
  ],
  "query_options": {
    "coalesce": true,
    "threshold": 0.9
  },
  "restated_question": "Which proteins are affected by sickle cell anemia?",
  "biolink_version": "3.1.2",
  "description": "Success. 42 results found.",
  "message": {
    "query_graph": {
      "edges": {
        "e00": {
          "subject": "n00",
          "object": "n01",
          "predicates": [
            "biolink:physically_interacts_with"
          ]
        }
      },
      "nodes": {
        "n00": {
          "ids": [
            "CHEMBL.COMPOUND:CHEMBL112"
          ]
        },
        "n01": {
          "categories": [
            "biolink:Protein"
          ]
        }
      }
    }
  },
  "type": "TranslatorAPIResponse",
  "total_results_count": 0,
  "schema_version": "1.4.0",
  "datetime": "2021-01-09 12:34:45",
  "operations": "",
  "table_column_names": [
    "chemical_substance.name",
    "chemical_substance.id"
  ],
  "tool_version": "ARAX 0.8.0",
  "job_id": "rXEOAosN3L",
  "context": "https://rtx.ncats.io/ns/translator.jsonld",
  "resource_id": "ARAX",
  "id": "https://arax.ncats.io/api/rtx/v1.3/response/123",
  "logs": [
    {
      "code": "code",
      "level": "",
      "message": "message",
      "timestamp": "2020-09-03T18:13:49Z"
    },
    {
      "code": "code",
      "level": "",
      "message": "message",
      "timestamp": "2020-09-03T18:13:49Z"
    }
  ],
  "status": "Success",
  "info": "info"
}