Agents API

The Agents API allows you to manage serverkess Agents in the Kubiya platform. These agents are serverless AI assistants that can be customized with specific tools, knowledge sources, and instructions to perform specialized tasks.

Base URL

https://api.kubiya.ai/api/v1/agents

All endpoints require authentication with a valid API key.

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": {}
  }
}

Agent Object

{
  "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": false,
  "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"
}

List Agents (v1)

Retrieve all available agents in your organization.

GET /api/v1/agents

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

application/json

Example Requests

curl -X GET "https://api.kubiya.ai/api/v1/agents" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

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": false,
    "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"
  }
]

List Agents (v2)

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

GET /api/v2/agents

Query Parameters

name

string

Filter agents by name

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v2/agents" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

Response

Same format as v1 endpoint.

Get Agent Details (v1)

Retrieve details for a specific agent.

GET /api/v1/agents/{agentId}

Path Parameters

agentId

string

required

ID of the agent

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v1/agents/agent-uuid-123" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

Response

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

Get Agent Details (v2)

GET /api/v2/agents/{agentId}

Path Parameters

agentId

string

required

ID of the agent

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Response

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

Create Agent

Create a new agent.

POST /api/v1/agents

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

name

string

required

Name of the agent

description

string

Description of the agent’s capabilities

tools

array

Array of tool IDs to assign to the agent

sources

array

Array of source IDs to assign to the agent

Example Requests

curl -X POST "https://api.kubiya.ai/api/v1/agents" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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

Update an existing agent.

PUT /api/v1/agents/{agentId}

Path Parameters

agentId

string

required

ID of the agent to update

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

name

string

Updated name for the agent

description

string

Updated description

tools

array

Updated array of tool IDs

Example Requests

curl -X PUT "https://api.kubiya.ai/api/v1/agents/agent-uuid-123" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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 an agent.

DELETE /api/v1/agents/{agentId}

Path Parameters

agentId

string

required

ID of the agent to delete

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X DELETE "https://api.kubiya.ai/api/v1/agents/agent-uuid-123" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

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

agentId

string

required

ID of the agent

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/agents/agent-uuid-123/integrations" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

Response

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

Activate Agent Integrations

Activate integrations for a specific agent.

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

Path Parameters

agentId

string

required

ID of the agent

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/agents/agent-uuid-123/activate_integrations" \
  -H "Authorization: UserKey $KUBIYA_API_KEY"

Response

{
  "status": "activated"
}

Common Errors

{
  "error": {
    "code": "not_found",
    "message": "Agent not found",
    "details": {
      "agentId": "agent-uuid-123"
    }
  }
}

Error Status Codes

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

Sources API

Set up tool sources for your agents to use

Tasks API

Execute tasks with your configured agents

Runners API

Deploy runners where agents can execute

Webhooks API

Handle events from your agents

Kubiya Platform APIs

MCP Server APIs

​Agents API

​Base URL

​Endpoints

​API v1

​API v2

​Common Response Status Codes

​Error Response Format

​Agent Object

​List Agents (v1)

​Headers

​Example Requests

​Response

​List Agents (v2)

​Query Parameters

​Headers

​Example Requests

​Response

​Get Agent Details (v1)

​Path Parameters

​Headers

​Example Requests

​Response

​Get Agent Details (v2)

​Path Parameters

​Headers

​Response

​Create Agent

​Headers

​Request Body

​Example Requests

​Response

​Update Agent

​Path Parameters

​Headers

​Request Body

​Example Requests

​Response

​Delete Agent

​Path Parameters

​Headers

​Example Requests

​Response

​Get Agent Integrations

​Path Parameters

​Headers

​Example Request

​Response

​Activate Agent Integrations

​Path Parameters

​Headers

​Example Request

​Response

​Common Errors

​Error Status Codes

​Next Steps

Sources API

Tasks API

Runners API

Webhooks API

Agents API

Base URL

Endpoints

API v1

API v2

Common Response Status Codes

Error Response Format

Agent Object

List Agents (v1)

Headers

Example Requests

Response

List Agents (v2)

Query Parameters

Headers

Example Requests

Response

Get Agent Details (v1)

Path Parameters

Headers

Example Requests

Response

Get Agent Details (v2)

Path Parameters

Headers

Response

Create Agent

Headers

Request Body

Example Requests

Response

Update Agent

Path Parameters

Headers

Request Body

Example Requests

Response

Delete Agent

Path Parameters

Headers

Example Requests

Response

Get Agent Integrations

Path Parameters

Headers

Example Request

Response

Activate Agent Integrations

Path Parameters

Headers

Example Request

Response

Common Errors

Error Status Codes

Next Steps