Kubiya LogoKubiya Developer Docs

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

MethodPathDescription
GET/api/v1/agentsList all agents
GET/api/v1/agents/{agentId}Get specific agent
POST/api/v1/agentsCreate agent
PUT/api/v1/agents/{agentId}Update agent
DELETE/api/v1/agents/{agentId}Delete agent
GET/api/v1/agents/{agentId}/integrationsGet agent integrations
GET/api/v1/agents/{agentId}/activate_integrationsActivate agent integrations

List Agents

Retrieve all available agents in your organization.

GET `/api/v1/agents`

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeNoapplication/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

FieldTypeDescription
ai_instructionsstringCustom instructions for the AI agent
allowed_groupsarrayList of group IDs that have access to this agent
allowed_usersarrayList of user IDs that have access to this agent
avatar_urlstringURL to the agent's avatar image
descriptionstringDetailed description of the agent's capabilities
environment_variablesobjectKey-value pairs of environment variables for the agent
idstringUnique identifier for the agent
imagestringContainer image used for the agent
instruction_typestringType of instructions used by the agent (e.g., "tools")
integrationsarrayList of enabled integrations (e.g., "aws", "github", "slack")
is_debug_modebooleanWhether debug mode is enabled for the agent
linksarrayList of associated links
llm_modelstringThe LLM model used by the agent (e.g., "azure/gpt-4o")
managed_bystringID of the entity managing this agent
metadataobjectMetadata about the agent including creation and update timestamps
namestringName of the agent
ownersarrayList of user IDs who own this agent
runnersarrayList of runner IDs where this agent can execute
secretsarrayList of secret names accessible to the agent
sourcesarrayList of source IDs providing tools or knowledge
startersarrayList of conversation starters
tagsarrayList of tags associated with the agent
task_idstringAssociated task ID if any
tasksarrayList of associated tasks
toolsarrayList of tools available to the agent
uuidstringUnique identifier for the agent

Get Agent Details

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

Path Parameters

NameTypeRequiredDescription
agentIdstringYesID 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

NameTypeRequiredDescription
agentIdstringYesID 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

NameTypeRequiredDescription
agentIdstringYesID 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

NameTypeRequiredDescription
agentIdstringYesID 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

NameTypeRequiredDescription
agentIdstringYesID 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 StatusDescription
400Bad Request - The request was invalid, often due to missing required fields
401Unauthorized - API key is missing or invalid
403Forbidden - The API key doesn't have permission to perform this action
404Not Found - The specified agent was not found
409Conflict - An agent with the same name already exists
500Internal Server Error - An unexpected error occurred on the server

Next Steps

After creating and configuring your agents, you can: