- Docs
- API reference
- Endpoints and schemas
- GraphQL
API basics
The endpoint, the request and the response, authentication, status codes, and the limits of the GraphQL API.
Every intent in this reference goes through one endpoint, with the same request format and the same rules. This page gives those rules. Read it before your first query.
Endpoint
Section titled “Endpoint”Send each request to this endpoint with the POST method:
https://api.enigma.com/graphqlThe API accepts no other method. Set the Content-Type header to application/json exactly. The API rejects a header with a parameter, such as application/json; charset=utf-8, with a 400 response.
Authentication
Section titled “Authentication”Send your API key in the x-api-key header of each request. To create a key, open the API keys page of Settings in Enigma Console.
| Key | Status | Response body |
|---|---|---|
| Missing, unknown, or deleted | 401 | {"error_message": "Missing or invalid API key", "error_code": "UNAUTHORIZED", "retryable": false} |
| Disabled | 403 | {"message": "API key is disabled"} |
Request
Section titled “Request”The request body is a JSON object with two keys:
queryholds the GraphQL document. This key is necessary.variablesholds the values of the variables in the document. This key is optional.
The API ignores operationName. Send one operation in each request.
curl https://api.enigma.com/graphql \ --request POST \ --header "Content-Type: application/json" \ --header "x-api-key: $ENIGMA_API_KEY" \ --data '{"query": "query FindBrand($name: String) { search(searchInput: { entityType: BRAND, name: $name, conditions: { limit: 1 } }) { ... on Brand { id names(first: 1) { edges { node { name } } } } } }", "variables": {"name": "Safeway"}}'Response:
{"data":{"search":[{"id":"0f26fbef-3436-4f85-8bcd-31fe12a4f99a","names":{"edges":[{"node":{"name":"SAFEWAY"}}]}}]}}Response
Section titled “Response”The response body is a JSON object with these keys:
dataholds the answer, in the shape of your query.errorsholds a list of error messages. Each item is a plain string. It is not an object withmessage,locations, andpath, as the GraphQL specification describes.extensionsholds the background tasks that the request started, when it starts one.
A response can hold data and errors together. When the API rejects a query before it runs it, the response holds errors only:
{"errors": ["Syntax Error: Expected Name, found '}'."]}Each response has an X-Enigma-Request-Id header. Give this ID when you contact support about a request.
Status codes
Section titled “Status codes”| Status | Meaning |
|---|---|
| 200 | The request succeeded. |
| 202 | The request started a background task, for example a search with output. The task is in extensions.backgroundTasks. Read its progress with backgroundTask. |
| 206 | Some values that you requested are still in progress. The task that computes them is in extensions.backgroundTasks. |
| 302 | The response is larger than about 6 MB. The Location header holds a URL to the response, and the URL is valid for 24 hours. Follow the redirect to read the response. |
| 400 | The request is not valid, or the account has no credits left. Read the errors list. |
| 401 | The API key is missing or not valid. |
| 403 | The API key is disabled. |
| 429 | You sent too many requests. When the response has a Retry-After header, wait that number of seconds before you send the request again. |
| 500 | The API had an internal error. |
| 504 | The request took too long to complete. Try again later, or ask for fewer records. |
Rate limits
Section titled “Rate limits”The limits apply to searches, and the API counts them for each API key.
| Plan | Searches per second | Searches per day |
|---|---|---|
| Free | 20 | 2,000 |
| Pro | 20 | No limit |
| Max | 20 | No limit |
| Enterprise | 100 | No limit |
A search that writes its result to a CSV file has a separate limit of 3 requests per second on all plans.
When you go above a limit, the API returns a 429 response with the message Rate limit exceeded. Try again in N seconds. and a Retry-After header.
Credits
Section titled “Credits”Searches and list mutations use credits from your account. When the account has no credits left, the request fails with a 400 response. The message links to the billing page of Enigma Console, where you can add credits.
Query limits
Section titled “Query limits”- A query can have a depth of 40 levels at most. A deeper query fails with a 400 response.
- Each connection returns a default number of records. Set
firstto get more records or fewer records.
Try a query
Section titled “Try a query”To write and run queries in a browser, use the API Playground in Enigma Console.