Kubiya LogoKubiya Developer Docs

Knowledge API

API endpoints for managing knowledge entries in the Kubiya platform

Knowledge API

The Knowledge API allows you to create, retrieve, update, and delete knowledge entries in the Kubiya platform. Knowledge entries provide contextual information that can be used by teammates and tools to improve their performance.

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/knowledgeList all knowledge entries
GET/api/v1/knowledge/{knowledgeId}Get knowledge entry details
POST/api/v1/knowledgeCreate a new knowledge entry
PUT/api/v1/knowledge/{knowledgeId}Update a knowledge entry
DELETE/api/v1/knowledge/{knowledgeId}Delete a knowledge entry
GET/api/v1/knowledge/searchSearch knowledge entries
GET/api/v1/knowledge/{knowledgeId}/versionsGet knowledge entry version history

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 Knowledge Entries

Retrieve a list of all knowledge entries in your organization.

GET /api/v1/knowledge

Query Parameters

NameTypeRequiredDescription
tagstringNoFilter by tag
limitintegerNoMaximum number of entries to return (default: 50)
pageintegerNoPage number for pagination
sortstringNoSort field (e.g., "created_at", "updated_at")
orderstringNoSort order ("asc" or "desc")

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

[
  {
    "id": "knowledge-123456",
    "title": "AWS Security Best Practices",
    "content": "This document outlines AWS security best practices...",
    "tags": ["aws", "security", "cloud"],
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2023-01-01T00:00:00Z",
    "created_by": "user@example.com",
    "visibility": "organization",
    "version": 1,
    "metadata": {
      "source": "manual",
      "format": "markdown",
      "size_bytes": 1024
    }
  }
]

Create Knowledge Entry

Create a new knowledge entry in your organization.

POST /api/v1/knowledge

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/json

Request Body

{
  "title": "AWS Security Best Practices",
  "content": "This document outlines AWS security best practices...",
  "tags": ["aws", "security", "cloud"],
  "visibility": "organization",
  "metadata": {
    "source": "manual",
    "format": "markdown"
  }
}

Required Fields

  • title: Title of the knowledge entry
  • content: Content of the knowledge entry
  • visibility: Visibility level ("private", "organization", "public")

Response

{
  "id": "knowledge-123456",
  "title": "AWS Security Best Practices",
  "content": "This document outlines AWS security best practices...",
  "tags": ["aws", "security", "cloud"],
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-01T00:00:00Z",
  "created_by": "user@example.com",
  "visibility": "organization",
  "version": 1,
  "metadata": {
    "source": "manual",
    "format": "markdown",
    "size_bytes": 1024
  }
}

Get Knowledge Entry

Retrieve a specific knowledge entry by ID.

GET /api/v1/knowledge/{knowledgeId}

Path Parameters

NameTypeRequiredDescription
knowledgeIdstringYesID of the knowledge entry to retrieve

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

{
  "id": "knowledge-123456",
  "title": "AWS Security Best Practices",
  "content": "This document outlines AWS security best practices...",
  "tags": ["aws", "security", "cloud"],
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-02T00:00:00Z",
  "created_by": "user@example.com",
  "visibility": "organization",
  "version": 2,
  "metadata": {
    "source": "manual",
    "format": "markdown",
    "size_bytes": 1024
  }
}

Update Knowledge Entry

Update an existing knowledge entry.

PUT /api/v1/knowledge/{knowledgeId}

Path Parameters

NameTypeRequiredDescription
knowledgeIdstringYesID of the knowledge entry to update

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY
Content-TypeYesapplication/json

Request Body

{
  "title": "Updated AWS Security Best Practices",
  "content": "This updated document outlines AWS security best practices...",
  "tags": ["aws", "security", "cloud", "best-practices"],
  "visibility": "organization",
  "metadata": {
    "source": "manual",
    "format": "markdown"
  }
}

Response

{
  "id": "knowledge-123456",
  "title": "Updated AWS Security Best Practices",
  "content": "This updated document outlines AWS security best practices...",
  "tags": ["aws", "security", "cloud", "best-practices"],
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-03T00:00:00Z",
  "created_by": "user@example.com",
  "visibility": "organization",
  "version": 3,
  "metadata": {
    "source": "manual",
    "format": "markdown",
    "size_bytes": 2048
  }
}

Delete Knowledge Entry

Delete a knowledge entry.

DELETE /api/v1/knowledge/{knowledgeId}

Path Parameters

NameTypeRequiredDescription
knowledgeIdstringYesID of the knowledge entry to delete

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

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

Search Knowledge

Search for knowledge entries based on keywords or tags.

GET /api/v1/knowledge/search

Query Parameters

NameTypeRequiredDescription
querystringYesSearch query
tagsarrayNoFilter by tags
visibilitystringNoFilter by visibility
limitintegerNoMaximum number of entries to return (default: 50)
pageintegerNoPage number for pagination
sortstringNoSort field (e.g., "relevance", "created_at")
orderstringNoSort order ("asc" or "desc")

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

{
  "results": [
    {
      "id": "knowledge-123456",
      "title": "AWS Security Best Practices",
      "content": "This document outlines AWS security best practices...",
      "tags": ["aws", "security", "cloud"],
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-01T00:00:00Z",
      "created_by": "user@example.com",
      "visibility": "organization",
      "version": 1,
      "metadata": {
        "source": "manual",
        "format": "markdown",
        "size_bytes": 1024
      },
      "relevance_score": 0.95
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 50
}

Get Knowledge Entry Version History

Retrieve the version history of a knowledge entry.

GET /api/v1/knowledge/{knowledgeId}/versions

Path Parameters

NameTypeRequiredDescription
knowledgeIdstringYesID of the knowledge entry

Query Parameters

NameTypeRequiredDescription
limitintegerNoMaximum number of versions to return (default: 50)
pageintegerNoPage number for pagination

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

[
  {
    "version": 1,
    "title": "AWS Security Best Practices",
    "content": "Initial version of AWS security best practices...",
    "created_at": "2023-01-01T00:00:00Z",
    "created_by": "user@example.com"
  },
  {
    "version": 2,
    "title": "AWS Security Best Practices",
    "content": "Updated AWS security best practices...",
    "created_at": "2023-01-02T00:00:00Z",
    "created_by": "user@example.com"
  }
]

Knowledge entries can be used by teammates to provide context-aware responses and by tools to access relevant information during execution.

Example Usage

# List all knowledge entries
curl -X GET "https://api.kubiya.ai/api/v1/knowledge" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Get knowledge entry details
curl -X GET "https://api.kubiya.ai/api/v1/knowledge/knowledge-123456" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Create a new knowledge entry
curl -X POST "https://api.kubiya.ai/api/v1/knowledge" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "AWS Security Best Practices",
    "content": "This document outlines AWS security best practices...",
    "tags": ["aws", "security", "cloud"],
    "visibility": "organization"
  }'
 
# Update a knowledge entry
curl -X PUT "https://api.kubiya.ai/api/v1/knowledge/knowledge-123456" \
  -H "Authorization: UserKey YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated AWS Security Best Practices",
    "content": "This updated document outlines AWS security best practices...",
    "tags": ["aws", "security", "cloud", "best-practices"],
    "visibility": "organization"
  }'
 
# Delete a knowledge entry
curl -X DELETE "https://api.kubiya.ai/api/v1/knowledge/knowledge-123456" \
  -H "Authorization: UserKey YOUR_API_KEY"
 
# Search knowledge entries
curl -X GET "https://api.kubiya.ai/api/v1/knowledge/search?q=aws+security&tags=aws,security" \
  -H "Authorization: UserKey YOUR_API_KEY"

Knowledge entries are a powerful way to provide context and guidance to your teammates. Make sure to keep them up to date and well-organized with appropriate tags.

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 knowledge entry was not found
500Internal Server Error - An unexpected error occurred on the server

Next Steps

After setting up knowledge entries, you can: