> ## Documentation Index > Fetch the complete documentation index at: https://koreai-ai-for-process-dev.mintlify.app/llms.txt > Use this file to discover all available pages before exploring further. # API Reference The Agent Platform provides two sets of APIs: * **Agentic App APIs**: The Agent Protocol API enables programmatic interaction with your agents, allowing you to manage conversational sessions, execute agent logic, retrieve responses, and track asynchronous tasks. * **Tools APIs**: Secured APIs to manage files, tools, models, and guardrails. Developers can perform key activities like deployment, import/export, monitoring, analytics, billing, and reporting using these APIs. ## Authentication ### Agentic App APIs All Agentic App API requests are made to URL `https://..com/api/v2/`. All requests must include an API Key in the `Authorization` header. You can generate the API key from the application. Know [how to generate API key](#how-to-create-the-api-key). The API keys are app-specific. They're not shared across accounts or workspaces. Ensure that you use the API key associated with the correct app when sending requests. ### Tools APIs Public APIs require an API key for authentication and authorization. The account owner or admin can generate this key in the **Settings** console. An API key serves as a unique identifier for the client or application accessing the API, ensuring security and access control. It helps: * Authenticate requests - Verify the identity of the client. * Control access - Restrict API usage based on permissions or rate limits. * Monitor usage - Track API calls for analytics, billing, or debugging. * Prevent abuse - Protect against unauthorized or excessive use. API keys are typically included in request headers or parameters to validate access. Each API key includes created on and last used dates to track its usage history. #### How to Create the API Key 1. [Login](/agent-platform/getting-started) to the Platform and [access](/agent-platform/administration/overview) the Settings Console. 2. On the left menu, click **Security & Control** > **API Scopes**. 3. Create an API app and include all the required scopes, and the API keys as mentioned [here](/agent-platform/administration/security-and-control#create-an-api-app). You can copy the API key only once and must not lose it. Save the key in a secure location for future use. ## Key Concepts and Terminologies Below is a list of important terms used across the API documentation. * **App (AppId)**: Represents a specific app created for the Platform. * **Environment (envName)**: Refers to a deployment environment for the app. The environment name must match the exact name as configured in the application. * **Session (sessionId)**: A unique ID representing a single conversation between a user and the agent. Sessions allow multi-turn conversations by preserving context. * **Session Identity**: Used to reference a session or user. You can refer to the session in one or more of the following ways: * `sessionId`: The unique, platform-generated ID for the session. * `sessionReference`: A custom session identifier. If not set, it defaults to the userReference. This can be the session identifier for the application from which the Agentic App API is invoked. * `userReference`: A unique identifier from your system that ties all sessions to a specific user. This must be unique to your system. It's a crucial identifier. Refer to [Session Resolution Steps](#session-resolution-process) for more information. * **Run (runId)**: Represents a single execution step within a session, typically triggered by user input and resulting in the agent's response. ## Session Resolution Process Each session is uniquely identified by `sessionId`, `sessionReference` is used as a secondary way to refer to the session. It can be particularly useful when the app invoking Agentic App APIs needs to maintain its own session tracking. Each session is owned by a user, identified by a system-generated **`userId`**, which is typically derived from the provided **`userReference`**. Session resolution follows a **priority-based approach** to determine how a session is created or reused. When more than one identifier is provided as input, the Platform checks them in order of priority, starting with the highest. The session is resolved using the first identifier that matches. If no match is found, the Platform moves on to the next identifier in the input. | Identifier | Priority | Purpose | | :----------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `sessionId` | Highest | Used only to retrieve an existing session. This identifier cannot be used to create new sessions. If a `userReference` is provided, it is validated against the session owner for security purposes. | | `sessionReference` | Medium | Attempts to find an existing session with the given sessionReference. | | `userReference` | Lowest | Always creates a new session associated with the specified user. Does not check for existing sessions. | The above session resolution steps are summarized using the flow chart below. Session Resolution using Identify fields ## Authorization Process for API Calls If an agent in an Agentic App includes tools that require authorization to execute APIs, the Platform ensures that the necessary authorizations are completed before any API calls are made during the agent's execution. **When OAuth Authorization is Required** At the **first invocation** of the session (via the **Session** or **Execute API**), if any required authorization is pending, the API will return a response containing a special event type: **IDP\_Redirect**. This indicates that the user needs to complete an authorization flow before the agent can proceed. The response includes: * An IDP\_Redirect event. * A URL for the user to complete the authorization process. * The identity provider (IDP) name and the authentication method. Sample Response ```json theme={null} { "messageId": "msg-260f4d3c-5b8c-4056-af97-11317fc28c8d", "events": [ { "type": "IDP_Redirect", "content": { "auth_profiles": [ { "url": "https://{host}/r/396c63515671634648357955", "idpName": "Google", "isAuthorized": false, "sso_type": "oauth2" } ] } } ], "output": [ { "type": "text", "content": "Hello! How can I assist you today with HR, Finance, or IT queries?" } ], "sessionInfo": { "status": "idle", "userReference": "s-b8987503-696b-4111-a006-49c0cbcf0fb9", "sessionReference": "s-b8987503-696b-4111-a006-49c0cbcf0fb9", "userId": "u-f5e5e830-70d4-53d6-8034-86bfa765c04a", "sessionId": "s-54f40bda-1505-4f9e-b38e-88d39ea36d58", "runId": "r-41ad20e0-6295-4f0e-9b04-e51875356107", "appId": "aa-c31cccce-d0bf-4db5-a177-7ff45941c2d8", "attachments": [] } } ``` **Next Steps** * Go to the URL in the events object and complete the authorization. * Reinvoke the API after successful authorization. **Important Notes** * Authorization is only required once per user (across sessions) or until the token expires. * If one or more authorizations are pending, all of them must be completed before continuing. If the required authorization is not completed, the associated tools will return an error upon invocation. *** ## APIs list ### Agentic App APIs The following APIs let users interact with agents and manage sessions. | Use Cases | APIs | | :------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------- | | Create, retrieve, or end a session with an agent to maintain conversation context. | [Sessions API](/agent-platform/apis/agentic-apps/sessions) | | Send user input to an agent within a session and receive the agent's response. | [Runs API](/agent-platform/apis/agentic-apps/execute) | | Upload or delete attachments to a conversation. You can reference these attachments as context during an agent run. | [File Attachment APIs](/agent-platform/apis/agentic-apps/upload) | | Create a new Agentic App. | [Create App API](/agent-platform/apis/agentic-apps/create-app) | | Manage API Keys. | [API Key Management](/agent-platform/apis/agentic-apps/api-key-mgmt) | ### File Management API | Use Cases | API | | :-------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------- | | Upload a small or large public file in the [supported formats](/agent-platform/apis/apis-list/upload-file-api). | [File Upload API](/agent-platform/apis/apis-list/upload-file-api) | ### View Process Status API | Use Cases | API | | :-------------------------------------------------------------------------- | :-------------------------------------------------------------------- | | Check the status of an ongoing or completed job related to tools or models. | [Get Dock Status API](/agent-platform/apis/apis-list/get-dock-status) | ### Manage Tools APIs | Use Cases | APIs | | :---------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ | | Import a new tool. | [Import a New Tool API](/agent-platform/apis/apis-list/import-a-new-tool) | | Import new configurations, datasets, or updates into a tool. | [Import to an Existing Tool API](/agent-platform/apis/apis-list/import-to-an-existing-tool) | | Export a tool's configuration and associated data, including its flow, for backup, sharing, or reuse. | [Export a Tool API](/agent-platform/apis/apis-list/export-a-tool) | | Deploy a specific tool into an environment. | [Deploy a Tool API](/agent-platform/apis/apis-list/deploy-a-tool) | | Undeploy a specific tool from an environment. | [Undeploy a Tool API](/agent-platform/apis/apis-list/undeploy-a-tool) | ### Manage Models APIs | Use Cases | APIs | | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------- | | Import a model in chunks. | [Import a Model API](/agent-platform/apis/apis-list/import-a-model) | | Export a trained AI model. | [Export a Model API](/agent-platform/apis/apis-list/export-a-model) | | Deploy a model into the environment in the Ready to Deploy state and configure its parameters. xYou must perform the initial deployment manually in the Platform account. Consecutive deployments must happen via the public API. | [Deploy a Model API](/agent-platform/apis/apis-list/deploy-a-model) | | Undeploy a model from the environment. | [Undeploy a Model API](/agent-platform/apis/apis-list/undeploy-a-model) | | Manage external model connections. | [External Model Connection APIs](/agent-platform/apis/apis-list/connections-api) | Built with [Mintlify](https://mintlify.com).