ajianaz/codomate/outline

Outline Knowledge Base — REST API Skill

Manage self-hosted Outline via REST API. All operations use POST method only (including reads).

When to Use

• Create, update, move, or archive documents
• Manage collections and folder structure
• Build automated content pipelines (publish docs from scripts)
• Set up knowledge base structure for teams

Setup

Prerequisites

• Self-hosted Outline instance (v0.78+)
• Admin API Key (generate in Outline Settings → API Keys)
• Python 3.8+ (no external dependencies — urllib only)

Environment

OUTLINE_URL=https://your-outline-domain.com
OUTLINE_API_KEY=your-api-key-here

Verify

# Quick health check — should return your collections
resp = outline_post("collections.list")
print(resp)

Quick Reference

Full API reference → references/api_reference.md

Key Rules

1. POST method only — all endpoints use POST, including reads
2. Content field is `"text"` — NOT "markdown" (markdown creates empty docs silently)
3. Content limit — ~28K chars safe (30K hard, silently truncated)
4. Full 36-char UUIDs — truncated UUIDs cause 403/404
5. `publish: true` on create — drafts can't receive children
6. `documents.move` for moving — documents.update returns 200 but does NOT move docs
7. Use `timeout=60` for updates — 15s default causes silent 400 on large content
8. NEVER use `documents.search` for deletion — use parentDocumentId for folder ops

Document Organization

Folder vs Standalone Doc

Parent Folder Rules

• Parent folder = index only (<2K chars), not full narrative
• Every sub-doc: publish: true when creating
• Sub-docs must be created AFTER parent is published
• Max recommended depth: 3-4 levels (Collection > Folder > Subfolder > Doc)

Naming Conventions

Rules: Use [Tag] prefix for grouping. No emoji in titles. No em-dash —. Descriptive titles only — never Notes or Draft.

Content Size Strategy

Update vs Create Decision

Duplication & Conflict Resolution

Link Sharing

• Use url field from documents.info → /doc/{slug}-{urlId}
• Do NOT use /s/{uuid} share links (often broken)
• Include hierarchy path in reports: Collection > Folder > Doc
• Public sharing may require login depending on Outline config (OIDC auth)

References