Skip to content

Create Agentic App API

Provides an endpoint to create a new Agentic App.

Method POST
Endpoint https://<agent-platform-env>.<domain>.com/public/api/v1/apps/createApp
Content-type application/json
Authorization Header x-api-key: <API-KEY>

Additional Request Headers

Fields Description Mandatory
accountid Accound Id to be used for app creation. Yes
userid Unique user Id to be used for app creation. Yes

Request Parameters

Fields Description Mandatory
name Unique name of the app to be created Yes
description Brief description of the purpose of the app. Yes
appIcon Details of the icon to be used for the app. Use the following fields to describe the app icon. If this field is not provided, a random icon is used for the app.
  • name (required, string): Identifier for the logo to be used as the app icon; allowed values are “logo1-logo10”.
  • type(required, string): Must always be set to "logo".
  • color(required, string): Hexadecimal color code for the icon. Example: #RRGGBB.
No

Sample Request

Example Curl Command

curl --location 'https://&lt;agent-platform-env>.&lt;domain>.com/public/api/v1/apps/createApp' \ 
--header 'Content-Type: application/json' \ 
--header 'x-api-key: your-api-key' \ 
</code>--header 'accountid: axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx45' \ 
--header 'userid: uxxxxxxxxxxxxxxxxxxx' \ 
--header 'authorization: bearer xxxxxxxxxxxxxxxxxxx' \ 
--data '{ \
    "name": "Calendar Assistant", \
    "description": "Calendar Assistant app for calendar management." \
}'

Response

On successful creation of the app, response in the following format is received.

Sample response - Success (201)

{
  "success": true,
  "data": {
    "appId": "aa-xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "name": "Calendar Assistant",
    "description": "Calendar Assistant app for calendar management",
    "appIcon": {
      "name": "logo5",
      "type": "logo",
      "color": "#B2CCFF"
    },
    "status": "IN_DEVELOPMENT",
    "type": "Agentic",
    "accountId": "axxxxxxxxxxxxxx",
    "createdBy": {
      "id": "uxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "emailId": "john@example.com"
    },
    "createdAt": "2025-08-18T06:58:21.313Z",
  },
  "meta": {
    "requestId": "req_12345678",
    "timestamp": "2025-08-18T06:58:21.313Z"
  }
}

Sample response - Error

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message",
    "details": {} // Optional additional error details
  },
  "meta": {
    "requestId": "req_1234567890",
    "timestamp": "2025-08-18T06:58:21.313Z"
  }
}

Where ERROR_CODE is one of the following.

HTTP Status Error Code Description
400 VALIDATION_ERROR One or more request parameters are invalid.
400 INVALID_APP_ICON App icon name, type, or color is invalid. When this error occurs, a random icon is added to the app.
400 INVALID_NAME_FORMAT App name contains special characters or an invalid format.
401 UNAUTHORIZED API key is missing, invalid, or expired.
401 API_KEY_EXPIRED The provided API key is no longer valid.
401 API_KEY_REVOKED The API key has been manually revoked.
403 ACCOUNT_ACCESS_DENIED The user does not have access to the account.
403 USER_PERMISSION_DENIED User does not have permission to create apps.
409 RESOURCE_CONFLICT An app with this name already exists in the workspace.
500 INTERNAL_ERROR Unexpected server error during processing.
503 SERVICE_UNAVAILABLE The API service is temporarily down for maintenance.