GET
/
api
/
v1
/
sources
Sources API
curl --request GET \
  --url https://api.kubiya.ai/api/v1/api/v1/sources \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: <content-type>' \
  --data '{
  "name": "<string>",
  "type": "<string>",
  "url": "<string>",
  "branch": "<string>",
  "metadata": {},
  "force": true,
  "source_id": "<string>",
  "include_metadata": true
}'

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

MethodPathDescription
GET/api/v1/sourcesList all sources
GET/api/v1/sources/{sourceId}Get source by ID
GET/api/v1/sources/{sourceId}/metadataGet source metadata
GET/api/v1/sources/loadDiscover/load a source (GET)
POST/api/v1/sourcesCreate 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/loadLoad a zipped source
PUT/api/v1/sources/zipCreate a zipped source
PUT/api/v1/sources/zip/sync/{sourceId}Sync a zipped source

Common Response Status Codes

Status CodeDescription
200Success
400Bad Request - Invalid parameters or request body
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn’t exist
500Internal 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
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 StatusDescription
400Bad Request - Invalid request body or 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 source was not found
500Internal Server Error - An unexpected error occurred on the server

Next Steps