Knowledge Base
Workspace-scoped Markdown documents for agent and developer context
Knowledge Base
Every workspace has a Knowledge Base — a collection of Markdown documents that describe the workspace's context, conventions, integrations, data sources, and business rules.
AI agents should always consult the Knowledge Base before starting any development task in a workspace.
Label Conventions
Use consistent labels to categorize documents:
| Label | Use For |
|---|---|
conventions | Coding standards, naming rules, patterns |
credentials | Which credentials exist and what they connect to |
data-sources | External APIs, databases, Airtable bases |
business-rules | Domain logic, approval flows, SLA rules |
architecture | System design decisions, integration topology |
runbooks | Step-by-step operational procedures |
Managing Documents
List Documents
curl "https://app.headlessops.ai/api/workspaces/ws_abc123/knowledge-docs?search=crm" \
-H "Cookie: session=YOUR_SESSION"Returns an array of { id, title, labels, snippet, updatedAt }.
Get a Document
curl https://app.headlessops.ai/api/workspaces/ws_abc123/knowledge-docs/doc_id \
-H "Cookie: session=YOUR_SESSION"Returns the full Markdown content.
Create a Document
curl -X POST https://app.headlessops.ai/api/workspaces/ws_abc123/knowledge-docs \
-H "Cookie: session=YOUR_SESSION" \
-H "Content-Type: application/json" \
-d '{
"title": "Airtable CRM Schema",
"content": "# Airtable CRM\n\nBase ID: appXXX\n\n## Tables\n...",
"labels": ["data-sources", "crm"]
}'Update / Delete
# Update
curl -X PUT https://app.headlessops.ai/api/workspaces/ws_abc123/knowledge-docs/doc_id \
-H "Cookie: session=YOUR_SESSION" \
-d '{ "content": "...updated content..." }'
# Delete
curl -X DELETE https://app.headlessops.ai/api/workspaces/ws_abc123/knowledge-docs/doc_id \
-H "Cookie: session=YOUR_SESSION"In-Integration Knowledge Files
In addition to workspace-level documents, integrations can include a knowledge_base.md file in their package. This file documents integration-specific context: API schemas, field mappings, business rules, and notes for future developers or agents.
See knowledge_base.md and fix_log.md conventions for the recommended format.