APIs - Kore.ai Docs

Use the AI for Work public APIs to send notifications, retrieve audit logs, and retrieve trace logs from your own applications and reporting tools.

API	Description
Notify API	Send interactive notifications with action buttons to users through an agent.
Audit Log API	Retrieve administrative and user activity records for reporting, SIEM integration, or compliance workflows.
Trace Log API	Retrieve query-level trace log records, including response time, token consumption, models, and the source that answered each query.

The sample requests and responses on this page use placeholder values in place of real data:

Values in double braces, such as {{host}} and {{PersonalToken}}, are placeholders that you replace with your own values.
IDs keep their prefix, if any, and replace the remaining characters with x. For example, u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx is a user ID and xxxxxxxxxxxxxxxxxxxxxxxx is a record ID.
Names and email addresses are fictitious, such as John Doe and john.doe@example.com.

Authentication

All AI for Work public API requests go to https://{{host}}/api/public/, where {{host}} is the AI for Work environment URL for your account. Each API uses one of two credentials.

API	Credential	Header
Notify API	The agent access token from the agent settings page	`authorization`
Audit Log API	A personal api key generated by an Admin	`auth`
Trace Log API	A personal api key generated by an Admin	`auth`

Generate a Personal API Key

The Audit Log API and the Trace Log API accept only a Personal API Key that an admin generates. Keys generated by users without the Admin role do not work with these APIs. To generate a Personal API Key:

Sign in to AI for Work.
Open the profile menu and select Personal API Key.
Copy the generated key and store it securely.

Notify API

The Notify API sends interactive notifications to users. Notifications can include customizable response options and action buttons. To know how agents pause and resume conversations around alerts, see Handling Alert Tasks.

Applicable only for Bot, Autonomous, and Workflow Agents.

Endpoint Reference

Method: POST
Endpoint: https://{{host}}/api/public/agents/{agentId}/notify
Content-Type: application/json
Authorization: authorization: {{AgentAccessToken}} — The access token obtained from the agent settings page.
API Scope: Notification

Path Parameters

Parameter	Required/Optional	Description
host	Required	Environment URL, for example `https://work.example.ai`
agentId	Required	The unique identifier of the agent. Replace `{agentId}` in the URL with the actual agent ID, obtained from the Post URL field while creating an agent.

Request Body Parameters

Parameter	Type	Required/Optional	Description
to	string	Required	Email address of the application user (single recipient).
message	object	Required	Contains notification title and body text.
message.title	string	Required	Notification title.
message.body	string	Required	Notification message body.
category	string	Optional	Category of the notification. Defaults to `Agent`.
actions	array	Optional	Array of interactive response buttons. Defaults to an empty array, which sends the notification without buttons.
actions[].title	string	Optional	Button label that the user sees.
actions[].type	string	Optional	Action type, for example, `"postback"`.
actions[].utterance	string	Optional	Text sent to the agent when the user selects the button.
actions[].payload	object	Optional	Custom data passed to the agent with the action, for tracking and response handling.

The API validates only to and message. It does not validate the properties inside actions, so check that each button includes the fields your agent needs to handle the response.

Sample Request

curl --location --request POST 'https://{{host}}/api/public/agents/ag-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/notify' \
--header 'authorization: {{AgentAccessToken}}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "to": "john.doe@example.com",
    "message": {
        "title": "Agent Update",
        "body": "Notification description"
    },
    "category": "agent",
    "actions": [
        {
            "title": "LaptopRequest",
            "type": "postback",
            "utterance": "submit action 1",
            "payload": {
                "transactionId": "tx-xxxxxxxx",
                "sessionId": "s-xxxxxxxx",
                "event": "laptopRequest"
            }
        }
    ]
}'

Sample Response

{
    "notify": "success"
}

Key Points

The to email address must belong to a valid application user.
The to key accepts a single email address in the initial implementation.
Use custom payload data for tracking and response handling.
Include actions in the request payload to present users with interactive buttons. If you omit actions, the user receives the notification without buttons.

Audit Log API

The Audit Log API retrieves log data programmatically for custom reporting, SIEM integration, or compliance workflows. For what the audit log records and where to view it in the product, see Audit Log.

Endpoint Reference

Method: GET
Endpoint: https://{{host}}/api/public/auditlogs
Content-Type: application/json
Authorization: auth: {{PersonalToken}} — A Personal API Key generated by an Admin. See Generate a Personal API Key.

Query Parameters

The startTime and endTime parameters are required. The API returns HTTP 400 if either is missing. All other parameters are optional; combine them to filter results.

Parameter	Required/Optional	Description	Example
`startTime`	Required	Start of the time window, as an ISO 8601 timestamp in UTC.	`startTime=2024-12-01T00:00:00Z`
`endTime`	Required	End of the time window, as an ISO 8601 timestamp in UTC.	`endTime=2024-12-05T23:59:59Z`
`entity`	Optional	Type of resource to filter by. Case-sensitive. See Supported Entities and Actions.	`entity=usergroup`
`entityId`	Optional	Unique ID of a specific resource instance.	`entityId=xxxxxxxxxxxxxxxxxxxxxxxx`
`userId`	Optional	Filter by the user who performed the action.	`userId=u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
`emailId`	Optional	Filter by the email address of the acting user.	`emailId=john.doe@example.com`
`action`	Optional	Type of action, in uppercase. See Supported Entities and Actions.	`action=CREATE`

Supported Entities and Actions

Entity values are case-sensitive. Use them exactly as shown, for example, agent, not Agent. Action values are uppercase.

Entity	Supported Actions
`workspace`	CREATE, UPDATE, DELETE
`usergroup`	CREATE, UPDATE, DELETE
`agent`	CREATE, UPDATE, DELETE, PUBLISH, UNPUBLISH, EXPORT
`role`	CREATE, UPDATE, DELETE, PUBLISH, UNPUBLISH
`userenrollment`	UPDATE, DELETE
`useraction`	CREATE, UPDATE, DELETE
`ssostatus`	UPDATE
`serviceaccount`	CREATE, UPDATE, DELETE
`llmintegrations`	CREATE, UPDATE, DELETE
`domains`	CREATE, UPDATE, DELETE
`ratelimits`	CREATE, UPDATE, DELETE
`nlprules`	CREATE, UPDATE, DELETE
`enterprisedirectory`	CREATE, UPDATE, DELETE
`emailnotificationpreferences`	CREATE, UPDATE, DELETE
`piiRule`	CREATE, UPDATE, DELETE
`guardrail`	UPDATE
`orchestrator`	UPDATE
`dataretention`	UPDATE
`scheduler`	UPDATE
`useragentscheduler`	CREATE, UPDATE, DELETE
`encryptionkey`	CREATE, UPDATE, DELETE
`mcpconnection`	CREATE, UPDATE, DELETE
`mcpserver`	CREATE, UPDATE, PUBLISH, DELETE
`attachmentsettings`	UPDATE
`projectssettings`	UPDATE
`project`	CREATE, UPDATE, DELETE
`emailtemplates`	UPDATE
`employeelookupsettings`	UPDATE
`personalizationandmemorysettings`	UPDATE
`feedbacknotificationsettings`	UPDATE
`userMemory`	CREATE, UPDATE, CLEAR, DELETE
`featureonboarding`	UPDATE
`enterprisesearch`	UPDATE
`prebuilttools`	CREATE, UPDATE, DELETE
`channels`	CREATE, UPDATE, DELETE
`announcements`	CREATE, UPDATE, PUBLISH, UNPUBLISH, DELETE

Sample Request

curl --location 'https://{{host}}/api/public/auditlogs?startTime=2024-12-01T23%3A59%3A59Z&endTime=2024-12-12T23%3A59%3A59Z&entity=nlprules&action=UPDATE&emailId=john.doe%40example.com' \
--header 'auth: {{PersonalToken}}'

Sample Response

{
  "logs": [
    {
      "parentIds": [],
      "_id": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "entity": "nlprules",
      "action": "update",
      "userId": "u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "accountId": "ac-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "entityId": "xxxxxxxxxxxxxxxxxxxxxxxx",
      "delta": {
        "from": {},
        "to": {
          "name": "Answer rule - 67"
        }
      },
      "htmlText": "Update business rule <b>Answer rule - 67</b>",
      "userName": "John Doe",
      "emailId": "john.doe@example.com",
      "keywords": "",
      "cOn": "2024-12-10T14:27:20.286Z",
      "__v": 0
    }
  ]
}

Trace Log API

The Trace Log API retrieves trace log records for a specified date range. Each record captures a single user request and includes response time, token consumption, the models and LLM events involved, and the source that answered the request, such as an agent, a project, an attachment, or an AI model. Use this API to pull usage, latency, and token data into your own reporting tools, data warehouses, or internal dashboards. For what a trace log shows in the product, see Trace Logs.

Endpoint Reference

Method: GET
Endpoint: https://{{host}}/api/public/analytics
Content-Type: application/json
Authorization: auth: {{PersonalToken}} — A Personal API Key generated by an Admin. See Generate a Personal API Key.
Required Role: Admin

Headers

Header	Value	Description
`auth`	`{{PersonalToken}}`	The Personal API Key generated from the profile menu.
`accept`	`application/json, text/plain, /`	Accepted response content types.
`content-type`	`application/json`	Request content type.

Query Parameters

All query parameters are optional.

Parameter	Required/Optional	Type	Description
`startDate`	Optional	Number	Start of the date range, as a Unix timestamp in milliseconds.
`endDate`	Optional	Number	End of the date range, as a Unix timestamp in milliseconds.
`agentId`	Optional	String	Returns records for the specified agent only.
`userId`	Optional	String	Returns records for the specified user only.

Date range behavior

Parameters sent	Date range returned
`startDate` and `endDate`	The specified range.
`startDate` only	A one-day range that starts at `startDate`.
Neither	Approximately the previous month.

Trace log records include the questions that users submit, which can contain personal or confidential information. Store and share the response according to your organization’s data protection policies.

Sample Request

curl --location \
  'https://{{host}}/api/public/analytics?startDate=1744108557559&endDate=1744194957559' \
  --header 'accept: application/json, text/plain, */*' \
  --header 'content-type: application/json' \
  --header 'auth: {{PersonalToken}}'

Sample Response

The following sample shows a request that an agent answered. The agent made an API call to an external agent platform and received an asynchronous response.

{
    "analytics": [
        {
            "accountId": "ac-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "msgId": "xxxxxxxxxxxxxxxxxxxxxxxx",
            "boardId": "i-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "cOn": "2026-10-12T14:22:40.000Z",
            "channel": "web",
            "deviceInfo": {},
            "isPersonal": false,
            "lMod": "2026-10-12T14:27:54.000Z",
            "question": "Is the alert true?",
            "reqStatus": "in-progress",
            "requestId": "#xxxxxxxxx",
            "respContext": {
                "type": "agent",
                "sources": [
                    {
                        "sourceId": "ag-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                        "name": "IT Operations Agent",
                        "type": "aAAgent",
                        "icon": "https://{{staticHost}}/kora/icons/lib/announcement/black.svg",
                        "darkIcon": "https://{{staticHost}}/kora/icons/dark/lib/announcement/black.svg",
                        "isFallback": false,
                        "isPersonal": false,
                        "ownerId": "u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
                    }
                ]
            },
            "totalReqTokens": 20427,
            "totalRespTime": 350955,
            "totalRespTokens": 761,
            "traceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "traceIds": [
                "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
            ],
            "trigger": "userInitiated",
            "userId": "u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "wsId": "ws-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "id": "xxxxxxxxxxxxxxxxxxxxxxxx",
            "timestamp": "2026-10-12T14:22:40.000Z",
            "llmStats": [
                {
                    "e": "Guardrail Validation",
                    "eType": "llm",
                    "m": "gpt-5.2",
                    "ts": "2026-10-12T14:22:40.359Z",
                    "rt": 1552,
                    "llmEvent": "Guardrail Validation",
                    "ipT": 648,
                    "opT": 47
                },
                {
                    "e": "ABL Agent API Request",
                    "eType": "api",
                    "ts": "2026-10-12T14:23:18.044Z",
                    "rt": 36056,
                    "llmEvent": "AblAgentResponse",
                    "url": "https://{{agentPlatformHost}}/api/v1/channels/ai4w/ai4w_c_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/message"
                },
                {
                    "e": "ABL Agent Async Response",
                    "eType": "api",
                    "m": "GPT-4.1",
                    "ts": "2026-10-12T14:27:54.901Z",
                    "rt": 312946,
                    "llmEvent": "AblAgentAsyncResponse",
                    "ipT": 19779,
                    "opT": 714
                }
            ]
        }
    ]
}

Response Reference

The API returns all trace log records in the selected date range in a single response. The API does not support pagination. Top-level response

Parameter	Type	Description
`analytics`	Array of objects	The trace log records that match the requested date range.

Trace log record Each object in the analytics array contains the following fields.

Parameter	Type	Description
`id`	String	Unique identifier for the record.
`accountId`	String	Unique identifier for the account or tenant.
`userId`	String	Unique identifier for the user who made the request.
`wsId`	String	Unique identifier for the workspace.
`boardId`	String	Unique identifier for the conversation (board) that contains the request.
`msgId`	String	Unique identifier for the message.
`requestId`	String	Short request identifier, prefixed with `#`.
`traceId`	String	Unique identifier for the request trace.
`traceIds`	Array of strings	All trace identifiers associated with the request.
`question`	String	The query or request the user submitted.
`channel`	String	The platform or medium through which the user made the request, for example, `web`.
`trigger`	String	How the request started, for example, `userInitiated`.
`reqStatus`	String	The current status of the request, for example, `completed` or `in-progress`.
`isPersonal`	Boolean	Indicates whether the request used a personal resource.
`deviceInfo`	Object	Details about the device from which the user made the request. Empty when no device details are available.
`respContext`	Object	The source that answered the request, such as an agent, a project, an attachment, or an AI model. See Response context object.
`llmStats`	Array of objects	Events describing each stage of request processing, such as guardrail validation, LLM calls, and agent API calls. See LLM event object.
`totalReqTokens`	Number	Total number of tokens used in the request.
`totalRespTokens`	Number	Total number of tokens generated in the response.
`totalRespTime`	Number	Total time taken to process and return the response, in milliseconds.
`cOn`	String	Time when the platform created the record, as an ISO 8601 timestamp in UTC.
`timestamp`	String	Time when the platform processed the request, as an ISO 8601 timestamp in UTC.
`lMod`	String	Time of the last modification to the record, as an ISO 8601 timestamp in UTC.

The agentInfo field is deprecated and no longer appears in trace log records. To identify the agent that answered a request, use respContext. When respContext.type is agent, respContext.sources[].sourceId contains the agent ID and respContext.sources[].name contains the agent name.

Response context object The respContext object identifies the source that answered the request.

Parameter	Type	Description
`type`	String	The type of source that answered the request: `agent`, `project`, `attachment`, or `llm`.
`sources`	Array of objects	The sources used to answer the request.
`sources[].sourceId`	String	Unique identifier for the source, such as an agent ID, a project ID, or an attachment ID. The value is `llm` for an AI model.
`sources[].name`	String	Display name of the source.
`sources[].type`	String	The source subtype, for example, `folder` for a project or `attachment` for an attachment.
`sources[].icon`	String	URL of the source icon for the light theme. Agent sources only.
`sources[].darkIcon`	String	URL of the source icon for the dark theme. Agent sources only.
`sources[].isFallback`	Boolean	Indicates whether the platform used the source as a fallback.
`sources[].isPersonal`	Boolean	Indicates whether the source is a personal resource of the user.
`sources[].ownerId`	String	Unique identifier for the user who owns the source. Agent sources only.
`sources[]._id`	String	Unique identifier for the source entry in the record.

The following examples show respContext for each source type.

"respContext": {
    "type": "agent",
    "sources": [
        {
            "sourceId": "ag-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "name": "Work",
            "type": "work",
            "icon": "https://{{staticHost}}/kora/icons/integrations/r/32/default.svg",
            "darkIcon": "https://{{staticHost}}/kora/icons/dark/integrations/r/32/default.svg",
            "isFallback": true,
            "isPersonal": false,
            "ownerId": "u-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "_id": "xxxxxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

"respContext": {
    "type": "project",
    "sources": [
        {
            "sourceId": "i-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
            "name": "HR Policies",
            "type": "folder",
            "isFallback": false,
            "isPersonal": false,
            "_id": "xxxxxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

"respContext": {
    "type": "attachment",
    "sources": [
        {
            "sourceId": "xxxxxxxxxxxxxxxxxxxxxxxx",
            "name": "Travel-Policy.pdf",
            "type": "attachment",
            "isFallback": false,
            "isPersonal": false,
            "_id": "xxxxxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

"respContext": {
    "type": "llm",
    "sources": [
        {
            "sourceId": "llm",
            "name": "LLM",
            "type": "llm",
            "isFallback": false,
            "isPersonal": false,
            "_id": "xxxxxxxxxxxxxxxxxxxxxxxx"
        }
    ]
}

LLM event object Each object in the llmStats array contains the following fields. Some fields apply only to certain event types.

Parameter	Type	Description
`e`	String	The event name, for example, `Guardrail Validation` or `ABL Agent API Request`.
`eType`	String	The event type: `llm` for a model call or `api` for an API call.
`llmEvent`	String	The internal event identifier, for example, `Guardrail Validation` or `AblAgentResponse`.
`m`	String	The LLM model used for the event. Appears only for events that call a model.
`ts`	String	Time when the platform logged the event, as an ISO 8601 timestamp in UTC.
`rt`	Number	Response time for the event, in milliseconds.
`ipT`	Number	Number of input tokens sent to the model for the event. Appears only for events that call a model.
`opT`	Number	Number of output tokens the model generated for the event. Appears only for events that call a model.
`url`	String	The endpoint that the platform called. Appears only for `api` events that call an external service.

​Authentication

​Generate a Personal API Key

​Notify API

​Endpoint Reference

​Path Parameters

​Request Body Parameters

​Sample Request

​Sample Response

​Key Points

​Audit Log API

​Endpoint Reference

​Query Parameters

​Supported Entities and Actions

​Sample Request

​Sample Response

​Trace Log API

​Endpoint Reference

​Headers

​Query Parameters

​Sample Request

​Sample Response

​Response Reference

Authentication

Generate a Personal API Key

Notify API

Endpoint Reference

Path Parameters

Request Body Parameters

Sample Request

Sample Response

Key Points

Audit Log API

Endpoint Reference

Query Parameters

Supported Entities and Actions

Sample Request

Sample Response

Trace Log API

Endpoint Reference

Headers

Query Parameters

Sample Request

Sample Response

Response Reference