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

API v1

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

API v2

Method	Path	Description
GET	`/api/v2/agents`	List all agents (with name filtering)
GET	`/api/v2/agents/{agentId}`	Get specific agent

Common Response Status Codes

Status Code	Description
200	Success
400	Bad Request - Invalid parameters or request body
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
500	Internal Server Error

Error Response Format

{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

Example Error Responses

// 400 Bad Request
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request parameters",
    "details": {
      "name": "Name is required"
    }
  }
}
 
// 404 Not Found
{
  "error": {
    "code": "not_found",
    "message": "Agent not found",
    "details": {
      "agentId": "agent-uuid-123"
    }
  }
}

API v2 Endpoints

List Agents (v2)

Retrieve all available agents in your organization with optional name filtering.

GET `/api/v2/agents`

Query Parameters

Name	Type	Required	Description
`name`	string	No	Filter agents by name

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	No	application/json

Response

[
  {
    "ai_instructions": "string",
    "allowed_groups": ["string"],
    "allowed_users": ["string"],
    "avatar_url": "string",
    "description": "string",
    "environment_variables": {
      "string": "string"
    },
    "id": "string",
    "image": "string",
    "instruction_type": "string",
    "integrations": ["string"],
    "is_debug_mode": boolean,
    "links": [],
    "llm_model": "string",
    "managed_by": "string",
    "metadata": {
      "created_at": "string",
      "last_updated": "string",
      "user_created": "string",
      "user_last_updated": "string"
    },
    "name": "string",
    "owners": ["string"],
    "runners": ["string"],
    "secrets": ["string"],
    "sources": ["string"],
    "starters": [],
    "tags": [],
    "task_id": "string",
    "tasks": [],
    "tools": [],
    "uuid": "string"
  }
]

Get Agent Details (v2)

GET `/api/v2/agents/{agentId}`

Path Parameters

Name	Type	Required	Description
`agentId`	string	Yes	ID of the agent

Response

{
  "uuid": "agent-uuid-123",
  "name": "devops-expert",
  "description": "DevOps and infrastructure specialist",
  "tools": ["aws-ec2", "kubernetes"],
  "sources": ["source-id-456"]
}

The v2 API endpoints provide enhanced functionality and improved response formats. While v1 endpoints are still supported, it's recommended to use v2 endpoints for new integrations.

List Agents

Retrieve all available agents in your organization.

GET `/api/v1/agents`

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	No	application/json

Response

[
  {
    "ai_instructions": "string",
    "allowed_groups": [
      "string"
    ],
    "allowed_users": [
      "string"
    ],
    "avatar_url": "string",
    "description": "string",
    "environment_variables": {
      "string": "string"
    },
    "id": "string",
    "image": "string",
    "instruction_type": "string",
    "integrations": [
      "string"
    ],
    "is_debug_mode": boolean,
    "links": [],
    "llm_model": "string",
    "managed_by": "string",
    "metadata": {
      "created_at": "string",
      "last_updated": "string",
      "user_created": "string",
      "user_last_updated": "string"
    },
    "name": "string",
    "owners": [
      "string"
    ],
    "runners": [
      "string"
    ],
    "secrets": [
      "string"
    ],
    "sources": [
      "string"
    ],
    "starters": [],
    "tags": [],
    "task_id": "string",
    "tasks": [],
    "tools": [],
    "uuid": "string"
  }
]

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

GET `/api/v1/agents/{agentId}`

Path Parameters

Name	Type	Required	Description
`agentId`	string	Yes	ID of the agent

Response

{
  "uuid": "agent-uuid-123",
  "name": "devops-expert",
  "description": "DevOps and infrastructure specialist",
  "tools": ["aws-ec2", "kubernetes"],
  "sources": ["source-id-456"]
}

Create Agent

POST `/api/v1/agents`

Request Body

{
  "name": "devops-expert",
  "description": "DevOps and infrastructure specialist",
  "tools": ["aws-ec2", "kubernetes"],
  "sources": ["source-id-456"]
}

Response

{
  "uuid": "agent-uuid-123",
  "name": "devops-expert",
  "description": "DevOps and infrastructure specialist"
}

Update Agent

PUT `/api/v1/agents/{agentId}`

Path Parameters

Name	Type	Required	Description
`agentId`	string	Yes	ID of the agent to update

Request Body

{
  "name": "devops-expert",
  "description": "Updated description",
  "tools": ["aws-ec2", "kubernetes", "github"]
}

Response

{
  "uuid": "agent-uuid-123",
  "name": "devops-expert",
  "description": "Updated description"
}

Delete Agent

DELETE `/api/v1/agents/{agentId}`

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.

GET `/api/v1/agents/{agentId}/integrations`

Path Parameters

Name	Type	Required	Description
`agentId`	string	Yes	ID of the agent

Response

[
  {
    "vendor": "github",
    "status": "connected"
  }
]

Activate Agent Integrations

Activate integrations for a specific agent.

GET `/api/v1/agents/{agentId}/activate_integrations`

Path Parameters

Name	Type	Required	Description
`agentId`	string	Yes	ID of the agent

Response

{
  "status": "activated"
}

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

Agents API

On this page