Intended audience: Partners using the AudioEye API
You can start integrating AudioEye® into your app or website as soon as your account has been created and your account manager has given you a log in to the portal:
- Retrieve your AudioEye API Key so that your API requests can be authenticated by Audioeye.
- Install an API client so that you can interact with the API
- Review the API documentation
- Test an API request to confirm that everything is working
Endpoints
Endpoint |
Name |
Description |
Gen 2 AudioEye API |
AudioEye’s modern, supported public API |
The latest version of AudioEye's endpoint documentation can be viewed on https://api.audioeye.io/openapi/#/.
Authentication
You can retrieve that API key needed to authenticate requests through the partner portal see Retrieving your API Key.
Include this key in your REST requests’ x-api-key header, per the included OpenAPI specification.
Because the AudioEye API requires authentication using a private API key, it is not well-suited for calling directly from an end-user’s browser, as this would leak your private credentials.These credentials grant access to functionality within your account; DO NOT share them, or embed them in a public webpage in such a way that the end-user’s browser loads them.
Instead, end-user requests should be proxied through your own servers, which are responsible for adding authentication, and potentially performing any persistence or logic needed to poll the API for score results.
Generating and Using an API Client
Since AudioEye delivers an OAS 3.0 document for its API, you can quickly generate an API client for your language of choice. Instructions and tools are available on the public OpenAPITools git repository on GitHub.
The Gen2 REST API accepts and returns JSON payloads. These payloads are documented using an OpenAPI document following the OpenAPI Specification (OAS):
“OAS defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without source code, documentation, or through network inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.”
Read more about the advantages of using OpenAPI on the OpenAPI Initiative website.
Request Rate Limiting
The AudioEye API imposes rate limits on callers. If you make too many requests per minute, per second, or per hour, responses will return with HTTP status code 429.
Specific rates are not publicly available. If you become rate limited but feel you have a good reason to maintain high request rates, please reach out to your point of contact at AudioEye or submit a helpdesk ticket.
Versioning and Resource Addressing
AudioEye APIs take the form:
GET https://api.audioeye.io/<version>/<resource>/<id>
Generally, all resources sharing a version are assumed to be compatible with each other.
Resources are never addressed as subresources, unless they are singleton instances, or virtual resources. E.g., the following route to fetch bar with barId == 2 is invalid:
GET https://api.audioeye.io/v20210831/foos/1/bars/2
Instead, you would just address bars directly:
GET https://api.audioeye.io/v20210831/bars/2
Testing the API
To check that the integration is working please make the following requests using our test API key:
Test API Key
bf7d655a-4368-4827-abe7-8a5bcbd1be13
-
CreateSite
curl --location --request POST 'https://api.audioeye.io/v20210921/site' \ --header 'api-key: bf7d655a-4368-4827-abe7-8a5bcbd1be13' \ --header 'Content-Type: application/json' \ --data-raw '{ "url": "https://www.example.com", "endCustomer": "Company No 1", "externalSiteId": "company no 1 identifier", "config": { "ctaColor": "#FF0000", "ctaLocation": "right-mid-lower", "toolbarTheme": "light" } }'
- This will create a site for the URL specified, and will return a site object containing the siteID and installScript and HashId required for installation
- Optional: If at this point you want to test AudioEye on a site you can use this information to install. See instructions for installing directly into a websites footer or for installing with google tag manager
-
GetAllSites
curl --location --request GET 'https://api.audioeye.io/v20210921/site?sortBy=domain' \ --header 'api-key: bf7d655a-4368-4827-abe7-8a5bcbd1be13'
- This will return a list of all sites for your account and should now include the site you just provisioned.
-
CancelSite
curl --location --request DELETE 'https://api.audioeye.io/v20210921/site/<SITE_ID>' \ --header 'api-key: bf7d655a-4368-4827-abe7-8a5bcbd1be13'
- Insert the SiteId returned by the first call into the example above.
- This will cancel the test site that you just created.
- Note: if you went through the process of installing AudioEye on a test site please be sure that testing is complete as cancelling will stop delivery of AudioEyes services for that site.