We’ve changed our name! API.AI is now Dialogflow. Learn more here.

API Reference

Base URL

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

https://api.dialogflow.com/v1/

Authentication

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

Protocol Version

All Dialogflow requests require the versioning v parameter in the URL. For example, https://api.dialogflow.com/v1/query?v=20150910.

The different protocol versions you can use in your requests:

Protocol Version Description
20150910 This is the base protocol and is used in our one-click integrations.
20170712 This updated version uses the base protocol, but instead of @sys.number values being returned as strings, they're returned as numbers. This protocol is used in our test console, which is shown in the getting started guide.

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.

Elements

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

JSON

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

Example Unsuccessful Response

JSON

{
  "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 Dialogflow.

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.