Arkivel

API reference

Generated from Arkivel 1.0.0. Source snapshot.

Public API v1

The focused Arkivel read API generated from the live contract.

This website serves reference files. Send application requests to your own Arkivel instance.

OpenAPI · Contract · Client metadata

/api/v1/articles GET
{
  "get": {
    "operationId": "v1_articles_list",
    "tags": [
      "articles"
    ],
    "summary": "{ articles, pagination }",
    "security": [],
    "x-arkivel-auth": "public",
    "parameters": [
      {
        "name": "page",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      },
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      },
      {
        "name": "category",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      {
        "name": "tag",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    ],
    "responses": {
      "200": {
        "description": "{ articles, pagination }"
      },
      "400": {
        "description": "Invalid request parameters."
      }
    }
  }
}
/api/v1/categories GET
{
  "get": {
    "operationId": "v1_categories_list",
    "tags": [
      "categories"
    ],
    "summary": "{ categories }",
    "security": [],
    "x-arkivel-auth": "public",
    "parameters": [],
    "responses": {
      "200": {
        "description": "{ categories }"
      }
    }
  }
}
/api/v1/tags GET
{
  "get": {
    "operationId": "v1_tags_list",
    "tags": [
      "tags"
    ],
    "summary": "{ tags }",
    "security": [],
    "x-arkivel-auth": "public",
    "parameters": [],
    "responses": {
      "200": {
        "description": "{ tags }"
      }
    }
  }
}
/api/v1/search GET
{
  "get": {
    "operationId": "v1_search_query",
    "tags": [
      "search"
    ],
    "summary": "{ results, query }",
    "security": [],
    "x-arkivel-auth": "public",
    "parameters": [
      {
        "name": "q",
        "in": "query",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      {
        "name": "limit",
        "in": "query",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 100,
          "default": 20
        }
      }
    ],
    "responses": {
      "200": {
        "description": "{ results, query }"
      },
      "400": {
        "description": "Invalid request parameters."
      }
    }
  }
}

Application routes

Create a personal access token in your instance at /settings/tokens. Send it as Authorization: Bearer ark_…; your account permissions still apply.

/api/admin/audit-log GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/admin/categories/merge POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/admin/kits GET
[
  {
    "method": "GET",
    "summary": "every starter kit with, for each, which of its modules are enabled and which of its collections already exist."
  }
]
/api/admin/kits/apply POST
[
  {
    "method": "POST",
    "summary": "body `{ kit: KitId, seedSampleItems?: boolean }`. Returns the apply report: `{ kit, skin, modulesEnabled, collectionsCreated, collectionsSkipped, itemsCreated }`."
  }
]
/api/admin/maintenance GET POST
[
  {
    "method": "GET",
    "summary": "get current mode"
  },
  {
    "method": "POST",
    "summary": "toggle maintenance mode"
  }
]
/api/admin/maintenance/report GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  }
]
/api/admin/modules GET PUT DELETE
[
  {
    "method": "GET",
    "summary": "the registry with the environment default, override, and resolved set"
  },
  {
    "method": "PUT",
    "summary": "store `{ enabled: ModuleId[] }` as the admin override"
  },
  {
    "method": "DELETE",
    "summary": "drop the override and return to the environment default"
  }
]
/api/admin/read-only GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  }
]
/api/admin/redirects GET POST DELETE
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  },
  {
    "method": "DELETE",
    "summary": null
  }
]
/api/articles GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  }
]
/api/articles/{id} GET PUT DELETE
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "PUT",
    "summary": null
  },
  {
    "method": "DELETE",
    "summary": null
  }
]
/api/articles/{id}/aliases GET POST DELETE
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  },
  {
    "method": "DELETE",
    "summary": null
  }
]
/api/articles/{id}/blame GET
[
  {
    "method": "GET",
    "summary": "GET /api/articles/[id]/blame Returns a per-paragraph blame annotation: for each non-empty paragraph in the current article content, finds the earliest revision that introduced it."
  }
]
/api/articles/{id}/check-password POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/articles/{id}/links GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  }
]
/api/articles/{id}/revisions/{revisionId} GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": "POST = revert to this revision (admin only)"
  }
]
/api/articles/{id}/revisions/{revisionId}/restore POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/articles/{id}/revisions/export GET
[
  {
    "method": "GET",
    "summary": "GET — download all revisions as CSV"
  }
]
/api/articles/{id}/share-token POST DELETE
[
  {
    "method": "POST",
    "summary": "POST — generate a share token for a draft article"
  },
  {
    "method": "DELETE",
    "summary": "DELETE — revoke the share token"
  }
]
/api/articles/import POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/assets GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  }
]
/api/auth/check GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/auth/login POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/auth/logout POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/auth/register POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/categories GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  }
]
/api/categories/{id} PUT DELETE
[
  {
    "method": "PUT",
    "summary": null
  },
  {
    "method": "DELETE",
    "summary": null
  }
]
/api/collections GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": "Body: `{ name, categoryId?, description?, icon?, template?: \"blank\" | \"tasks\" | \"reading_list\" | \"simple_table\", schema?, views? }`. A template supplies schema and views unless the body overrides them."
  }
]
/api/collections/{id} GET PATCH DELETE
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "PATCH",
    "summary": "Body: any of `{ name, slug, description, icon, categoryId, schema }`."
  },
  {
    "method": "DELETE",
    "summary": null
  }
]
/api/collections/{id}/import-course-sync POST
[
  {
    "method": "POST",
    "summary": "Body: { source: canonical course-sync JSON, dryRun?: boolean }. Preview is the default."
  }
]
/api/collections/{id}/items GET POST
[
  {
    "method": "GET",
    "summary": "`?page=1&q=title` — 100 items a page, ordered by sortOrder then creation."
  },
  {
    "method": "POST",
    "summary": "Body: `{ title, properties?, articleId?, sortOrder? }`."
  }
]
/api/collections/{id}/items/{itemId} GET PATCH DELETE
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "PATCH",
    "summary": "Body: any of `{ title, properties (merged), articleId, sortOrder }`."
  },
  {
    "method": "DELETE",
    "summary": null
  }
]
/api/collections/{id}/views POST
[
  {
    "method": "POST",
    "summary": "Body: `{ name, slug?, kind?, config?, isDefault? }`."
  }
]
/api/collections/{id}/views/{viewId} PATCH DELETE
[
  {
    "method": "PATCH",
    "summary": "Body: any of `{ name, slug, kind, config, isDefault, sortOrder }`."
  },
  {
    "method": "DELETE",
    "summary": null
  }
]
/api/export/history GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/export/json GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/export/markdown GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/export/zip GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/graph GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/health GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/health/wiki GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/import/notion POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/import/obsidian POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/media/health GET
[
  {
    "method": "GET",
    "summary": "`{ mode, catalog, recommendation, sample_library, can_edit }` — configuration, not provider connectivity."
  }
]
/api/media/import POST PUT
[
  {
    "method": "POST",
    "summary": "Body: `{ items }` or `{ raw }` (a JSON file's text) — preview matches; nothing is saved."
  },
  {
    "method": "PUT",
    "summary": "Body: `{ items: [watchlist item inputs] }` (1–100) — saves them as plan_to_watch; `{ imported, skipped, items }`."
  }
]
/api/media/library GET POST PUT DELETE
[
  {
    "method": "GET",
    "summary": "Downloads the whole library as `arkivel-library.json`."
  },
  {
    "method": "POST",
    "summary": "Body: `{ backup }` — previews a merge: `{ added, existing, episodesAdded, episodesExisting }`."
  },
  {
    "method": "PUT",
    "summary": "Body: `{ backup }` — merges it into the library; same counts as the preview."
  },
  {
    "method": "DELETE",
    "summary": "Removes untouched starter titles and their marks: `{ removed }`."
  }
]
/api/media/mood POST
[
  {
    "method": "POST",
    "summary": "Body: `{ mood, count? }` — `{ mood, source, message, recommendations }` from the unwatched library."
  }
]
/api/media/save POST
[
  {
    "method": "POST",
    "summary": "Body: `{ media: \"movie\" | \"series\", id, status? }` — saves a title into the watchlist; returns the existing item when it is already there."
  }
]
/api/media/search GET
[
  {
    "method": "GET",
    "summary": "`?q=` — matching titles (trending when blank), each flagged with the watchlist item that already has it."
  }
]
/api/media/seasons POST
[
  {
    "method": "POST",
    "summary": "Body: `{ itemId, season }` — marks every episode of that season watched for a saved series: one row per episode in the episodes collection (created when missing, updated when present), bound to the watchlist item."
  }
]
/api/media/titles GET
[
  {
    "method": "GET",
    "summary": "`?q=&type=` — Search results (trending or the catalogue when `q` is blank)."
  }
]
/api/media/titles/{media}/{id} GET
[
  {
    "method": "GET",
    "summary": "A title's details, its saved watchlist item if any, and `?season=n` episodes for a series."
  }
]
/api/media/tmdb/{id} GET
[
  {
    "method": "GET",
    "summary": "`?type=movie|tv&seasons=1` — `{ tmdb, ratings, seasons?, source, episode_scope? }`."
  }
]
/api/media/watchlist GET POST
[
  {
    "method": "GET",
    "summary": "`?status=&type=&mood=` — saved titles, each with metadata and episode counts."
  },
  {
    "method": "POST",
    "summary": "Body: a watchlist item input — saves it; an existing `(tmdb_id, media_type)` comes back unchanged."
  }
]
/api/media/watchlist/{id} PATCH DELETE
[
  {
    "method": "PATCH",
    "summary": "Body: `{ status?, moods? }` (at least one) — updates the title; `watched` stamps a missing watched date."
  },
  {
    "method": "DELETE",
    "summary": "Removes the title and its episode marks; 404 when it is already gone."
  }
]
/api/media/watchlist/{id}/episodes GET POST DELETE
[
  {
    "method": "GET",
    "summary": "Watched episode marks for the title, by season then episode."
  },
  {
    "method": "POST",
    "summary": "Body: `{ episodes: [{ season_number, episode_number }] }` (1–500) — marks them watched; returns the requested marks."
  },
  {
    "method": "DELETE",
    "summary": "Body: `{ season_number, episode_number }` — removes that mark; 204 even when it was already absent."
  }
]
/api/preferences GET PUT
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "PUT",
    "summary": null
  }
]
/api/search GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/sessions GET
[
  {
    "method": "GET",
    "summary": "list current user's active sessions"
  }
]
/api/sessions/{id} DELETE
[
  {
    "method": "DELETE",
    "summary": "revoke a session (must belong to current user)"
  }
]
/api/tags GET POST
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "POST",
    "summary": null
  }
]
/api/tags/{id} PUT DELETE
[
  {
    "method": "PUT",
    "summary": null
  },
  {
    "method": "DELETE",
    "summary": null
  }
]
/api/tokens GET POST
[
  {
    "method": "GET",
    "summary": "the caller's personal access tokens (never the secrets)."
  },
  {
    "method": "POST",
    "summary": "`{ name, expiresInDays: number | null }`; the response carries the token once."
  }
]
/api/tokens/{id} DELETE
[
  {
    "method": "DELETE",
    "summary": "revoke a token you own (admins may revoke any)."
  }
]
/api/upload POST
[
  {
    "method": "POST",
    "summary": null
  }
]
/api/users GET PATCH
[
  {
    "method": "GET",
    "summary": null
  },
  {
    "method": "PATCH",
    "summary": null
  }
]
/api/v1/articles GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/v1/categories GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/v1/contract GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/v1/openapi.json GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/v1/sdk GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/v1/search GET
[
  {
    "method": "GET",
    "summary": null
  }
]
/api/v1/tags GET
[
  {
    "method": "GET",
    "summary": null
  }
]