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.

Endpoints

Method	Path	Description
GET	`/api/v1/sources`	List all sources
GET	`/api/v1/sources/{sourceId}`	Get source by ID
GET	`/api/v1/sources/{sourceId}/metadata`	Get source metadata
GET	`/api/v1/sources/load`	Discover/load a source (GET)
POST	`/api/v1/sources`	Create a new source
PUT	`/api/v1/sources/{sourceId}`	Sync a source
DELETE	`/api/v1/sources/{sourceId}`	Delete a source
GET	`/api/v1/sources/agent_sources/{sourceId}`	Get agent sources
PUT	`/api/v1/sources/zip/load`	Load a zipped source
PUT	`/api/v1/sources/zip`	Create a zipped source
PUT	`/api/v1/sources/zip/sync/{sourceId}`	Sync a zipped source

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

List All Sources

Retrieve all sources in your organization.

GET /api/v1/sources

Query Parameters

Name	Type	Required	Description
`type`	string	No	Filter by source type
`status`	string	No	Filter by source status
`limit`	integer	No	Maximum number of sources to return (default: 50)
`page`	integer	No	Page number for pagination

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "id": "source-123",
    "name": "AWS Tools",
    "type": "git",
    "url": "https://github.com/org/aws-tools",
    "branch": "main",
    "status": "active",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-15T12:00:00Z",
    "metadata": {
      "description": "Collection of AWS automation tools",
      "tags": ["aws", "automation"],
      "version": "1.0.0"
    }
  }
]

Get Source by ID

Retrieve details for a specific source.

GET /api/v1/sources/{sourceId}

Path Parameters

Name	Type	Required	Description
`sourceId`	string	Yes	ID of the source to retrieve

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "id": "source-123",
  "name": "AWS Tools",
  "type": "git",
  "url": "https://github.com/org/aws-tools",
  "branch": "main",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-15T12:00:00Z",
  "metadata": {
    "description": "Collection of AWS automation tools",
    "tags": ["aws", "automation"],
    "version": "1.0.0"
  }
}

Get Source Metadata

Retrieve metadata for a specific source.

GET /api/v1/sources/{sourceId}/metadata

Path Parameters

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

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "id": "source-123",
  "metadata": {
    "description": "Collection of AWS automation tools",
    "tags": ["aws", "automation"],
    "version": "1.0.0",
    "last_sync": "2023-01-15T12:00:00Z",
    "tools_count": 15,
    "dependencies": {
      "python": ">=3.8",
      "aws-cli": ">=2.0"
    }
  }
}

Discover/Load a Source

Discover and load a source from a URL.

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

Query Parameters

Name	Type	Required	Description
`url`	string	Yes	URL of the source to load
`branch`	string	No	Branch to load (for Git sources)
`type`	string	No	Source type (git, zip, local)

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "id": "source-123",
  "name": "AWS Tools",
  "type": "git",
  "url": "https://github.com/org/aws-tools",
  "branch": "main",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-15T12:00:00Z",
  "metadata": {
    "description": "Collection of AWS automation tools",
    "tags": ["aws", "automation"],
    "version": "1.0.0"
  }
}

Create a Source

Create a new source.

POST /api/v1/sources

Headers

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

Request Body

{
  "name": "AWS Tools",
  "type": "git",
  "url": "https://github.com/org/aws-tools",
  "branch": "main",
  "metadata": {
    "description": "Collection of AWS automation tools",
    "tags": ["aws", "automation"]
  }
}

Required Fields

name: Name of the source
type: Type of source (git, zip, local)
url: URL of the source (for git and zip types)

Response

{
  "id": "source-123",
  "name": "AWS Tools",
  "type": "git",
  "url": "https://github.com/org/aws-tools",
  "branch": "main",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-15T12:00:00Z",
  "metadata": {
    "description": "Collection of AWS automation tools",
    "tags": ["aws", "automation"],
    "version": "1.0.0"
  }
}

Sync a Source

Synchronize a source with its remote repository.

PUT /api/v1/sources/{sourceId}

Path Parameters

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

Headers

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

Request Body

{
  "branch": "main",
  "force": false
}

Response

{
  "id": "source-123",
  "name": "AWS Tools",
  "type": "git",
  "url": "https://github.com/org/aws-tools",
  "branch": "main",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-15T12:00:00Z",
  "metadata": {
    "description": "Collection of AWS automation tools",
    "tags": ["aws", "automation"],
    "version": "1.0.0",
    "last_sync": "2023-01-15T12:00:00Z"
  }
}

Delete a Source

Delete a source.

DELETE /api/v1/sources/{sourceId}

Path Parameters

Name	Type	Required	Description
`sourceId`	string	Yes	ID of the source to delete

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

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

Get Agent Sources

Retrieve sources associated with a specific agent.

GET /api/v1/sources/agent_sources/{sourceId}

Path Parameters

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

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

[
  {
    "id": "source-123",
    "name": "AWS Tools",
    "type": "git",
    "url": "https://github.com/org/aws-tools",
    "status": "active",
    "metadata": {
      "description": "Collection of AWS automation tools",
      "tags": ["aws", "automation"]
    }
  }
]

Zip Endpoints

Load a Zipped Source

Load a source from a zip file.

PUT /api/v1/sources/zip/load

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	multipart/form-data

Request Body

Name	Type	Required	Description
`file`	file	Yes	Zip file containing the source
`name`	string	Yes	Name for the source
`metadata`	object	No	Additional metadata

Response

{
  "id": "source-123",
  "name": "Local Tools",
  "type": "zip",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-15T12:00:00Z",
  "metadata": {
    "description": "Local tools collection",
    "tags": ["local", "tools"]
  }
}

Create a Zipped Source

Create a zip file from a source.

PUT /api/v1/sources/zip

Headers

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

Request Body

{
  "source_id": "source-123",
  "include_metadata": true
}

Response

The response is a zip file containing the source.

Sync a Zipped Source

Synchronize a zipped source.

PUT /api/v1/sources/zip/sync/{sourceId}

Path Parameters

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

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	multipart/form-data

Request Body

Name	Type	Required	Description
`file`	file	Yes	Updated zip file
`force`	boolean	No	Force sync even if there are conflicts

Response

{
  "id": "source-123",
  "name": "Local Tools",
  "type": "zip",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-15T12:00:00Z",
  "metadata": {
    "description": "Local tools collection",
    "tags": ["local", "tools"],
    "last_sync": "2023-01-15T12:00:00Z"
  }
}

Sources are essential for providing tools to your teammates. Make sure to keep them up to date and properly organized.

Example Usage

# List all sources
curl -X GET "https://api.kubiya.ai/api/v1/sources" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get source by ID
curl -X GET "https://api.kubiya.ai/api/v1/sources/source-123" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get source metadata
curl -X GET "https://api.kubiya.ai/api/v1/sources/source-123/metadata" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Discover/load a source
curl -X GET "https://api.kubiya.ai/api/v1/sources/load?url=https://github.com/org/aws-tools" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Create a new source
curl -X POST "https://api.kubiya.ai/api/v1/sources" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AWS Tools",
    "type": "git",
    "url": "https://github.com/org/aws-tools",
    "branch": "main",
    "metadata": {
      "description": "Collection of AWS automation tools",
      "tags": ["aws", "automation"]
    }
  }'
 
# Sync a source
curl -X PUT "https://api.kubiya.ai/api/v1/sources/source-123" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "branch": "main",
    "force": false
  }'
 
# Delete a source
curl -X DELETE "https://api.kubiya.ai/api/v1/sources/source-123" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get agent sources
curl -X GET "https://api.kubiya.ai/api/v1/sources/agent_sources/agent-123" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Load a zipped source
curl -X PUT "https://api.kubiya.ai/api/v1/sources/zip/load" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -F "file=@tools.zip" \
  -F "name=Local Tools" \
  -F "metadata={\"description\":\"Local tools collection\",\"tags\":[\"local\",\"tools\"]}"
 
# Create a zipped source
curl -X PUT "https://api.kubiya.ai/api/v1/sources/zip" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "source-123",
    "include_metadata": true
  }'
 
# Sync a zipped source
curl -X PUT "https://api.kubiya.ai/api/v1/sources/zip/sync/source-123" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -F "file=@updated-tools.zip" \
  -F "force=false"

Common Errors

HTTP Status	Description
400	Bad Request - Invalid request body or 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 source was not found
409	Conflict - A source with the same name already exists
500	Internal Server Error - An unexpected error occurred on the server

Next Steps

After setting up sources, you can:

Attach them to Agents to provide tools
Use them with Runners for execution
Manage them using Terraform

Sources API

On this page