Overview

The Aura API allows you to programmatically perform actions on your Aura instances without the need to log in to the Console.

A complete list of the available endpoints can be seen and tested in the API Specification.

Before using the API, you must follow the steps outlined in Authentication to create your credentials and authenticate your requests.

API URL

Base URL

The base URL for the Aura API is https://api.neo4j.io.

Versioning

The current version of the Aura API is v1

As and when we need to introduce breaking changes to the API, we will release a new version to ensure we do not break existing integrations.

In the future, as we deprecate legacy API versions, we will provide notice. Once the expiry date for a deprecated version has passed, that version will no longer be available.

Example request

The following example shows how to use the base URL and versioning to make a request to the API:

GET https://api.neo4j.io/v1/instances

Retries

In the event of 5xx server error responses, you may consider retrying the request after a delay if it is safe to do so. The response may include a Retry-After header with a suggestion of a suitable minimum delay before attempting to retry.

The global rate limit for all requests is 125 requests per minute.

You should consider your use of the rate limit before attempting to retry, and it is recommended that you use an exponential backoff delay with a limited number of retries before giving up.

A request is only guaranteed to be safe to retry if it uses an idempotent HTTP method, such as GET. If, for example, you retry a request for creating an instance, you may end up with duplicate instances and end up being charged extra as a result.

In the case of 429 Too Many Requests, we would recommend slowing down the rate of all requests sent from your client application and consider retrying with a suitable minimum delay and backoff strategy.

For other 4xx client error responses, you should not resend such requests without first correcting them.

Excessive token requests may cause inefficiencies or rate-limiting.

You can optimize your API usage by following these steps:

  • Retrieve the token once per hour: As tokens remain valid for an hour, reduce the frequency of token requests and reuse the same token for multiple API calls.

  • Implement token caching: Store the token securely within your system to reuse it for subsequent requests during its validity period, minimizing unnecessary calls to the endpoint.

Request tracing and troubleshooting

An X-Request-Id response header is returned with each request and can be used for troubleshooting.

The value of this header contains a unique ID that can be used to track the journey of a request.

If you run into any issues with a particular request, you can raise a support ticket and provide the X-Request-Id.