Create Agentic App API

Back to API List

Provides an endpoint to create a new Agentic App.

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

Additional Request Headers

Fields	Description	Mandatory
accountid	Account 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 isn’t 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://<platform-domain.com>/api/public/apps/createApp' \ 
--header 'Content-Type: application/json' \ 
--header 'x-api-key: your-api-key' \ 
`--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": "[e-mail]"
    },
    "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	INSUFFICIENT_SCOPE	The API key does not have the required scope
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.