General structure

Redivis implements a REST API for creating, reading, updating, and deleting various resources.

The Open API specification is discoverable at the API's base URL: https://redivis.com/api/v1. The specification is returned in YAML format; if you prefer JSON, you can specify https://redivis.com/api/v1?format=json.

In most cases, it will be easier to utilize the Python, R, and Javascript client libraries, rather than interfacing with the REST API directly.

Calling API methods

All API methods our organized by their respective resource and documented under the REST API section of this documentation. These methods follow common patterns that are enumerated below:

Request headers

In order to interface with the API, you will need to provide an appropriate access token in the headers of your request. Read more about API authorization >

Request parameters

Most methods require certain parameters in the URL path to specify the relevant resource(s). For example, /api/v1/organizations/:orgReference/datasets.

Certain methods will also allow for (or require) query parameters in the URL path. For example, /api/v1/organizations/:orgReference/datasets?maxResults=100

Request body

Some methods support sending a body with the request. This body will typically be a JSON-encoded string with properties corresponding to the resource being created or updated.

The only exceptions will be when uploading various files to Redivis, in which case the body is treated as a binary stream.

HEAD, GET, and DELETE requests will never have a request body.

Response status

The following status codes are returned by this API:

• 200: The response was successful

• 400: The request was malformed or is otherwise invalid. Validate that your parameters and/or request body are valid, and that the given operation is appropriate for the requested resource.

• 401: Invalid credentials. Either your request is missing credentials, credentials have expired, or are otherwise malformed.

• 403: Not authorized. You do not have access to the request resource, or the scope associated with your API credentials does not allow for the given operation.

• 404: Not found. The resource could not be found. Note that if you don't have the ability to view a resource, the API will typically return a 404 to avoid revealing the existence of that resource, even though this is really an authorization / access error.

• 500: Internal error. This means an unexpected internal error has occurred. You can retry the request, or contact Redivis support if the problem persists.

Response headers

In addition to standard HTTP headers, the API will include the following headers on the response:

• X-RateLimit-Limit: The total number of requests within the rate limit interval

• X-RateLimit-Remaining: The number of allowed requests remaining in the current interval.

• X-RateLimit-Reset: The point in time (represented as ms since the epoch) after which the rate limit will reset itself.

• Retry-After: If the rate limit is exhausted, this header will inform the point in time (represented as ms since the epoch) after which requests can be resumed.

• X-Redivis-Warning: User-facing warnings that may contain helpful information for consumers of this API. This header may be repeated if a particular request causes multiple warnings.

• X-Redivis-Error-Payload: Only present on HEAD requests when an error occurs, since no body can be sent in the response. Contains the JSON-encoded error that would typically be present in the response body.

Response body

All methods provide a body in the response, with the exception of those that use the HTTP HEAD or DELETE verbs. Typically, the body will be JSON-encoded content corresponding to the relevant resource(s), as specified within the Resource Definitions section of this documentation.

The only exceptions will be when retrieving raw data from Redivis, where the body contents and content type will correspond to the data being returned.

Errors

For all 40x and 50x status codes, the body will contain JSON-encoded information containing details about the error (HEAD requests that error will instead contain an X-Redivis-Error-Payload header). This error will take the form:

{
    "status": number, // http status code
    "error": string,  // The error type, e.g., "invalid_request"
    "error_description": string, // More detailed information about the cause of the error
}

Rate Limits

The API is currently limited to roughly 1,000 request per 60-second interval. The X-RateLimit-Limit header on all responses will be set to 1000, and the X-RateLimit-Remaining will reveal the number of requests remaining within the current interval.

If the limit is exceeded for the current interval, you will receive a 429 error with a Retry-After header, specifying when you may resume requests.