API Basics

Basics

The API can be used to generate programmatic requests to Platform. You can use it to create new jobs, list users, organize projects, and more. For most users, it's best to get started by using the Civis-provided Python or R clients.

Base URL

The Civis API is hosted at https://api.civisanalytics.com/ - This is the prefix for all the endpoints.

Authentication

There are multiple ways to authenticate your API calls:

• Be logged into Civis and hit the API from within your browser, or
• Generate an API key from your user profile page and either
• use HTTP Basic auth (the API key is the username, leave the password blank)
• set the Authorization header to Bearer API_KEY

Versioning

The Civis API is versioned. Specify the version with the Accept header set to application/vnd.civis-platform.v1 , or don't specify it and you'll float to version 1.

Rate Limits

API requests are limited to 1000 general requests or 100 Run-creating requests per 300 seconds. If that limit is exceeded, Civis will return a HTTP 429 response. The current limit, which is subject to change, is included in the X-RateLimit-Limit header. The number of remaining requests is included in the X-RateLimit-Remaining header. The Civis-provided clients for Python and R will handle these headers for you automatically to slow requests.

Note that some clients also generate a request to retrieve the latest API and dynamically create themselves accordingly. These requests also count towards the general rate limit. Refer to the documentation for each client to understand how to limit these requests.

Permissions 

Receiving an HTTP 404 response from the Civis API could indicate that you do not have permission to perform that task.