# 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: * * {% hint style="success" %} In most cases, it will be easier to utilize the [Python](https://docs.redivis.com/api/client-libraries/redivis-python), [R](https://docs.redivis.com/api/client-libraries/redivis-r), and [Javascript](https://docs.redivis.com/api/client-libraries/redivis-js) client libraries, rather than interfacing with the REST API directly. {% endhint %} ## Calling API methods All API methods our organized by their respective resource and documented under the [REST API](https://docs.redivis.com/api/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 >](https://docs.redivis.com/api/rest-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](https://redivis.com/contact) 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](https://docs.redivis.com/api/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: ```json { "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](#429) error with a `Retry-After` header, specifying when you may resume requests.