Kubiya LogoKubiya Developer Docs

Sources API

API endpoints for managing tool sources in the Kubiya platform

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

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

List All Sources

Retrieve all sources in your organization.

GET /api/v1/sources

Query Parameters

NameTypeRequiredDescription
typestringNoFilter by source type
statusstringNoFilter by source status
limitintegerNoMaximum number of sources to return (default: 50)
pageintegerNoPage number for pagination

Headers

NameRequiredDescription
AuthorizationYesUserKey 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

NameTypeRequiredDescription
sourceIdstringYesID of the source to retrieve

Headers

NameRequiredDescription
AuthorizationYesUserKey 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

NameTypeRequiredDescription
sourceIdstringYesID of the source

Headers

NameRequiredDescription
AuthorizationYesUserKey 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

NameTypeRequiredDescription
urlstringYesURL of the source to load
branchstringNoBranch to load (for Git sources)
typestringNoSource type (git, zip, local)

Headers

NameRequiredDescription
AuthorizationYesUserKey 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

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/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

NameTypeRequiredDescription
sourceIdstringYesID of the source to sync

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/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

NameTypeRequiredDescription
sourceIdstringYesID of the source to delete

Headers

NameRequiredDescription
AuthorizationYesUserKey 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

NameTypeRequiredDescription
sourceIdstringYesID of the agent

Headers

NameRequiredDescription
AuthorizationYesUserKey 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

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesmultipart/form-data

Request Body

NameTypeRequiredDescription
filefileYesZip file containing the source
namestringYesName for the source
metadataobjectNoAdditional 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

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/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

NameTypeRequiredDescription
sourceIdstringYesID of the source to sync

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesmultipart/form-data

Request Body

NameTypeRequiredDescription
filefileYesUpdated zip file
forcebooleanNoForce 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 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
409Conflict - A source with the same name already exists
500Internal Server Error - An unexpected error occurred on the server

Next Steps

After setting up sources, you can: