Arkivel API Documentation

https://your-arkivel.example/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" \
  "https://your-arkivel.example/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" \
  "https://your-arkivel.example/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" \
  "https://your-arkivel.example/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" \
  "https://your-arkivel.example/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 "https://your-arkivel.example/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

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, component packs, theme packs and the theme-pack schema, and the marketplace registry with items, contract, and validation summaries
• 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
• 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/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/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 — Actor, action, target, workspace, severity, success, and date filters plus downloadable JSON exports with summary, standard, strict, or full redaction
• 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 — Relevance v2 facets, weights, synonyms, aliases, redirects, stemming, stale/review/verification signals, and admin-only score explanations
• GET / PUT / DELETE /api/articles/:id/snapshots — Snapshot read/compare/restore/discard flows plus draft recovery, editor diagnostics, and large-document fixture metadata
• GET /api/v1/contract and GET /api/v1/openapi.json — Frozen pre-v5 endpoint metadata, OpenAPI schema, standard headers/errors, fixture responses, and migration guide references
• GET /api/v1/sdk — SDK-ready TypeScript payload names, API key scopes, generated client snippets, and sample script metadata for every stable v1 surface
• POST /api/webhooks/test and POST /api/webhooks/deliveries/:id/redeliver — Timestamped signatures, retry policy, delivery logs, event schemas, replay protection, and local receiver guidance
• GET /api/admin/operations and GET /api/admin/operations?bundle=1 — Admin service health, queues, slow pages, failed webhooks/imports/exports/plugins, alerts, acknowledgements, and redacted diagnostic bundle metadata
• GET /api/admin/maintenance/report and POST /api/admin/maintenance/report — Safe-upgrade checks, backup reminders, background task pause state, cleanup queues, and runbook metadata
• GET /api/admin/observability and POST /api/admin/observability — Structured event feed, metric ingestion, privacy controls, and external collector metadata
• GET /api/admin/performance — Route p95, interaction, and bundle budgets, large-wiki fixtures, slow samples, and slow-query review metadata
• 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/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" }