Arkivel API Documentation

http://localhost:3000/api/v1

v1 responses include X-Arkivel-API-Version, X-Arkivel-API-Schema, and rate-limit compatibility headers. See docs/api-v1-migration.md for pre-v5 client guidance and /api/v1/sdk for SDK-ready type, scope, example, and script metadata.

GET /api/v1/articles

List published articles with pagination and optional filters.

Example:

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:3000/api/v1/articles?page=1&limit=10&category=people"

Response:

{
  "articles": [
    {
      "title": "Example Article",
      "slug": "example-article",
      "excerpt": "A brief description...",
      "content": "<p>HTML content...</p>",
      "category": { "name": "People", "slug": "people" },
      "tags": [{ "name": "History", "slug": "history" }],
      "createdAt": "2026-01-01T00:00:00.000Z",
      "updatedAt": "2026-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 42,
    "totalPages": 5
  }
}

GET /api/v1/search

Search articles by title and content. Multi-word queries use AND logic.

Example:

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:3000/api/v1/search?q=kingdom&limit=5"

GET /api/v1/categories

List all categories with article counts and parent info.

Example:

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:3000/api/v1/categories"

Response:

{
  "categories": [
    {
      "name": "People",
      "slug": "people",
      "description": null,
      "icon": "person",
      "sortOrder": 0,
      "parent": null,
      "articleCount": 15,
      "childCount": 3
    }
  ]
}

GET /api/v1/tags

List all tags with article counts.

Example:

curl -H "X-API-Key: YOUR_KEY" \
  "http://localhost:3000/api/v1/tags"

Public feeds are available without authentication:

• RSS 2.0: /feed.xml
• Atom: /feed/atom

GET /api/stats

Get wiki-wide statistics. No authentication required.

Example:

curl "http://localhost:3000/api/stats"

Response:

{
  "articles": 42,
  "categories": 6,
  "tags": 15,
  "users": 3,
  "revisions": 128,
  "discussions": 24,
  "recentEditsThisWeek": 12
}

• Sitemap: /sitemap.xml— Dynamic sitemap with all articles and categories
• Robots: /robots.txt— Crawler instructions
• API Sitemap: /api/sitemap— XML sitemap via API route

These app feeds are designed for dashboards, demos, and local automation.

• GET /api/studio — Arkivel Studio summary, generated board nodes, graph edges, base views, and action queue
• GET /api/studio/canvas — JSON Canvas export of the generated Studio board
• GET /api/atlas — Canon Atlas territories, signals, threads, dossier, continuity pressure, and next moves
• GET /api/trails — Canon Trails guided routes, stop reasons, reading estimates, word totals, and link totals
• GET /api/intelligence — Knowledge cockpit score, radar, constellation, pressure model, engines, and action queue
• GET /api/customization — Public self-host manifest for grouped customization, supported env vars, style presets, color themes, layouts, layout composition hooks, reusable UI components including editor primitives and accessibility primitives, collaboration UX metadata, offline/PWA metadata, mobile polish metadata, desktop research metadata, accessibility finish metadata, migration readiness metadata, backup/restore metadata, upgrade assistant metadata, test quality gates metadata, e2e smoke suite metadata, release gate automation metadata, documentation onboarding metadata, in-app onboarding metadata, example site recipe metadata, feature freeze metadata, release candidate one metadata, final release gate metadata, security review metadata, privacy controls metadata, marketplace security metadata, marketplace beta metadata, marketplace lifecycle metadata, marketplace authoring metadata, template marketplace metadata, sync manifest metadata, external reference metadata, archive mirror metadata, component slot contracts, plugin manifest schema/examples/compatibility matrix, trusted local plugin loader metadata, plugin manifests, theme packs, template packs, marketplace registry/import-preview metadata, status vocabulary, detail/copy metadata, validation summaries, persisted space customization contracts, migration guidance, and theme hooks
• GET /api/plugins / PUT /api/plugins — Admin-only plugin review and enablement API with loader status, permission prompts, health metadata, compatibility, routes, widgets, hooks, load errors, and audit-backed enable/disable changes
• npm run plugin:validate — Local plugin author CLI for validating plugin.json and listing supported permissions, hooks, webhook events, schema fields, and compatibility metadata
• portableBundle in GET /api/customization — Pre-v5 full-site bundle contract with manifest fields, checksums, export scope, privacy filters, dry-run import report groups, and compatibility promises
• GET /api/export/history — Admin-only export history report with manifest, checksum, warning, omitted-data, file-count, byte-count, format, status, and scope metadata; add ?download=1 for a downloadable JSON report
• GET /api/import/rehearsal / POST /api/import/rehearsal — No-write import rehearsal contract with conflict categories, recommended actions, blocked changes, rollback plans, and fixture profiles
• GET /api/articles, GET /api/search, GET /api/categories, and GET /api/tags — Accept workspaceId, wikiId, or X-Arkivel-Workspace scoping, plus includeGlobal=1 during single-workspace migration
• GET /api/wikis/:id/invitations / POST /api/wikis/:id/invitations — Workspace admin invitation review and creation for viewer/editor/admin roles
• PATCH /api/wikis/:id/invitations — Resend or revoke workspace invitations with 14-day expiration refreshes and audit events
• roleTemplates in GET /api/customization — Role template contract and permission matrix for pages, APIs, exports, webhooks, plugins, customization, marketplace actions, API-key behavior, and recovery guidance
• collaborationControls in GET /api/customization — Workspace-aware policy for co-authors, edit locks, review assignments, comments, mentions, notifications, activity digests, contribution summaries, and public visibility checks
• editorialGovernance in GET /api/customization and GET /api/admin/editorial-governance/summary — Review due dates, required reviewers, approval thresholds, claim queues, verification stamps, ownership paths, release blockers, and editorial risk summaries
• GET /api/admin/audit-log and auditTrail in GET /api/customization — Actor, action, target, workspace, severity, success, and date filters plus downloadable JSON exports with summary, standard, strict, or full redaction
• moderation in GET /api/customization, PATCH /api/articles/:id/discussions, and PATCH /api/suggestions/:id — Discussion reports/reviewer visibility plus suggestion accept, reject, comment, assign, and convert-to-task actions with anti-spam metadata
• GET /api/search?explain=1 and searchRelevance in GET /api/customization — Relevance v2 facets, weights, synonyms, aliases, redirects, stemming, stale/review/verification signals, and admin-only score explanations
• GET /api/search/contract and searchApi in GET /api/customization — Stable typed result shapes for articles, categories, tags, discussions, revisions, and marketplace items plus query privacy, retention, and webhook event planning
• GET /api/discovery and discoveryEngines in GET /api/customization — Duplicate-page, unresolved-question, canon-conflict, glossary-gap, orphan-topic, topic-cluster, continue-reading, admin-action, and dashboard-widget discovery reports
• GET / PUT / DELETE /api/articles/:id/snapshots and editorReliability in GET /api/customization — Snapshot read/compare/restore/discard flows plus draft recovery, editor diagnostics, and large-document fixture metadata
• editorControls in GET /api/customization — Reusable editor primitive metadata, plugin command/toolbar/slash/side-panel extension points, shared block templates, and shortcut scope registry
• collaborationUx in GET /api/customization — Live editing connection states, presence-name requirements, conflict/reconnect copy, inline review planning, notification routing, mobile editor QA, and accessibility checkpoints
• GET /api/v1/contract, GET /api/v1/openapi.json, and publicApiV1 in GET /api/customization — Frozen pre-v5 endpoint metadata, OpenAPI schema, standard headers/errors, fixture responses, and migration guide references
• GET /api/v1/sdk and sdkTypes in GET /api/customization — SDK-ready TypeScript payload names, API key scopes, generated client snippets, and sample script metadata for every stable v1 surface
• POST /api/webhooks/test, POST /api/webhooks/deliveries/:id/redeliver, and webhookReliability in GET /api/customization — Timestamped signatures, retry policy, delivery logs, event schemas, replay protection, and local receiver guidance
• GET /api/admin/operations, GET /api/admin/operations?bundle=1, and operationsDashboard in GET /api/customization — Admin service health, queues, slow pages, failed webhooks/imports/exports/plugins, alerts, acknowledgements, and redacted diagnostic bundle metadata
• GET /api/admin/maintenance/report, POST /api/admin/maintenance/report, and maintenanceTooling in GET /api/customization — Safe-upgrade checks, backup reminders, background task pause state, cleanup queues, and runbook metadata
• GET /api/admin/observability, POST /api/admin/observability, POST /api/observability/metrics, and observability in GET /api/customization — Structured event feed, metric ingestion, privacy controls, and external collector metadata
• GET /api/admin/performance and performanceBudgets in GET /api/customization — Route p95, interaction, and bundle budgets, large-wiki fixtures, slow samples, and slow-query review metadata
• GET /api/admin/cache, POST /api/admin/cache, and cacheStrategy in GET /api/customization — Cache invalidation rules, manual invalidation, stale warnings, Redis status, and deployment recipes
• GET /api/offline/contract and offlinePwa in GET /api/customization — Install metadata, service-worker cache rules, offline reading fallback, stale headers, retry queue limits, mobile QA checkpoints, draft warnings, and privacy limits
• GET /api/mobile-polish and mobilePolish in GET /api/customization — Phone, tablet, laptop, and wide desktop QA checkpoints, touch targets, safe-area checks, overflow/clipping guardrails, dialog bounds, and mobile screenshot slots
• GET /api/desktop-research and desktopResearch in GET /api/customization — Electron, Tauri, browser PWA, and Docker Desktop research, local deployment recipes, filesystem import/export UX, and research-only desktop scope decision
• GET /api/accessibility and accessibilityFinish in GET /api/customization — Keyboard/focus/dialog/dropdown/control audit matrix, graph/atlas/dashboard/marketplace/editor screen-reader summaries, high-contrast and reduced-motion checks, contribution checklist, and v5 blocker gate
• GET /api/migration-readiness and migrationReadiness in GET /api/customization — Blocking migration dry runs, backup prompts, schema compatibility reports, data-integrity checks, restore validation, representative v4 upgrade paths, and failure recovery guidance
• GET /api/backup-restore and backupRestore in GET /api/customization — Admin backup wizard sections, restore rehearsal manifest verification, conflict reports, scheduled backup planning, external storage notes, and disaster-recovery drill guidance
• GET /api/upgrade-assistant and upgradeAssistant in GET /api/customization — v5 readiness checklist, pre-upgrade diagnostics, post-upgrade smoke checks, compatibility warnings, and release-note/migration doc links
• GET /api/test-quality and testQualityGates in GET /api/customization — Expanded test surfaces, stable QA fixtures, CI matrix planning, known-warning policy, and release-manager quality dashboard planning
• GET /api/e2e-smoke-suite, e2e/smoke-suite.spec.ts, and e2eSmokeSuite in GET /api/customization — Product smoke flows, responsive smoke routes, repeatable fixture seeding, and Playwright screenshot/trace failure artifacts
• GET /api/release-gates, scripts/verify-docs-sync.mjs, and releaseGateAutomation in GET /api/customization — Release candidate gates, docs sync verification, checklist metadata, known issues, and blocker labels
• GET /api/documentation-onboarding and documentationOnboarding in GET /api/customization — Maintainer docs, setup paths, troubleshooting topics, docs IA review, and practical internal-link test metadata
• GET /api/in-app-onboarding and inAppOnboarding in GET /api/customization — First-run checklist, guided admin setup topics, contextual help panel plan, demo content pack, and screenshot checkpoint metadata
• GET /api/example-site-recipes and exampleSiteRecipes in GET /api/customization — Example setup recipes, env snippets, screenshot targets, pack recommendations, migration stories, and v5 readiness checklist metadata
• GET /api/release-freeze and featureFreeze in GET /api/customization — Feature-freeze policy, full rehearsal matrix, blocker labels, v5 gate ownership, and release-note draft metadata
• GET /api/release-candidate-one and releaseCandidateOne in GET /api/customization — RC1 gate evidence, deployment validation, starter and pack validation areas, review checklists, and feedback-template metadata
• GET /api/final-release-gates and finalReleaseGates in GET /api/customization — RC fixes, final beta freeze contracts, gate evidence, compatibility targets, correction windows, and stable v5 release gates
• GET /api/security/review and securityReview in GET /api/customization — Browser security headers, reviewed auth/API/plugin/export surfaces, abuse-case gates, supply-chain checklist, and pre-v5 threat-model draft
• GET /api/privacy/controls and privacyControls in GET /api/customization — Deployment-mode privacy controls, retention settings, user data lifecycle planning, and AI/external integration warnings
• GET /api/marketplace/security and marketplaceSecurity in GET /api/customization — Unsafe pack rejection metadata, blocked permissions/hooks, dangerous plugin capability warnings, provenance requirements, and local-only installation guidance
• GET /api/marketplace/beta and marketplaceBeta in GET /api/customization — Local-first beta metrics, featured/recent/recommended packs, collections, compatibility badges, search facets, install-intent steps, and beta limitations
• GET /api/marketplace/lifecycle and marketplaceLifecycle in GET /api/customization — Pack states, allowed transitions, inventory metadata, health checks, preview media validation, update metadata, compatibility warnings, and rollback guidance
• GET /api/marketplace/authoring and marketplaceAuthoring in GET /api/customization — Pack author dashboard sections, local validation, metadata preview, screenshot checks, license checks, docs completeness, README generation, compatibility matrix rows, quality checklist, and submission templates
• GET /api/marketplace/templates and templateMarketplace in GET /api/customization — Template-pack listings, included schema, category and article previews, compatibility notes, diff/merge contracts, and export-from-space fixture output
• GET /api/sync-manifests and syncManifests in GET /api/customization — Source/target sync manifests, section checksums, dry-run reports, visibility rules, signed snapshot planning, staging promotion guidance, and the network-federation release gate
• GET /api/external-references and externalReferences in GET /api/customization — External Arkivel reference metadata, imported/mirrored provenance labels, diagnostics, and public index planning that excludes private content
• GET /api/archive-mirrors and archiveMirrors in GET /api/customization — Read-only archive snapshots, private mirror setup, selected-space transfer workflows, repeated-sync conflict notes, and the pre-v5 federation decision checkpoint
• GET /api/categories/:id/customization / GET /api/articles/:id/customization — Public resolved customization reads for space and article overrides; admin-only PUT requests validate and save overrides while public responses hide private draft config
• GET /api/space-templates / POST /api/space-templates — Preview-safe starter space registry plus preview pages, JSON preview/import validation, one-click local import preview by template id, category trees, starter articles, sample metadata, tags, infobox fields, navigation, dashboards, layout, and recommended packs
• GET /api/space-workflows and domainWorkflows in GET /api/customization — Docs portal, team handbook, worldbuilding, research, and personal wiki workflow controls, steps, starter template links, and release gates
• GET /api/assistant-packs and assistantPacks in GET /api/customization — Opt-in built-in AI packs for drafting, summarization, search, claim extraction, taxonomy, alt-text, import cleanup, and review with per-space availability, prompt/context previews, usage logs, cost estimates, permissions, safety, admin route, and graceful fallback metadata
• GET /api/assistant-packs/governance and assistantGovernance in GET /api/customization — Privacy warnings, human-review requirements, citation prompts, confidence metadata, AI audit events, private/sensitive opt-outs, and optional/non-blocking release gate
• GET /api/categories/:id/governance / PUT /api/categories/:id/governance — Resolved space governance for owner, reviewer, visibility, review cadence, stale-page threshold, and health signals; writes are admin-only and audit logged
• GET /api/admin/space-governance/summary — Admin-only space governance dashboard summary with inherited badges and health widgets

All errors return a JSON object with an error field:

// 401 Unauthorized
{ "error": "Invalid or missing API key. Include X-API-Key header." }

// 400 Bad Request
{ "error": "Description of what went wrong" }

// 404 Not Found
{ "error": "Resource not found" }