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.

Base URL

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

All endpoints require authentication with a valid API key.

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

Source Object

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

List All Sources

Retrieve all sources in your organization.

GET /api/v1/sources

Query Parameters

type

string

Filter by source type

status

string

Filter by source status

limit

integer

default:"50"

Maximum number of sources to return

page

integer

Page number for pagination

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v1/sources" \
  -H "Authorization: UserKey $KUBIYA_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

sourceId

string

required

ID of the source to retrieve

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v1/sources/source-123" \
  -H "Authorization: UserKey $KUBIYA_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

sourceId

string

required

ID of the source

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Request

curl -X GET "https://api.kubiya.ai/api/v1/sources/source-123/metadata" \
  -H "Authorization: UserKey $KUBIYA_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

url

string

required

URL of the source to load

branch

string

Branch to load (for Git sources)

type

string

Source type (git, zip, local)

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X GET "https://api.kubiya.ai/api/v1/sources/load?url=https://github.com/org/tools&branch=main" \
  -H "Authorization: UserKey $KUBIYA_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

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

name

string

required

Name of the source

type

string

required

Type of source (git, zip, local)

url

string

required

URL of the source (for git and zip types)

branch

string

Branch name (for git sources)

metadata

object

Additional metadata for the source

Example Requests

curl -X POST "https://api.kubiya.ai/api/v1/sources" \
  -H "Authorization: UserKey $KUBIYA_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"]
    }
  }'

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

sourceId

string

required

ID of the source to sync

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

branch

string

Branch to sync to

force

boolean

default:"false"

Force sync even if there are conflicts

Example Requests

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

sourceId

string

required

ID of the source to delete

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Example Requests

curl -X DELETE "https://api.kubiya.ai/api/v1/sources/source-123" \
  -H "Authorization: UserKey $KUBIYA_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

sourceId

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/sources/agent_sources/agent-123" \
  -H "Authorization: UserKey $KUBIYA_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

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

multipart/form-data

Request Body

file

required

Zip file containing the source

name

string

required

Name for the source

metadata

object

Additional metadata

Example Request

curl -X PUT "https://api.kubiya.ai/api/v1/sources/zip/load" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -F "file=@tools.zip" \
  -F "name=Local Tools" \
  -F "metadata={\"description\":\"Local tools collection\"}"

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

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

source_id

string

required

ID of the source to zip

include_metadata

boolean

default:"true"

Whether to include metadata in the zip

Example Request

curl -X PUT "https://api.kubiya.ai/api/v1/sources/zip" \
  -H "Authorization: UserKey $KUBIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_id": "source-123",
    "include_metadata": true
  }' -o source-backup.zip

Response

The response is a zip file containing the source.

Common Errors

{
  "error": {
    "code": "not_found",
    "message": "Source not found",
    "details": {
      "sourceId": "source-invalid"
    }
  }
}

Error Status Codes

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
500	Internal Server Error - An unexpected error occurred on the server

Next Steps

Agents API

Attach sources to your agents

Tasks API

Execute tasks using tools from sources

Runners API

Deploy sources to runners

Knowledge API

Add knowledge alongside tool sources

Kubiya Platform APIs

MCP Server APIs

​Sources API

​Base URL

​Endpoints

​Common Response Status Codes

​Error Response Format

​Source Object

​List All Sources

​Query Parameters

​Headers

​Example Requests

​Response

​Get Source by ID

​Path Parameters

​Headers

​Example Requests

​Response

​Get Source Metadata

​Path Parameters

​Headers

​Example Request

​Response

​Discover/Load a Source

​Query Parameters

​Headers

​Example Requests

​Response

​Create a Source

​Headers

​Request Body

​Example Requests

​Response

​Sync a Source

​Path Parameters

​Headers

​Request Body

​Example Requests

​Response

​Delete a Source

​Path Parameters

​Headers

​Example Requests

​Response

​Get Agent Sources

​Path Parameters

​Headers

​Example Request

​Response

​Zip Endpoints

​Load a Zipped Source

​Headers

​Request Body

​Example Request

​Response

​Create a Zipped Source

​Headers

​Request Body

​Example Request

​Response

​Common Errors

​Error Status Codes

​Next Steps

Agents API

Tasks API

Runners API

Knowledge API

Sources API

Base URL

Endpoints

Common Response Status Codes

Error Response Format

Source Object

List All Sources

Query Parameters

Headers

Example Requests

Response

Get Source by ID

Path Parameters

Headers

Example Requests

Response

Get Source Metadata

Path Parameters

Headers

Example Request

Response

Discover/Load a Source

Query Parameters

Headers

Example Requests

Response

Create a Source

Headers

Request Body

Example Requests

Response

Sync a Source

Path Parameters

Headers

Request Body

Example Requests

Response

Delete a Source

Path Parameters

Headers

Example Requests

Response

Get Agent Sources

Path Parameters

Headers

Example Request

Response

Zip Endpoints

Load a Zipped Source

Headers

Request Body

Example Request

Response

Create a Zipped Source

Headers

Request Body

Example Request

Response

Common Errors

Error Status Codes

Next Steps