Skip to content
Console(opens in a new tab)

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.

Send each request to this endpoint with the POST method:

https://api.enigma.com/graphql

The 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.

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"}

The request body is a JSON object with two keys:

  • query holds the GraphQL document. This key is necessary.
  • variables holds the values of the variables in the document. This key is optional.

The API ignores operationName. Send one operation in each request.

Terminal window
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"}}]}}]}}

The response body is a JSON object with these keys:

  • data holds the answer, in the shape of your query.
  • errors holds a list of error messages. Each item is a plain string. It is not an object with message, locations, and path, as the GraphQL specification describes.
  • extensions holds 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 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.

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.

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.

  • 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 first to get more records or fewer records.

To write and run queries in a browser, use the API Playground in Enigma Console.