API Reference

Base URL

All the URLs referenced in the documentation have the following base:



Each API request requires authentication to identify the agent that is responsible for making the request. Authentication is provided through an access token.

There are two access tokens for each agent. The developer access token is used for managing entities and intents, and the client access token is used for making queries. The client access token may not be as secure because it may be stored as part of the app, and it may potentially be discovered. There is a way to regenerate the client key if it is compromised.

Obtaining Access Tokens

To obtain the access token, choose the required agent from the Agents dropdown and click the Settings icon settings next to it.

The agent's settings will be opened. In the API keys section you'll find two access tokens that you will use for authentication.

Using Access Tokens

For each API request, include this HTTP header:

Authorization with the value Bearer {access_token}.

For example:

Authorization: Bearer YOUR_ACCESS_TOKEN


All API.AI requests should be made with the versioning v parameter in the URL.

The approach is similar to the Foursquare versioning policy. So, for example, the query requests should be made to the endpoint /query?v=20150910.

The v parameter is formatted as YYYYMMDD.

The parameter indicates that you are ready to handle API version as of the specified date.


API.AI supports the following languages:

Language Language Tag
Brazilian Portuguese pt-BR
Chinese (Cantonese) zh-HK
Chinese (Simplified) zh-CN
Chinese (Traditional) zh-TW
English en
Dutch nl
French fr
German de
Italian it
Japanese ja
Korean ko
Portuguese pt
Russian ru
Spanish es
Ukrainian uk

Language tag follows the HTTP/1.1 specification, section 3.10.

Status Object

The status object is returned with every request and indicates if the request was successful. If it is not successful, error information is included. See Status and Error Codes for more information on the returned errors.


The following elements are in the status object:

Name Type Description
status Contains data on how the request succeeded or failed.
code Integer HTTP status code
errorType String Text description of error, or "success" if no error.
errorId String ID of the error. Optionally returned if the request failed.
errorDetails String Text details of the error. Only returned if the request failed.

Example Successful Response


  "status": {
    "code": 200,
    "errorType": "success"

Example Unsuccessful Response


  "status": {
    "code": 400,
    "errorType": "bad_request",
    "errorDetails": "Json request query property is missing"

Status and Error Codes

The following table describes status and error codes returned by API.AI.

In the status object, the code field contains the status code and the errorType field contains the error type.

Status Code Error Type Description
200 success Request was successful.
200 deprecated A resource is deprecated and will be removed in the future.
400 bad_request Some required parameter is missing or has the wrong value.
Details will be in the errorDetails field.
401 unauthorized Internal authorization failed. It might mean missing or wrong credentials.
404 not_found URI is not valid or the resource ID does not correspond to an existing resource.
405 not_allowed HTTP method not allowed, such as attempting to use a POST request with an endpoint that only accepts GET requests, or vice versa.
406 not_acceptable Can be returned if uploaded files have some errors.
409 conflict The request could not be completed due to a conflict with the current state of the resource. This code is only returned in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. For example, deleting an entity that is used in an intent will return this error.
429 too_many_requests Too many requests were sent in the short amount of time.