The Everlaw API is organized around REST. Our API has predictable resource-oriented URLS, returns JSON-encoded responses, and uses standard HTTP response codes, authentication and methods.

The Everlaw API uses API keys to authenticate requests. You can view and manage keys for your organization on the Organization Admin page.

Your API keys grant access to your Everlaw platform data - be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, open S3 buckets, etc.

You should provide your API key as a Bearer token when making an API request by setting the "Authorization" header:

Authorization: Bearer everlaw-api.XXXX.YYYYYYYY

You must provide your API key with every request, and all API requests must be made over HTTPS.

All responses are in JSON format. Response entities are encapsulated in a JSON object along with any other top-level response content, e.g. pagination links (see the Pagination section below):

{
   "data": {
       "id": 1,
       "name": "Test Project"
       ...
   }
}

Some API endpoints fetch lists of objects (e.g. listing all users in an organization). These list API endpoints share a common structure, taking at least these two parameters: limit and after. The Everlaw API utilizes cursor-based pagination via the after parameter. This parameter takes an existing object ID value and returns objects starting after the given ID. The limit parameter specifies how many objects you would like to return in a given request.

Paginated responses will include a links entry in the top-level response that provides pre-built pagination links for fetching more results (if they exist). This links object will always include a next key which is a URL to fetch the next page of results OR null if this was the last page of results:

{
   "data": [{
       "id": 1,
       "name": "Test Project"
       ...
   }],
   "links": {
       "next": "https://...."
   }
}

The Everlaw API employs rate limiting to help limit the performance impact of API activity and maintain stability. There is a fixed rate limit of 25 requests per second enforced per authenticating user account. Request rates that exceed this limit may see error responses with status code 429. Additionally, there is a stricter rate limit enforced for failed authentication (invalid/missing API tokens).

A basic approach for handling rate limiting is to watch for 429 status codes and employ a retry mechanism. This retry mechanism should follow an exponential backoff schedule (with increasing delays between successive retries) to reduce request rates when necessary.

When using the Everlaw API it is important to consider users that are interacting through the Everlaw platform - actions you take through the API (particularly those that create or modify platform objects, such as uploads/datasets) can impact the platform experience for your reviewers. To help keep this experience user-friendly and performant, Everlaw imposes some limits on how the API can be used, including the rate limits discussed above as well as operation-specific limits. These limits include caps on the number of user-visible objects created via the API (for example, a limit on the number of datasets that can be created via the API), and will be called out on the specific operations below.

If you hit one of these limits, the operation will fail with response code 422 (unprocessable) and include an error message indicating the particular limit. These limits can be adjusted for specific databases or organizations as necessary to allow for continued API use - please contact Everlaw Support for more information or if you would like to adjust a particular limit.

The Everlaw API uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success; codes in the 4xx range indicate an error with the request content (e.g. a missing parameter, or insufficient permissions); codes in the 5xx range indicate an error with our servers (e.g. scheduled maintenance).

Error responses will include a JSON body with a human-readable title indicating the cause of the error and the HTTP status code:

{
    "title": "You do not have permission to make this request",
    "status": 403
}

Users on Everlaw are typically members of one or more organizations. These organizations are a convenient way to group and manage user accounts as well as case data (databases and projects) owned by the organization. Each organization is associated with a list of members (some of whom may be "org admins") as well as a list of databases and their associated projects that the organization owns.

Organizations are administered by members that have been granted the "org admin" role, allowing them administrative control over membership, SAML/SSO configuration, access to organization-owned cases, management permissions over organization API keys, and other functionality. Organization-level API keys are also granted this "org admin" role. For more details, see Organization Administrator.

Matters on Everlaw are organized into top-level entities known as databases. Each database is a separate collection of documents owned and administered by a particular organization. Every database has one or more associated projects, which contain a subset (possibly all) of the documents in the database, but which have their own entirely separate review work. For more details, see Database and Project Permissions.

Permissions

There are a few important actions possible at the database level - in particular, uploading and deleting documents and administering (creating/modifying/deleting) projects associated with the database. These are managed via permissions on the database objects. For more details, see Database Administration and Permissions.

At the project level, permissions are managed via User Groups, which comprise a set of permissions and a list of members granted those permissions. Users can be members of one or more groups, and are granted the union of all the permissions of those groups. For more details, see User Groups and Project Permissions.

Organization admins are by default granted administrative access to the databases owned by that organization (as well as all associated projects). It is possible to disable this org admin access for specific databases as necessary to limit org admin access; in that case, org admins will be able to fetch basic summary information about the database/projects (e.g. its name, total billable size, etc) but not access documents or other similar data. This distinction is reflected in the separation of "Database/Project Org Admin" endpoints from others at the database and project levels. For more details, see Organization Admin: Organization and Project Administration.

Matters on Everlaw are billed based on the amount of data hosted each month. There are several endpoints available to fetch billing information for a particular month by database or project or across an entire organization. This billing information includes sizes of the hosted data by data type (native, pre-processed, produced) and storage type (standard, ECA) as well as project/database status information relevant for billing - e.g. when a project was suspended or deleted.

Monthly billing information will include both final sizes and peak sizes. Final sizes reflect the size at the end of the month (or the current date, if the month has not yet ended), whereas peak sizes reflect the maximum size observed over the given month (which is the basis for computing your actual bill). Each size point includes sizes for Standard and ECA (Early Case Assessment) data, which are further broken down by data type.

Monthly billing information also includes status information that reflects the state of the project/database over the course of the month. This includes the effective state of the project for the sake of billing (i.e. do we consider the project to have been active/suspended/deleted for the month), the final/end-of-month state for the project, and timestamps for important state changes (e.g. suspension, deletion).

When requesting billing information for a database, our response will include separate billable size and state information for each project in that database, as well as a combined overall billable size and state for the database. The combined database size typically reflects the size of the largest project in that database, and the status is the merger of the status of all the projects (e.g. if any project is active, the database as a whole is considered active; if all projects are suspended, the database is considered suspended, etc).

Global operations.