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

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

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

[
  {
    "content": "# ...",
    "content_hash": "...",
    "created_at": "...",
    "description": "...",
    "groups": ["..."],
    "labels": [],
    "managed_by": "",
    "name": "...",
    "owner": "...",
    "properties": {},
    "source": "...",
    "supported_agents": ["..."],
    "supported_agents_groups": [],
    "task_id": "",
    "type": "knowledge",
    "updated_at": "...",
    "uuid": "..."
  }
]

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

Required Fields

  • title: Title of the knowledge entry
  • content: Markdown content of the knowledge entry

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

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,
  "versions": [
    {
      "version": 1,
      "updated_at": "2023-01-01T00:00:00Z",
      "updated_by": "user@example.com"
    },
    {
      "version": 2,
      "updated_at": "2023-01-02T00:00:00Z",
      "updated_by": "user@example.com"
    }
  ]
}

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

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
}

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
qstringYesSearch query
tagsarrayNoFilter by tags (comma-separated)
limitintegerNoMaximum number of entries to return (default: 10)

Headers

NameRequiredDescription
AuthorizationYesUserKey YOUR_API_KEY

Response

{
  "entries": [
    {
      "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",
      "score": 0.95
    }
  ],
  "total": 1
}

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: