Gretel.ai REST API Documentation

Welcome to the Gretel.ai REST API documentation. These APIs allow you to ingest data to Gretel and explore the data we are able to extract. These are the same APIs used by our [Console](https://console.gretel.cloud). By exposing the APIs, we hope you are able to build your own workflows around Gretel. Additionally, we provide API bindings for [Python](https://github.com/gretelai/gretel-python-client) that allow simpler use of the APIs for certain tasks. Our Python bindings also include a transformation SDK that you can use to make changes to your data for anonymization and other use cases. ### Authentication With the exception of authentication resources, all requests to this API must include an Authorization header. There are two forms of authorization currently. First, you can obtain a JSON Web Token from our authentication endpoints. If using a JWT the header will look like: `Authorization: Bearer YOUR_TOKEN` Second, you can create a persistent API Key from our console. When using this key, the header will look like: `Authorization: grtu****` You should not use the `Bearer` prefix when using your Gretel User Key. ### Project Endpoints When using endpoints that have projects in them you may use the unique project `name` or the project ID in the path parameters. ### Request Structure Unless otherwise specified, all request bodies should be in JSON format. Any URL parameters should be properly escaped using common utilities. #### Search Query Parameter When utilizing an endpoint that supports a `query` parameter, please use the following format: ``` text ?query=field1:this;field1:that;field2:*val*;exists;-notexists ``` - Including duplicate references to a field will return entities matching one of the provided values (an "or" filter). For example, `field:thing1;field:thing2` will return entities that have either `thing1` or `thing2` in the `field` field. - Partial matching on a field can be done by adding asterisks in the provided value. Only one of these filters may be applied per field and cannot be used along with explicit field queries. For example, `field:*thing*` will return entities that have `thing` anywhere in the `field` field. - Field existence checking can be done by including the field name without a value, prepending a `-` to check for non-existence. For example, `exists;-nexists` will return entities that have the `exists` field and do not have the `nexists` field. - Only include fields listed as supported by the endpoint documentation. Extra fields will result in an error response. #### Search Sort Parameter The `sort` parameter can include one or more comma-separated fields. By default, the results will be sorted by the provided fields in ascending order. To sort in descending order, prepend a `-` to the field. For example, `field1,-field2` will sort the results by `field1` in ascending order and then by `field2` in descending order. ### Response Structure All valid responses will be in JSON format. The following error codes are utilized: 200: Valid response, payload will be JSON 400: A request error on the client, body will have a `message` and a `context` property. The message property will be a human readable string on what went wrong. Context will contain field specific details where the field could be a query param, JSON payload property, etc. 401: Access is not granted to the resource due to project membership issues or membership level issues. Note that access to a non-existant project will result in a 401 as well. 403: Rate limiting for the endpoint is in effect.