Authentication

The API uses keys for authentication, and your key is similar to a password. Avoid distributing your API key to other users, or hard-coding it. Generate a new key whenever you think your account may have been compromised.

For security reasons, your API key automatically expires every 90 days. When your key has expired, you must generate a new one to continue using the API.

πŸ“˜

Notes

  • If your policies require you to rotate keys more often, you can always generate a new key.
  • If you want to pause using the API without deleting your account, you can revoke your API key.

Before you begin, sign up for a free account, or if you already have one, sign in.

The process of managing your API key can be divided into the following tasks:

  • Retrieve your API key: Go to the Dashboard page, and select the Copy icon to the right of the key to copy it to your clipboard.
  • Generate a new API key: Go to the Dashboard page, choose Settings from the sidebar, and then select the Regenerate Key button under the API Key section.
  • Revoke an API key: Go to the Dashboard page, choose Settings from the sidebar, and then select the Revoke Key button under the API Key section.

Making requests to the API

The example code in this section assumes the following:

  • Your API key is stored in a variable named API_KEY.
  • The URL of the API service is stored in a variable named API_URL. For details about retrieving the URL of the API service, see the Call an endpoint section.

The code below demonstrates creating a new index by calling the POST method of the /indexes endpoint. For each request, pass the x-api-key header parameter with the value of your API key.

# Declare the `headers` dictionary containing your API key
headers = {
    "x-api-key": API_KEY
}

INDEXES_URL = f"{API_URL}/indexes"
INDEX_NAME = "<YOUR_INDEX_NAME>" 
data = {
    "engines": [
      {
        "engine_name": "marengo2.5",
        "engine_options":  ["visual", "conversation", "text_in_video", "logo"]
      }
    ],
    "index_name": INDEX_NAME,
}
# Make a POST request to the `indexes` endpoint, passing the `x-api-key` header parameter
response = requests.post(INDEXES_URL, headers=headers, json=data)
print (f'Status code: {response.status_code}')
pprint (response.json())
// Declare the `headers` object containing your API key
const headers = {
  'x-api-key': API_KEY
}
 
const INDEXES_URL = `${API_URL}/indexes`
const INDEX_NAME = '<YOUR_INDEX_NAME>' 

// Make a POST request to the `indexes` endpoint, passing the `x-api-key` header parameter
const resp = await axios.post(
		INDEXES_URL,
		{
		'engines': [
      {
        'engine_name': 'marengo2.5',
        'engine_options': ['visual', 'conversation', 'text_in_video', 'logo']
      }

    ],
		'index_options': ['visual', 'conversation', 'text_in_video'],
		'index_name': INDEX_NAME
	},
	{ headers }
)
const { data: response } = resp;
console.log(`Status code: ${resp.status}`)
console.log(response)

If your API key is valid, the response should look similar to the following:

{
  "_id": "63fd8686e5857ca95a830ad1"
}

If your API key has expired or is invalid, the response should look similar to the following:

Status code: 401
{
  "code": "api_key_invalid",
  "message": "Provided API key is invalid. Please check your API key or generate a new one from the dashboard and try again."
}