Agents API
API endpoints for managing AI Teammates in the Kubiya platform
Agents API
The Agents API allows you to manage AI Teammates (agents) in the Kubiya platform. These teammates are AI assistants that can be customized with specific tools, knowledge sources, and instructions to perform specialized tasks.
This playground makes API calls to Kubiya API through a secure server-side proxy. Your requests never expose your API token directly to the browser.
Endpoints
Method | Path | Description |
---|---|---|
GET | /api/v1/agents | List all agents |
GET | /api/v1/agents/{agentId} | Get specific agent |
POST | /api/v1/agents | Create agent |
PUT | /api/v1/agents/{agentId} | Update agent |
DELETE | /api/v1/agents/{agentId} | Delete agent |
GET | /api/v1/agents/{agentId}/integrations | Get agent integrations |
GET | /api/v1/agents/{agentId}/activate_integrations | Activate agent integrations |
List Agents
Retrieve all available agents in your organization.
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Content-Type | No | application/json |
Response
Response Fields
Field | Type | Description |
---|---|---|
ai_instructions | string | Custom instructions for the AI agent |
allowed_groups | array | List of group IDs that have access to this agent |
allowed_users | array | List of user IDs that have access to this agent |
avatar_url | string | URL to the agent's avatar image |
description | string | Detailed description of the agent's capabilities |
environment_variables | object | Key-value pairs of environment variables for the agent |
id | string | Unique identifier for the agent |
image | string | Container image used for the agent |
instruction_type | string | Type of instructions used by the agent (e.g., "tools") |
integrations | array | List of enabled integrations (e.g., "aws", "github", "slack") |
is_debug_mode | boolean | Whether debug mode is enabled for the agent |
links | array | List of associated links |
llm_model | string | The LLM model used by the agent (e.g., "azure/gpt-4o") |
managed_by | string | ID of the entity managing this agent |
metadata | object | Metadata about the agent including creation and update timestamps |
name | string | Name of the agent |
owners | array | List of user IDs who own this agent |
runners | array | List of runner IDs where this agent can execute |
secrets | array | List of secret names accessible to the agent |
sources | array | List of source IDs providing tools or knowledge |
starters | array | List of conversation starters |
tags | array | List of tags associated with the agent |
task_id | string | Associated task ID if any |
tasks | array | List of associated tasks |
tools | array | List of tools available to the agent |
uuid | string | Unique identifier for the agent |
Get Agent Details
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
agentId | string | Yes | ID of the agent |
Response
Create Agent
Request Body
Response
Update Agent
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
agentId | string | Yes | ID of the agent to update |
Request Body
Response
Delete Agent
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
agentId | string | Yes | ID of the agent to delete |
Response
A successful delete operation returns an HTTP 200 status with no response body.
Get Agent Integrations
Retrieve all integrations for a specific agent.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
agentId | string | Yes | ID of the agent |
Response
Activate Agent Integrations
Activate integrations for a specific agent.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
agentId | string | Yes | ID of the agent |
Response
The response will contain the agent's UUID which you'll need to reference in future API calls.
Common Errors
HTTP Status | Description |
---|---|
400 | Bad Request - The request was invalid, often due to missing required fields |
401 | Unauthorized - API key is missing or invalid |
403 | Forbidden - The API key doesn't have permission to perform this action |
404 | Not Found - The specified agent was not found |
409 | Conflict - An agent with the same name already exists |
500 | Internal Server Error - An unexpected error occurred on the server |
Next Steps
After creating and configuring your agents, you can:
- Set up Tools for your agents to use
- Add Knowledge Sources to provide context
- Create Webhooks to handle events from your agents