outline

name	outline
description	Manage Outline knowledge base via REST API — create/update docs, manage collections, organize folders. Works with any self-hosted Outline instance.
version	2.0.0
license	MIT
tags	["outline","wiki","docs","knowledge-base","api","publishing"]

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

Operation	Endpoint	Key Fields
List collections	collections.list	—
Create doc	documents.create	title, text, collectionId, parentDocumentId, publish
Update doc	documents.update	id, title, text
Get doc info	documents.info	id
Move doc	documents.move	id, parentDocumentId, collectionId
Archive doc	documents.archive	id
List docs in collection	documents.list	collectionId
Search	documents.search	query

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

Scenario	Structure	Example
Single topic, <28K chars	Standalone doc in folder	[Research] Beehiiv vs Substack
Large topic, multi-part	Parent folder + sub-docs	Micro-SaaS Research > Batch 1, 2, Deep Dive
Blueprint/manuscript	Parent folder + chapters	[Blueprint] AI Agency > Chapter 1, 2...
Daily/automated content	Standalone doc in dedicated folder	DD - Topic in News Digest

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

Type	Format	Example
Technical doc	Title Case	HTTP Router API Reference
Project doc	[Project] Title	[Hermes] Agent Architecture
Research	[Research] Topic	[Research] Beehiiv vs Substack
Blueprint	[Blueprint] Title	[Blueprint] The AI Agency
Automation	[Automation] Title	[Automation] Chatwoot CS Agent
Archived	[ARCHIVED] Title	[ARCHIVED] Old Memory System

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

Content Size Strategy

Size	Strategy
< 28K chars	Single doc
28K-60K chars	Split into 2-3 sub-docs under parent folder
> 60K chars	Parent index + multiple sub-docs

Update vs Create Decision

Situation	Action
Doc doesn't exist	documents.create
Doc exists, content outdated	documents.update (id + text)
Doc in wrong folder	documents.move (id + parentDocumentId + collectionId)
Duplicate doc	Rename old [ARCHIVED], update main one

Duplication & Conflict Resolution

Scenario	Action
Same title exists	Check content — update if newer, archive if same
Wrong folder	documents.move to correct folder
Doc no longer relevant	Rename [ARCHIVED] Title, then documents.archive
Doc too large for single file	Create parent folder, split into sub-docs

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

File	Description
references/api_reference.md	Complete API endpoint reference, auth, error codes
references/code_examples.md	Python helper functions, request patterns, batch operations
references/pitfalls.md	All gotchas, error table, deletion safety checklist