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

Knowledge Entry Object

{
  "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.

GET /api/v1/knowledge

Query Parameters

tag

string

Filter by tag

limit

integer

default:"50"

Maximum number of entries to return

page

integer

Page number for pagination

sort

string

Sort field (e.g., “created_at”, “updated_at”)

order

string

Sort order (“asc” or “desc”)

Headers

Authorization

string

required

UserKey YOUR_API_KEY

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.

POST /api/v1/knowledge

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

title

string

required

Title of the knowledge entry

content

string

required

Content of the knowledge entry

visibility

string

required

Visibility level (“private”, “organization”, “public”)

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

knowledgeId

string

required

ID of the knowledge entry to retrieve

Headers

Authorization

string

required

UserKey YOUR_API_KEY

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

knowledgeId

string

required

ID of the knowledge entry to update

Headers

Authorization

string

required

UserKey YOUR_API_KEY

Content-Type

string

required

application/json

Request Body

title

string

Updated title of the knowledge entry

content

string

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

knowledgeId

string

required

ID of the knowledge entry to delete

Headers

Authorization

string

required

UserKey YOUR_API_KEY

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

query

string

required

Search query

Headers

Authorization

string

required

UserKey YOUR_API_KEY

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

knowledgeId

string

required

ID of the knowledge entry

Query Parameters

limit

integer

default:"50"

Maximum number of versions to return

page

integer

Page number for pagination

Headers

Authorization

string

required

UserKey YOUR_API_KEY

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

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

Agents API

Use knowledge entries to provide context to your agents

Sources API

Set up sources that automatically create knowledge entries

Tasks API

Execute tasks using knowledge-enhanced agents

Search Integration

Build advanced search functionality with knowledge entries

Kubiya Platform APIs

MCP Server APIs

Agent Server APIs

​Knowledge API

​Base URL

​Endpoints

​Common Response Status Codes

​Error Response Format

​Knowledge Entry Object

​List Knowledge Entries

​Query Parameters

​Headers

​Example Requests

​Response

​Create Knowledge Entry

​Headers

​Request Body

​Example Requests

​Response

​Get Knowledge Entry

​Path Parameters

​Headers

​Example Requests

​Response

​Update Knowledge Entry

​Path Parameters

​Headers

​Request Body

​Example Requests

​Response

​Delete Knowledge Entry

​Path Parameters

​Headers

​Example Requests

​Response

​Search Knowledge

​Query Parameters

​Headers

​Example Requests

​Response

​Get Knowledge Entry Version History

​Path Parameters

​Query Parameters

​Headers

​Example Requests

​Response

​Example Usage

​Common Errors

​Error Status Codes

​Next Steps

Agents API

Sources API

Tasks API

Search Integration

Knowledge API

Base URL

Endpoints

Common Response Status Codes

Error Response Format

Knowledge Entry Object

List Knowledge Entries

Query Parameters

Headers

Example Requests

Response

Create Knowledge Entry

Headers

Request Body

Example Requests

Response

Get Knowledge Entry

Path Parameters

Headers

Example Requests

Response

Update Knowledge Entry

Path Parameters

Headers

Request Body

Example Requests

Response

Delete Knowledge Entry

Path Parameters

Headers

Example Requests

Response

Search Knowledge

Query Parameters

Headers

Example Requests

Response

Get Knowledge Entry Version History

Path Parameters

Query Parameters

Headers

Example Requests

Response

Example Usage

Common Errors

Error Status Codes

Next Steps