CIViC API

V2 API

The V2 API documentation can be found here.

Our full API documentation can be found on GitHub.

We’ve developed a graphical user interface for accessing the new API, including a set of useful example queries.

A set of example usage scripts of the API in Python, R, and Ruby can be found on our GitHub repo.

Using API Keys in Requests

CIViC API keys authenticate API requests as the user who generated the key. They can be used for requests that require a logged-in user, such as mutations (i.e., API requests that execute a curation or editorial action), or for API clients that should not be subject to the default anonymous request rate limit.

To generate an API key, sign in to CIViC, open your user profile, choose Manage API Keys, and click Generate New API Key. Copy the key when it is created and store it in a secure location, such as a password manager. CIViC only shows the full token at creation time; after that, the key list displays a masked reminder. Revoke any key that is no longer needed or may have been exposed.

Include the key in the HTTP Authorization header using the bearer token scheme:

Authorization: Bearer <CIViC_API_KEY>

For example, a GraphQL request with curl:

curl https://civicdb.org/api/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ${CIVIC_API_KEY}" \
  --data '{"query":"query { viewer { id username } }"}'

Or with Python:

import os
import requests

response = requests.post(
    "https://civicdb.org/api/graphql",
    headers={
        "Authorization": f"Bearer {os.environ['CIVIC_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={"query": "query { viewer { id username } }"},
)
response.raise_for_status()
print(response.json())

Do not place API keys in URLs, query strings, checked-in scripts, or shared notebooks. Use environment variables or a secrets manager when running automated clients.

API Usage Expectations

By default, API queries against the CIViC knowledgebase are rate-limited to 3 requests / second as measured over a 5 minute window. This allows you to burst higher than that rate for brief periods, or sustain that rate indefinitely. If you generate a (free) API key and provide it with your requests, that limit does not apply. We do however, reserve the right to impose additional rate limits to curb abuse or overly excessive use. We ask that users with high-throughput or continuous use needs consider using CIViCpy for these purposes.

V2 Contents:

V1 API (deprecated)

CIViC provided a RESTful API that has been deprecated and is no longer available.