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

Method	Path	Description
GET	`/api/v1/knowledge`	List all knowledge entries
GET	`/api/v1/knowledge/{knowledgeId}`	Get knowledge entry details
POST	`/api/v1/knowledge`	Create 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/search`	Search knowledge entries
GET	`/api/v1/knowledge/{knowledgeId}/versions`	Get 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 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

Name	Type	Required	Description
`tag`	string	No	Filter by tag
`limit`	integer	No	Maximum number of entries to return (default: 50)
`page`	integer	No	Page number for pagination
`sort`	string	No	Sort field (e.g., "created_at", "updated_at")
`order`	string	No	Sort order ("asc" or "desc")

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/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

Name	Type	Required	Description
`knowledgeId`	string	Yes	ID of the knowledge entry to retrieve

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Type	Required	Description
`knowledgeId`	string	Yes	ID of the knowledge entry to update

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY
`Content-Type`	Yes	application/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

Name	Type	Required	Description
`knowledgeId`	string	Yes	ID of the knowledge entry to delete

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Type	Required	Description
`query`	string	Yes	Search query
`tags`	array	No	Filter by tags
`visibility`	string	No	Filter by visibility
`limit`	integer	No	Maximum number of entries to return (default: 50)
`page`	integer	No	Page number for pagination
`sort`	string	No	Sort field (e.g., "relevance", "created_at")
`order`	string	No	Sort order ("asc" or "desc")

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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

Name	Type	Required	Description
`knowledgeId`	string	Yes	ID of the knowledge entry

Query Parameters

Name	Type	Required	Description
`limit`	integer	No	Maximum number of versions to return (default: 50)
`page`	integer	No	Page number for pagination

Headers

Name	Required	Description
`Authorization`	Yes	UserKey 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 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

Next Steps

After setting up knowledge entries, you can:

Use them to provide context to Agents
Share them with Teammates
Organize them with Tags

Knowledge API

On this page