> ## Documentation Index > Fetch the complete documentation index at: https://koreai.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # APIs 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](#notify-api) | Send interactive notifications with action buttons to users through an agent. | | [Audit Log API](#audit-log-api) | Retrieve administrative and user activity records for reporting, SIEM integration, or compliance workflows. | | [Trace Log API](#trace-log-api) | Retrieve query-level trace log records, including response time, token consumption, models, and the source that answered each query. | > [!NOTE] > > 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: 1. Sign in to AI for Work. 2. Open the profile menu and select **Personal API Key**. 3. 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](https://koreai.mintlify.site/ai-for-work/custom-agents/agent-management.md#handling-alert-tasks). > [!NOTE] > > 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. | > [!NOTE] > > 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 ```bash expandable theme={null} 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 ```json theme={null} { "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](https://koreai.mintlify.site/ai-for-work/administration/audit-log.md). ### 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](#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](#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](#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 ```bash theme={null} 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 ```json expandable theme={null} { "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 Answer rule - 67", "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](https://koreai.mintlify.site/ai-for-work/analytics.md#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](#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. | > [!WARNING] > > 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 ```bash theme={null} 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. ```json expandable theme={null} { "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. | > [!NOTE] > > 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. ```json Agent theme={null} "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" } ] } ``` ```json Project theme={null} "respContext": { "type": "project", "sources": [ { "sourceId": "i-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", "name": "HR Policies", "type": "folder", "isFallback": false, "isPersonal": false, "_id": "xxxxxxxxxxxxxxxxxxxxxxxx" } ] } ``` ```json Attachment theme={null} "respContext": { "type": "attachment", "sources": [ { "sourceId": "xxxxxxxxxxxxxxxxxxxxxxxx", "name": "Travel-Policy.pdf", "type": "attachment", "isFallback": false, "isPersonal": false, "_id": "xxxxxxxxxxxxxxxxxxxxxxxx" } ] } ``` ```json AI Model theme={null} "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. | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.