General structure

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

The Open API specification is discoverable in YAML and JSON format at:

• https://redivis.com/api/v1/openAPI.yaml
• https://redivis.com/api/v1/openAPI.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.
• 402: Quota exceeded. You have exceeded the usage quota for a given operation. You may need to get or purchase additional quota, or, if the quota is duration based, you can wait for it to reset per the duration in the Retry-After response header.
• 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.
• 429 Rate limited. You have exceeded the allowed rate of API requests in a given period. You can retry the request after the number of seconds in the Retry-After response header.
• 500: Internal error. This means an unexpected internal error has occurred. You can retry the request, or contact Redivis support if the problem persists.
• 503: Service unavailable. This is likely a transient error, and the request should be retried based on the number of seconds in the Retry-After header.

Response headers

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

• If the endpoint has a rate limit, RateLimit and RateLimit-Policy will be set per the RateLimit header fields for HTTP standardization draft adopted by the IETF.
• Retry-After: If the service is unavailable, or quota / rate limit is exhausted, this header will inform the number of seconds until which the request can be retried.
• 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 for most endpoints. If the endpoint has a rate limit, RateLimit and RateLimit-Policy response headers will be set per the RateLimit header fields for HTTP standardization draft adopted by the IETF.

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