Guide: Upload a Document

This guide walks you through uploading an existing document - a playbook, framework, database, or reference guide - as a knowledge artifact.

Prerequisites

• A document in PDF, Markdown, or plain text format (max 20 MB)
• Kate API key
• pip install projectkate

Step 1: Prepare Your Document

Kate works best with well-structured documents. Before uploading:

• Use clear headings - clear section headers help Kate process your content effectively
• Include examples - documents with concrete examples produce better artifact responses
• Remove boilerplate - strip cover pages, tables of contents, and appendices that don't contain knowledge
• Check for sensitive data - review your document for personally identifiable information before uploading

Supported formats:

• PDF (text-based, not scanned images)
• Markdown (.md)
• Plain text (.txt)

Step 2: Upload

import asyncio
from projectkate import KateClient

async def main():
    async with KateClient(api_key="your-api-key") as client:
        artifact = await client.artifacts.upload(
            name="Restaurant Menu Engineering Playbook",
            file_path="./menu-engineering.pdf",
            domain="restaurant-management",
        )
        print(f"Created: {artifact.title} ({artifact.id})")
        print(f"Status: {artifact.status}")  # "draft"

asyncio.run(main())

Kate processes the upload and creates a draft artifact.

Using curl:

curl -X POST "https://api.projectkate.com/artifacts/upload?title=Menu+Engineering&domain=restaurant-management" \
  -H "x-api-key: your-api-key" \
  -F "file=@./menu-engineering.pdf"

Step 3: Review Coverage

Check what topics the artifact covers:

artifact = await client.artifacts.analyze_coverage(
    artifact_id=artifact.id
)

Review the coverage analysis in the dashboard to see:

• Which topics are well-covered
• Any gaps in coverage
• Quality assessment

Step 4: Set Pricing

Configure pricing in the dashboard or set it during upload:

Step 5: Publish

artifact = await client.artifacts.publish(artifact_id=artifact.id)
print(f"Status: {artifact.status}")

Step 6: Update Versions

When your knowledge changes, upload a new version:

1. Upload the updated document as a new artifact
2. Existing subscribers stay on their current version
3. You can notify subscribers of the new version

Tips for Better Upload Artifacts

• Structure matters - a well-organized document with clear headings produces more accurate artifact responses
• Be specific - "Tax Optimization for US Freelancers earning $50K-$200K" is better than "Tax Guide"
• Include edge cases - documents that cover common exceptions and gotchas are more valuable to buyer agents
• Keep it focused - a 30-page deep dive on one topic is more useful than a 200-page surface-level overview of many topics

Next Steps

• Artifact Types - understand KH-Upload vs other types
• Pricing & Tokens - pricing strategies
• Improving Quality Scores - maximize quality