Open Platform

Knowledges API

Manage your knowledge base programmatically via PAT-authenticated API endpoints.

The Knowledges API lets PAT-authenticated users manage knowledge entries programmatically. All requests require the Authorization: Bearer <pat_token> header and use the base path /personal/v1/knowledge/.

Endpoint Overview

Method	Path	Description
POST	`/personal/v1/knowledge/list`	List knowledge entries
GET	`/personal/v1/knowledge/{id}`	Get knowledge details
POST	`/personal/v1/knowledge/create`	Create a knowledge entry
POST	`/personal/v1/knowledge/update`	Update a knowledge entry
POST	`/personal/v1/knowledge/upsert`	Save a knowledge entry (create or update)

Common Response Structure

{
  "code": 200,
  "message": "common.success",
  "data": { ... }
}

Field	Type	Description
code	int	Status code, 200 indicates success
message	string	Internationalized message key
data	object/null	Response data

Pagination data structure for list endpoints:

Field	Type	Description
page	object/null	Pagination info, `null` when no pagination params sent
page.total	int	Total record count
page.page_num	int	Current page number (starts from 1)
page.page_size	int	Records per page
items	array	List of `KnowledgeResponse` objects

Knowledge Object (KnowledgeResponse)

Field	Type	Description
id	int	Auto-increment primary key
name	string	Knowledge name
type	string	Knowledge type: `default` or `document`
trigger	string	Trigger condition type (see enum below)
trigger_config	object	Trigger configuration (varies by trigger type)
description	string/null	Knowledge description
data	object	Knowledge content data (varies by type)
labels	object/null	Label key-value pairs, e.g. `{"env": "prod"}`
metadata	object/null	Metadata information
application_id	string/null	Compat field derived from `trigger_config.application_id`
application_name	string/null	Display name from application trigger config
workspace_id	string/null	Workspace ID
is_public	bool	Whether it's public knowledge
is_readonly	bool	Whether it's read-only
is_applied	bool	Whether the workspace has subscribed
source	string	Knowledge source, defaults to `"custom"`
forked_from	int/null	Fork source knowledge ID, NULL means original
created_at	int	Creation timestamp (milliseconds)
updated_at	int	Update timestamp (milliseconds)

Trigger Enum (KnowledgeTrigger)

Value	Description	trigger_config Requirement
`smart`	Smart trigger	No config beyond `application_id`
`always`	Always active	No config beyond `application_id`
`application`	Application-bound	Must provide `application_id`
`service`	Service-bound	Must provide `service_id`
`infrastructure`	Infrastructure-bound	Must provide `infrastructure_id`
`connector`	Connector-bound	Must provide `connector_id`
`bridge_node`	Bridge node-bound	Must provide `bridge_node_client_id`
`proxy`	Proxy node-bound	Must provide `proxy_id`
`alert`	Alert-bound	Must provide non-empty `match_patterns` array

KnowledgeType Enum

Value	Description	data Requirement
`default`	Simple knowledge	Must provide `content` field
`document`	Document knowledge	Must provide `document_content` or `document_id` field

FilterOperator Enum

Value	Description
`eq`	Exact match
`includeAny`	Include any (OR)
`excludeAny`	Exclude any
`like`	Fuzzy match

Endpoint Details

List Knowledge

POST /personal/v1/knowledge/list
Authorization: Bearer <pat_token>
Content-Type: application/json

Request body:

Field	Type	Required	Description
filters	object	No	Filter conditions
filters.name	FilterValue	No	Filter by knowledge name
filters.type	FilterValue	No	Filter by knowledge type
filters.trigger	FilterValue	No	Filter by trigger type
filters.labels	LabelFilter	No	Filter by labels
filters.application_id	FilterValue	No	Filter by application_id
filters.service_id	FilterValue	No	Filter by service_id
filters.infrastructure_id	FilterValue	No	Filter by infrastructure_id
filters.connector_id	FilterValue	No	Filter by connector_id
filters.bridge_node_client_id	FilterValue	No	Filter by bridge_node_client_id
filters.proxy_id	FilterValue	No	Filter by proxy_id
filters.workspace_id	FilterValue	No	Filter by workspace_id
filters.is_public	FilterValue	No	Filter by public status
filters.is_readonly	FilterValue	No	Filter by read-only status
filters.source	FilterValue	No	Filter by source
sort	object	No	Sort configuration
sort.order_by	string	Yes	Sort field
sort.order	string	Yes	Sort direction: `desc`, `asc`
page	object	No	Pagination configuration
page.page_no	int	No	Page number, starts from 1, default 1
page.page_size	int	No	Records per page, 1~200, default 20
include_public	bool	No	Include public knowledge, default `false`
context_visible_only	bool	No	Use context visible set only, default `true`

FilterValue structure:

Field	Type	Required	Description
operator	string	Yes	Operator: `eq`, `includeAny`, `excludeAny`, `like`
values	array	No	Values list for array operations
value	string	No	Value for single-value operations

LabelFilter structure:

Field	Type	Required	Description
operator	string	Yes	Filter operator
values	array	Yes	Label filter item list
values.key	string	Yes	Label key
values.value	string/null	No	Label value, empty means match by key only

curl examples:

# List without filters
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/list' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": {
      "page_no": 1,
      "page_size": 20
    },
    "sort": {
      "order_by": "created_at",
      "order": "desc"
    }
  }' | jq .

# Fuzzy search by name
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/list' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "name": {
        "operator": "like",
        "value": "alert"
      }
    },
    "page": {
      "page_no": 1,
      "page_size": 20
    }
  }' | jq .

# Filter by trigger type
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/list' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": {
      "trigger": {
        "operator": "eq",
        "value": "alert"
      }
    },
    "page": {
      "page_no": 1,
      "page_size": 50
    }
  }' | jq .

Get Knowledge Details

GET /personal/v1/knowledge/{id}
Authorization: Bearer <pat_token>

Path parameters:

Parameter	Type	Description
id	int	Knowledge primary key ID

curl example:

curl -s 'http://localhost:8000/personal/v1/knowledge/1' \
  -H 'Authorization: Bearer <pat_token>' | jq .

Response example:

{
  "code": 200,
  "message": "common.success",
  "data": {
    "id": 1,
    "name": "MySQL Connection Alert Handling",
    "type": "default",
    "trigger": "alert",
    "trigger_config": {
      "match_patterns": ["MySQL connection"]
    },
    "description": "Standard handling procedure for MySQL connection limit alerts",
    "data": {
      "content": "1. Log into MySQL and run SHOW PROCESSLIST\n2. Identify long-running transactions or slow queries\n3. Kill blocking sessions"
    },
    "labels": {"env": "prod"},
    "application_id": null,
    "application_name": null,
    "workspace_id": "wks-xxx",
    "is_public": false,
    "is_readonly": false,
    "is_applied": false,
    "source": "custom",
    "forked_from": null,
    "created_at": 1717000000000,
    "updated_at": 1717000000000
  }
}

Create Knowledge

POST /personal/v1/knowledge/create
Authorization: Bearer <pat_token>
Content-Type: application/json

Request body:

Field	Type	Required	Description
name	string	Yes	Knowledge name, max 255 characters, cannot be empty or whitespace
type	string	Yes	Knowledge type: `default` or `document`
trigger	string	Yes	Trigger condition type
trigger_config	object	Yes	Trigger configuration, must match trigger type
description	string/null	No	Knowledge description
data	object	Yes	Knowledge content data
labels	object/null	No	Label key-value pairs, key cannot be empty
metadata	object/null	No	Metadata information

curl examples:

# Create simple knowledge (default type + alert trigger)
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/create' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "MySQL Connection Alert Handling",
    "type": "default",
    "trigger": "alert",
    "trigger_config": {
      "match_patterns": ["MySQL connection"]
    },
    "description": "Standard handling procedure for MySQL connection limit alerts",
    "data": {
      "content": "1. Log into MySQL and run SHOW PROCESSLIST\n2. Identify long-running transactions or slow queries\n3. Kill blocking sessions"
    },
    "labels": {
      "env": "prod",
      "team": "dba"
    }
  }' | jq .

# Create application-triggered knowledge
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/create' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Order Service Restart Procedure",
    "type": "document",
    "trigger": "application",
    "trigger_config": {
      "application_id": "app-order-service"
    },
    "data": {
      "document_content": "# Order Service Restart\n\n1. Confirm no pending orders\n2. Perform graceful shutdown\n3. Wait for health check to pass"
    }
  }' | jq .

Update Knowledge

POST /personal/v1/knowledge/update
Authorization: Bearer <pat_token>
Content-Type: application/json

All fields except id are optional. When updating data, type must also be provided. When updating trigger_config, trigger must also be provided.

Request body:

Field	Type	Required	Description
id	int	Yes	Knowledge primary key ID
name	string/null	No	Knowledge name
type	string/null	No	Knowledge type
trigger	string/null	No	Trigger condition type
trigger_config	object/null	No	Trigger config (must provide trigger along with it)
description	string/null	No	Knowledge description
data	object/null	No	Knowledge content data (must provide type along with it)
labels	object/null	No	Label key-value pairs
metadata	object/null	No	Metadata information

curl example:

# Update knowledge name and content
curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/update' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 1,
    "name": "MySQL Connection Alert Handling v2",
    "type": "default",
    "data": {
      "content": "Updated handling procedure..."
    }
  }' | jq .

Upsert Knowledge

POST /personal/v1/knowledge/upsert
Authorization: Bearer <pat_token>
Content-Type: application/json

Uses name + trigger + trigger_config as the unique identifier. Updates if exists, creates if not.

Request body:

Field	Type	Required	Description
name	string	Yes	Knowledge name
trigger	string	Yes	Trigger condition type
trigger_config	object	Yes	Trigger configuration
type	string/null	No	Knowledge type
description	string/null	No	Knowledge description
data	object/null	No	Knowledge content data
labels	object/null	No	Label key-value pairs
metadata	object/null	No	Metadata information

curl example:

curl -s -X POST 'http://localhost:8000/personal/v1/knowledge/upsert' \
  -H 'Authorization: Bearer <pat_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "MySQL Connection Alert Handling",
    "type": "default",
    "trigger": "alert",
    "trigger_config": {
      "match_patterns": ["MySQL connection"]
    },
    "data": {
      "content": "Latest handling procedure..."
    },
    "labels": {
      "env": "staging"
    }
  }' | jq .

Edit this pageorReport an issue

Authentication

Authenticate with Castrel APIs using Personal Access Tokens.

Roadmap

Upcoming features and improvements for Castrel.