Sources API

Sources in Kubiya are collections of tools that can be attached to teammates. Sources can be Git repositories, directories, or other tool collections. The Sources API allows you to create, discover, synchronize, and manage sources.

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.

List all sources

GET

Authentication

Token

Enter your Kubiya API key only. The "UserKey" prefix will be added automatically.

Get source details

GET

Authentication

Token

Enter your Kubiya API key only. The "UserKey" prefix will be added automatically.

Create a new source

POST

Authentication

Token

Enter your Kubiya API key only. The "UserKey" prefix will be added automatically.

Request Body

Source Discovery

Discover and load a source based on a URL (like a Git repository) or configuration.

GET /v1/sources/load?url={source_url}

POST /v1/sources/load?url={source_url}

Query Parameters

Name	Type	Required	Description
`url`	string	No	URL of the source to load (e.g., Git repository)
`runner`	string	No	Name of the runner to use for loading the source

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes (for POST)	application/json

Request Body (POST only)

{
  "dynamic_config": {
    "key1": "value1",
    "key2": "value2"
  },
  "inline_tools": [
    {
      "name": "custom-tool",
      "description": "A custom tool definition",
      "schema": {
        "input": {
          "type": "object",
          "properties": {}
        },
        "output": {
          "type": "object",
          "properties": {}
        }
      }
    }
  ]
}

Response

{
  "uuid": "source-id-456",
  "name": "AWS Tools",
  "url": "https://github.com/org/aws-tools",
  "tools": [
    {
      "id": "tool-id-789",
      "name": "aws-ec2-manager",
      "description": "Manage EC2 instances",
      "schema": {
        "input": {
          "type": "object",
          "properties": {}
        },
        "output": {
          "type": "object",
          "properties": {}
        }
      }
    }
  ]
}

Get Source Metadata

Retrieve metadata about a specific source.

GET /v1/sources/{source_id}

Path Parameters

Name	Type	Required	Description
`source_id`	string	Yes	ID of the source

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "uuid": "source-id-456",
  "name": "AWS Tools",
  "url": "https://github.com/org/aws-tools",
  "tools": [
    {
      "name": "aws-ec2-manager",
      "description": "Manage EC2 instances"
    }
  ]
}

Sync Source

Synchronize a source to update its tools and configuration.

POST /v1/sources/{source_id}/sync

Path Parameters

Name	Type	Required	Description
`source_id`	string	Yes	ID of the source to sync

Query Parameters

Name	Type	Required	Description
`runner`	string	No	Name of the runner to use for syncing

Headers

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

Request Body

{
  "mode": "pull",
  "branch": "main",
  "force": false,
  "auto_commit": false,
  "no_diff": false
}

Parameters Explanation

mode: Sync mode, typically "pull" to get latest changes
branch: Git branch to sync from
force: Whether to force sync even if there are conflicts
auto_commit: Whether to automatically commit changes
no_diff: Whether to skip diff generation

Response

{
  "uuid": "source-id-456",
  "name": "AWS Tools",
  "url": "https://github.com/org/aws-tools",
  "tools": [
    {
      "name": "aws-ec2-manager",
      "description": "Manage EC2 instances"
    }
  ]
}

List Source Tools

Retrieve a list of all tools in a specific source.

GET /v1/sources/{source_id}/tools

Path Parameters

Name	Type	Required	Description
`source_id`	string	Yes	ID of the source

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "id": "tool-id-789",
    "name": "aws-ec2-manager",
    "description": "Manage EC2 instances",
    "schema": {
      "input": {
        "type": "object",
        "properties": {}
      },
      "output": {
        "type": "object",
        "properties": {}
      }
    }
  }
]

Bind Source to Teammate

Connect a source to a teammate, making all tools in the source available to the teammate.

POST /v1/sources/{source_id}/teammates/{teammate_id}

Path Parameters

Name	Type	Required	Description
`source_id`	string	Yes	ID of the source
`teammate_id`	string	Yes	ID of the teammate

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

A successful bind operation returns an HTTP 200 status with no response body.

Get Source Teammates

Retrieve all teammates connected to a specific source.

GET /v1/sources/{source_id}/teammates

Path Parameters

Name	Type	Required	Description
`source_id`	string	Yes	ID of the source

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "id": "teammate-id-123",
    "uuid": "teammate-id-123",
    "name": "devops-expert",
    "sources": ["source-id-456"]
  }
]

Example Usage

Discover a Source

# Discover a source from a Git repository
curl -X GET "https://api.kubiya.ai/v1/sources/load?url=https://github.com/kubiyabot/tool-examples" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Discover a source with custom configuration
curl -X POST "https://api.kubiya.ai/v1/sources/load?url=https://github.com/kubiyabot/tool-examples" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dynamic_config": {
      "aws_region": "us-west-2"
    }
  }'

Sync a Source

# Sync a source to update its tools
curl -X POST "https://api.kubiya.ai/v1/sources/source-id-456/sync" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "pull",
    "branch": "main",
    "force": false
  }'

Bind a Source to a Teammate

# Binding a source to a teammate
curl -X POST "https://api.kubiya.ai/v1/sources/source-id-456/teammates/teammate-id-123" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json"
 
# Get all teammates for a source
curl -X GET "https://api.kubiya.ai/v1/sources/source-id-456/teammates" \
  -H "Authorization: UserKey YOUR_API_KEY"

Sources can be Git repositories, local directories, or other collections of tools. When using Git repositories, the source will automatically detect and load tool definitions from the repository.

Common Errors

HTTP Status	Description
400	Bad Request - The request was invalid or malformed
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 source or teammate was not found
500	Internal Server Error - An unexpected error occurred on the server

Next Steps

After setting up sources, you can:

Attach them to Teammates to provide capabilities
Execute Tools from the sources
Set up Webhooks to respond to source updates

Sources API

List all sources

Get source details

Create a new source

On this page