Endpoint Types

The API for consuming CIViC data can mostly be broken down into two different types of endpoints: index and detail.

Index Endpoints

The index endpoints provide high level overview information about a collection of entities all at once and allow a user to page through all the entities in the system. Index endpoints provide two top-level keys in their JSON structure: _meta and records.

Example /genes Request

curl https://civicdb.org/api/genes

Example /genes Response (partial)

Expecting value: line 1 column 1 (char 0)

Meta Attribute

As seen to above, the _meta section contains information about the total number of available records, the page size, and provides links to the next and previous page of results. These links can be used to easily traverse all of the records in CIViC. A null entry for next (or previous) indicates that you have reached the end of the collection.

Records Attribute

The records section will contain the actual objects requested in the API call (ie: genes, variants or evidence_items)

If you do not wish to use the links in the _meta section, index endpoints also accept manual pagination parameters in the query string:

Example /genes Request with Manual Pagination

curl https://civicdb.org/api/genes?page=2&count=25

Meta Pagination Parameters

Parameter	Default	Description
page	1	Which page of results to return
count	25	How many records to return on a single page

Detail Endpoints

Detail endpoints return the full CIViC record for a single entity, specified explicitly by id. In addition to the high level overview information returned by the index endpoint, this complete record will include information about data provenance, timestamps, and secondary relationships. Unlike the index endpoints, detail endpoints do not have separate _meta and records sections as only a single record is returned.

Example /genes Detail Request

curl https://civicdb.org/api/genes/533

Example /genes Detail Response

Expecting value: line 1 column 1 (char 0)