Eggplant DAI Model Execution Endpoints

New Feature

Admin users can now generate API clients with a client_id and client_secret through the DAI UI.

Eggplant DAI uses the OAuth 2.0 authentication protocol with the client_credentials grant type in order to enable access to REST API. This page explains how you can generate an API access key and secret, exchange those for a token, and use the token to call the remaining DAI REST API. For example, it can be used to call the Execution API which lets you run your models and interact with execution controls like Starting an Execution via REST. These services allow you to integrate this behavior into your DevOps toolchains.

Getting Started

The REST API is ready and available to use as soon as you finish installing Eggplant DAI. To gain access to the API, you need to:

• Find out where to send your credentials.
• Generate API client credentials via the user interface using the new experience.
• Acquire an access token to authenticate with the DAI REST API.

As soon as you acquire an access token, you can start to test models with all the options that are available in the Eggplant DAI web app. After a run starts, you can leave it to process. An ID is returned which you can use to check the progress of a run. In addition, you can abort a run.

Generate Your API Client Credentials

Admin users can create API clients. The created clients have equivalent permissions to an admin user and can do almost everything an admin user can, except create more API clients.

To create an API client:

1. Navigate to System > API Access
2. Click Add New.
3. Add a name and description for your credentials.
4. Click Create.
5. A prompt appears asking you to download a file. Click Download and store the credentials .csv file in a safe place.

You can now use the client_id, client_secret, and token_url from your credentials file to Acquire an access token.

Security Note

Treat these credentials as you would a password. Store them securely and do not share them. If API credentials are ever misplaced, leaked, or forgotten, they can be revoked or regenerated through the API Access interface.

Where to send credentials

If you have downloaded an API Client .csv file or an exection environment .ini, you can find the token_url value in the files.

You can also construct the token_url value to authenticate against by following these steps on any DAI instance:

1. Navigate to the DAI login page.
2. Copy the value from the address bar, login_url in following example.
3. Replace /auth and everything that follows it with /token.

Example:

login_url=http://localhost:8000/auth/realms/eggplant/protocol/openid-connect/auth?client_id=...
token_url=http://localhost:8000/auth/realms/eggplant/protocol/openid-connect/token

The realm name is dynamic if you are an Eggplant Cloud customer. We will be denoting that with \{realm\} for the remainder of the documentation and should be replaced with your custom value prior to usage.

Acquire an Access Token and Authenticate

Use the credentials from the previous steps to obtain an access token from the API, and to authenticate.

Send a request to the token_url.

POST > http://localhost:8000/auth/realms/\{realm\}/protocol/openid-connect/token
Content-Type:application/x-www-form-urlencoded

Request body:

{
    "grant_type": "client_credentials",
    "client_id":"{your client identifier}",
    "client_secret":"{your client secret}",
}

Example successful response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "4fcb07e1-eb73-42e7-b369-26c8db036f90",
  "scope": "email template:dai:agents profile"
}

The access token lasts for 5 minutes. To maintain access to the API, you need to check when the access token expires, resend your credentials to get a new token before the original one expires, or when a 401 response is returned.

Available Methods

Use the following HTTP methods to send requests to the Eggplant DAI API endpoints:

• GET for requesting data
• POST for creating new records
• PUT for updating records
• DELETE for deleting records

This table includes links to descriptions of the individual API methods for starting, monitoring, and stopping a model run.

Title	URL	HTTP Method	Description
NEW Auth Method	http://localhost:8000/auth/realms/{realm}/protocol/openid-connect/token	POST	The token_url endpoint returns an access token for the API.
NEW Start Model Execution	http://localhost:8000/execution_service/api/v1/executions	POST	Executes a model run.
List Run Details	http://localhost:8000/ai/runs	GET	Returns details of the model run in progress.
Get a List of all Agents	http://localhost:8000/ai/agents	POST	Returns details of all hosted agents.
NEW Abort Model Execution	http://localhost:8000/execution_service/api/v1/executions/{execution_status_id}	DELETE	Stops the model run.

For more detailed analysis of model runs, such as viewing run reports, viewing coverage reports, analyzing test cases, and so on see our Swagger docs.