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://<your-agent-platform-env>.<domain>.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.
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
- Login to the Platform and access the Settings Console.
- On the left menu, click Security & Control > API Scopes.
- Create an API app and include all the required scopes, and the API keys as mentioned here.
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 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. - If a session with the given sessionReference exists, it’s retrieved.
- If no session is found, a new session is created using the sessionReference.
- If both sessionReference and userReference are provided, the userReference is validated to ensure it matches the session owner.
- If only sessionReference is provided, the session owner is automatically mapped as the user.
- When creating a new session, if no user mapping exists, the sessionReference is used as the userReference for the new session.
|
userReference | Lowest | Always creates a new session associated with the specified user. Does not check for existing sessions. |
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
{
"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": []
}
}
- 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 |
| Send user input to an agent within a session and receive the agent’s response. | Runs API |
| Upload or delete attachments to a conversation. You can reference these attachments as context during an agent run. | File Attachment APIs |
| Create a new Agentic App. | Create App API |
File Management API
| Use Cases | API |
|---|
| Upload a small or large public file in the supported formats. | File Upload 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 |
Manage Tools APIs
| Use Cases | APIs |
|---|
| Import a new tool. | Import a New Tool API |
| Import new configurations, datasets, or updates into a tool. | Import to an Existing Tool API |
| Export a tool’s configuration and associated data, including its flow, for backup, sharing, or reuse. | Export a Tool API |
| Deploy a specific tool into an environment. | Deploy a Tool API |
| Undeploy a specific tool from an environment. | Undeploy a Tool API |
Manage Models APIs
| Use Cases | APIs |
|---|
| Import a model in chunks. | Import a Model API |
| Export a trained AI model. | Export a Model API |
| 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 |
| Undeploy a model from the environment. | Undeploy a Model API |
| Manage external model connections. | External Model Connection APIs |
