Skip to main content

Using AppDirect AI APIs

As APIs are built using REST principles, each API has a predictable resource-oriented URL, accepts form-encoded request bodies, returns responses in JSON format, and utilizes standard HTTP response codes, authentication mechanisms, and verbs.


API authentication is the process of confirming the identity of a user making an API request, and it is a critical component of API security. The main goal of the authentication mechanism is to protect sensitive data and ensure that the APIs are not misused.

The AppDirect AI APIs use keys to authenticate requests. An API key is a unique identifier that is provided to registered users to control usage and monitor access.

The API key must be sent with every request as a request header.

Getting Started

This article provides instructions on how to get started with the AppDirect REST APIs using cURL.

Understanding elements of an API request

This section describes the elements that are required to make an API request:

  • HTTP method

    The HTTP method of an endpoint defines the type of action performed on a given resource. Following are some of the commonly used methods:

    • GET - Used to retrieve resource details.
    • POST - Used for new resources.
    • PUT - Used to update an existing resource.
    • DELETE - Used to delete resources.
    • PATCH - Used to make a partial update on a resource.

    The reference documentation provides the HTTP method for every endpoint.

  • Path

    Each API endpoint has a path. The reference documentation provides a path for every endpoint. For example, the path for the “Get AI Details” API is /api/v1/ai/{aiId}. The curly brackets {} in a path represent path parameters that you need to specify. In this example, replace aiId with the identifier of the AI whose details are to be retrieved.

  • Headers

    Headers are a part of the HTTP requests and responses that include metadata in key-value pairs. They can be used for defining caching behavior, enabling authentication, and handling session state.

    HTTP headers significantly influence server and client behavior throughout the request and response cycle. Request headers (sent by the client) provide information and instructions about the requested resource, while response headers (sent by the server) provide metadata, instructions, and additional information about the response.

    Following are some of the most commonly used request headers:

    • Accept

      The Accept header specifies the media types the client can accept from the server, such as application/json or text/html, enabling the server to send the appropriate resource representation.

    • User-Agent

      The User-Agent header identifies the web browser or client application that is making the request, allowing the server to customize its response to the client.

    • X-Authorization

      The Authorization header sends client credentials to the server when accessing protected resources. For example, the client might include a JSON Web Token (JWT), which the server verifies before returning the requested resource.

    • Content-Type

      The Content-Type header indicates the media type of the content in the request body. For example, Content-Type:application/json indicates that the request body contains the JSON data which aids the server in interpreting and processing the payload.

    • Cookie

      The Cookie header allows clients to send stored cookies back to the server, enabling the server to associate requests with specific users or sessions for personalized experiences.

    Following are some of the most commonly used response headers:

    • Content-Type

      The Content-Type response header indicates the type of data that the server is sending to the client. It typically includes media type (such as text/html, application/json) and any optional parameters.

    • Cache-Control

      The Cache-Control header regulates caching behavior in the client’s browser or intermediate caches. It defines the response cache duration, expiration date, and revalidation.

    • Server

      The Server header contains details about the technology stack of the server that generated the response along with its name and version.

    • Set-Cookie

      The Set-Cookie header instructs clients to store a cookie with specific attributes, enabling stateful communication and personalized experiences in subsequent requests.

    • Content-Length

      The Content-Length header in the response body allows clients to anticipate data size. This improves performance as it allows clients to plan efficient memory allocation and data processing in advance.

  • Authentication

    Every AppDirect REST API endpoint requires authentication. To authenticate your request, you must provide an authentication token with the necessary scopes or permissions.

  • Parameters

    API methods often require or allow you to send additional information in parameters with your request. Following are some of the different types of parameters:

    • Path parameters

      Path parameters are sent along with a URL that points to a specific resource. They are separated from a URL using a backward slash (‘/’) and are required.

    • Body parameters

      Body parameters enable you to send additional data to an API, which can be optional or required depending on the endpoint.

    • Query parameters

      Query parameters enable you to manage what data is returned for a request. They are separated using a question mark (‘?’) and are usually optional.

Making a request

This section describes how to make an authenticated request to the AppDirect REST APIs using cURL:

  1. Install cURL

    Install cURL before you proceed with the next steps. For more information, refer to cURL documentation.

  2. Selecting an endpoint for your request

    • Select an endpoint you want to make a request to. You can refer to [AppDirect AI API ( to discover the endpoints.

    • Identify the HTTP method and path of the endpoint. You will send these with your request.

      For example, the “Create a new chat session for the AI” endpoint uses the HTTP method POST and path /api/v1/ai/{aiId}/chats.

    • Identify the required parameters. For example, the “Create a new chat session for the AI" endpoint uses the path parameter {aiId} and body parameter name. Replace both parameters with the desired values.

  3. Getting API key for authentication

    Create an access token to authenticate your request. You will need to send this token in an Authorization header with your request. To generate an API key, refer to API Keys.

  4. Preparing a cURL request

    You should use the curl command to make your request. Include the following options and values in your request:

    • --request or -X followed by the HTTP method as the value.

    • --url followed by a full path as the value. The full URL must include the base URL for the AppDirect REST API ( and the path of the endpoint. For example, the url for the “Create a new chat session for the AI” will look like this:{aiId}/chats.

    • --header or -H:

      • Accept: Pass the media type in an Accept header.
      • ** X-AppDirect-Api-Version:** Pass the API version in a X-AppDirect-Api-Version header.
      • X-Authorization: Pass your authentication token in an Authorization header.
    • --data or -d followed by any body parameters within a JSON object.

    Following is the example request for “Create a new chat session for the AI” endpoint:

    curl --request POST \
    --url “” \
    --header “Accept: application/json \
    --header “X-AppDirect-Api-Version: 1” \
    --header “X-Authorization: 123458acfgtkdasdiggd123hhhhd” \
    --data ‘{
    “name”: “Chat session 1”
  5. Understanding the response

    Every API request will return the response status code (standard HTTP response code), response headers, and potentially a response body.

    Following is the example response for “Create a new chat session for the AI” endpoint:

    "id": "string",
    "createdAt": "2024-01-24T15:03:20.270Z",
    "updatedAt": "2024-01-24T15:03:20.270Z",
    "name": "string",
    "userId": "string",
    "pinPosition": 0,
    "ai": {
    "id": "string",
    "name": "string",
    "src": "string",
    "description": "string",
    "userId": "string",
    "userName": "string"

Was this page helpful?