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.
Base URL https://api.kubiya.ai/api/v1/knowledge All endpoints require authentication with a valid API key.
Endpoints Method Path Description 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 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" : { "code" : "string" , "message" : "string" , "details" : {} } } Knowledge Entry Object Knowledge Entry Response
Search Result
{ "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 } }
List Knowledge Entries Retrieve a list of all knowledge entries in your organization.
Query Parameters Maximum number of entries to return
Page number for pagination
Sort field (e.g., “created_at”, “updated_at”)
Sort order (“asc” or “desc”)
Example Requests
curl -X GET "https://api.kubiya.ai/api/v1/knowledge" \ -H "Authorization: UserKey $KUBIYA_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.
Request Body Title of the knowledge entry
Content of the knowledge entry
Visibility level (“private”, “organization”, “public”)
Array of tags for categorization
Additional metadata for the knowledge entry
Source of the knowledge entry
Format of the content (e.g., “markdown”, “text”)
Example Requests
curl -X POST "https://api.kubiya.ai/api/v1/knowledge" \ -H "Authorization: UserKey $KUBIYA_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", "metadata": { "source": "manual", "format": "markdown" } }'
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 ID of the knowledge entry to retrieve
Example Requests
curl -X GET "https://api.kubiya.ai/api/v1/knowledge/knowledge-123456" \ -H "Authorization: UserKey $KUBIYA_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 ID of the knowledge entry to update
Request Body Updated title of the knowledge entry
Updated content of the knowledge entry
Example Requests
curl -X PUT "https://api.kubiya.ai/api/v1/knowledge/knowledge-123456" \ -H "Authorization: UserKey $KUBIYA_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", "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 ID of the knowledge entry to delete
Example Requests
curl -X DELETE "https://api.kubiya.ai/api/v1/knowledge/knowledge-123456" \ -H "Authorization: UserKey $KUBIYA_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 Maximum number of entries to return
Page number for pagination
Sort field (e.g., “relevance”, “created_at”)
Sort order (“asc” or “desc”)
Example Requests
curl -X GET "https://api.kubiya.ai/api/v1/knowledge/search?query=aws+security" \ -H "Authorization: UserKey $KUBIYA_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 ID of the knowledge entry
Query Parameters Maximum number of versions to return
Page number for pagination
Example Requests
curl -X GET "https://api.kubiya.ai/api/v1/knowledge/knowledge-123456/versions" \ -H "Authorization: UserKey $KUBIYA_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" } ] Example Usage
# List all knowledge entries curl -X GET "https://api.kubiya.ai/api/v1/knowledge" \ -H "Authorization: UserKey $KUBIYA_API_KEY " # Create a new knowledge entry KNOWLEDGE_ID = $( curl -X POST "https://api.kubiya.ai/api/v1/knowledge" \ -H "Authorization: UserKey $KUBIYA_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" }' | jq -r '.id' ) # Update the knowledge entry curl -X PUT "https://api.kubiya.ai/api/v1/knowledge/ $KNOWLEDGE_ID " \ -H "Authorization: UserKey $KUBIYA_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "title": "Updated AWS Security Best Practices", "content": "This updated document...", "tags": ["aws", "security", "cloud", "best-practices"] }' # Search for the entry curl -X GET "https://api.kubiya.ai/api/v1/knowledge/search?query=aws+security" \ -H "Authorization: UserKey $KUBIYA_API_KEY "
Common Errors Knowledge Not Found
Invalid Request
Permission Denied
{ "error" : { "code" : "not_found" , "message" : "Knowledge entry not found" , "details" : { "knowledgeId" : "knowledge-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 knowledge entry was not found 500 Internal Server Error - An unexpected error occurred on the server
Knowledge entries can be used by teammates to provide context-aware responses and by tools to access relevant information during execution.
Next Steps 