{

"openapi": "3.1.0",

"info": {

"title": "docs.dev Admin API",

"version": "1.0.0",

"description": "The API behind the in-site editor: sessions, shared drafts, page management, publishing, and AI generation. Every route lives on the same origin as the docs site and authenticates with the sealed `docsdev_admin` session cookie set at sign-in."

},

"servers": [

{

"url": "/",

"description": "Same origin as the docs site"

}

],

"tags": [

{ "name": "Auth", "description": "Sign in with a PIN or GitHub, inspect the session, sign out." },

{ "name": "Drafts", "description": "Shared drafts visible to every editor, with a last-writer conflict guard." },

{ "name": "Pages", "description": "List and delete documentation pages." },

{ "name": "Publish", "description": "Commit a page (and its uploaded assets) to GitHub." },

{ "name": "AI", "description": "Workers AI documentation writing and image generation." }

],

"components": {

"securitySchemes": {

"session": {

"type": "apiKey",

"in": "cookie",

"name": "docsdev_admin",

"description": "Sealed (AES-256-GCM) session cookie issued by `POST /api/admin/login` or the GitHub OAuth callback."

}

},

"schemas": {

"Draft": {

"type": "object",

"description": "A shared draft of one page.",

"required": ["slug", "content", "updatedAt", "author"],

"properties": {

"slug": { "type": "string", "description": "Page slug. Empty string means the docs home page.", "examples": ["getting-started"] },

"content": { "type": "string", "description": "Full MDX source of the page, including frontmatter." },

"updatedAt": { "type": "integer", "description": "Server timestamp (ms) of the last save. Echo it back as `baseUpdatedAt` on the next save.", "examples": [1783106203671] },

"author": { "type": "string", "description": "Display name of the last editor. Verified from the session for GitHub sign-ins.", "examples": ["Sarah Chen"] }

}

},

"DraftMeta": {

"type": "object",

"description": "Draft listing entry (no content).",

"required": ["slug", "updatedAt", "author"],

"properties": {

"slug": { "type": "string" },

"updatedAt": { "type": "integer" },

"author": { "type": "string" }

}

},

"SessionUser": {

"type": "object",

"required": ["method", "login", "name"],

"properties": {

"method": { "type": "string", "enum": ["pin", "github"], "description": "How this session was established." },

"login": { "type": "string", "examples": ["sarah"] },

"name": { "type": "string", "examples": ["Sarah Chen"] },

"avatar": { "type": "string", "description": "Avatar URL (GitHub sessions only, may be empty)." }

}

},

"Error": {

"type": "object",

"required": ["ok"],

"properties": {

"ok": { "type": "boolean", "const": false },

"error": { "type": "string", "description": "Human-readable reason (omitted on plain auth failures)." }

}

}

},

"responses": {

"Unauthorized": {

"description": "No valid session cookie.",

"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }

},

"StoreError": {

"description": "The draft store is unreachable (for example, GitHub is down).",

"content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }

}

}

},

"security": [{ "session": [] }],

"paths": {

"/api/admin/login": {

"post": {

"tags": ["Auth"],

"operationId": "loginWithPin",

"summary": "Sign in with a PIN",

"description": "Exchanges the team PIN for a sealed session cookie. PIN sessions publish with the server-held `GITHUB_PAT`; use GitHub sign-in for per-user commit attribution.",

"security": [],

"requestBody": {

"required": true,

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["pin"],

"properties": { "pin": { "type": "string", "examples": ["1234"] } }

}

}

}

},

"responses": {

"200": {

"description": "Signed in. The `docsdev_admin` cookie is set on the response.",

"content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } }

},

"401": { "description": "Wrong PIN.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }

}

}

},

"/api/auth/github/login": {

"get": {

"tags": ["Auth"],

"operationId": "loginWithGitHub",

"summary": "Sign in with GitHub",

"description": "Starts the GitHub App OAuth flow. Authorization is push access to the docs repository — anyone who can push can edit. On success the callback sets the session cookie and redirects back to `return`.",

"security": [],

"parameters": [

{

"name": "return",

"in": "query",

"required": false,

"schema": { "type": "string" },

"description": "Path to land on after sign-in (defaults to `/admin`)."

}

],

"responses": {

"302": { "description": "Redirect to GitHub's authorization page." }

}

}

},

"/api/admin/session": {

"get": {

"tags": ["Auth"],

"operationId": "getSession",

"summary": "Inspect the current session",

"security": [],

"responses": {

"200": {

"description": "Session state. `admin` is false and `user` is null when signed out.",

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["admin", "githubOAuth"],

"properties": {

"admin": { "type": "boolean" },

"user": { "oneOf": [{ "$ref": "#/components/schemas/SessionUser" }, { "type": "null" }] },

"githubOAuth": { "type": "boolean", "description": "Whether GitHub sign-in is configured on this deployment." }

}

}

}

}

}

}

}

},

"/api/admin/logout": {

"post": {

"tags": ["Auth"],

"operationId": "logout",

"summary": "Sign out",

"description": "Clears the session cookie.",

"responses": {

"200": { "description": "Signed out.", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } } }

}

}

},

"/api/admin/drafts": {

"get": {

"tags": ["Drafts"],

"operationId": "getDrafts",

"summary": "Read a draft, or list all drafts",

"description": "With `slug`, returns that page's shared draft (or `null`). Without it, lists every draft's metadata — used for the DRAFT dots in the sidebar.",

"parameters": [

{

"name": "slug",

"in": "query",

"required": false,

"schema": { "type": "string" },

"description": "Page slug. Omit to list all drafts."

}

],

"responses": {

"200": {

"description": "The draft, or the draft list.",

"content": {

"application/json": {

"schema": {

"type": "object",

"properties": {

"ok": { "type": "boolean", "const": true },

"draft": { "oneOf": [{ "$ref": "#/components/schemas/Draft" }, { "type": "null" }], "description": "Present when `slug` was given." },

"drafts": { "type": "array", "items": { "$ref": "#/components/schemas/DraftMeta" }, "description": "Present when `slug` was omitted." }

}

}

}

}

},

"401": { "$ref": "#/components/responses/Unauthorized" },

"502": { "$ref": "#/components/responses/StoreError" }

}

},

"put": {

"tags": ["Drafts"],

"operationId": "saveDraft",

"summary": "Save a draft",

"description": "Saves the shared draft for a page. Carries the `updatedAt` you based your edit on; if a teammate saved since, the write is rejected with **409** and their draft, so the editor can offer *Load theirs / Keep mine* instead of silently clobbering. For GitHub sessions the author is taken from the verified identity — a client-supplied `author` is ignored.",

"requestBody": {

"required": true,

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["slug", "content"],

"properties": {

"slug": { "type": "string", "examples": ["getting-started"] },

"content": { "type": "string", "description": "Full MDX source." },

"author": { "type": "string", "description": "Display name (PIN sessions only)." },

"baseUpdatedAt": { "type": "integer", "description": "`updatedAt` of the server draft this edit was based on. 0 for a brand-new draft." }

}

}

}

}

},

"responses": {

"200": {

"description": "Saved.",

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["ok", "updatedAt"],

"properties": {

"ok": { "type": "boolean", "const": true },

"updatedAt": { "type": "integer", "description": "New server timestamp — send it back as `baseUpdatedAt` next time." }

}

}

}

}

},

"400": { "description": "Missing `slug` or `content`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },

"401": { "$ref": "#/components/responses/Unauthorized" },

"409": {

"description": "A teammate saved since `baseUpdatedAt`. The response carries their draft.",

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["ok", "conflict"],

"properties": {

"ok": { "type": "boolean", "const": false },

"conflict": { "$ref": "#/components/schemas/Draft" }

}

}

}

}

},

"502": { "$ref": "#/components/responses/StoreError" }

}

},

"delete": {

"tags": ["Drafts"],

"operationId": "deleteDraft",

"summary": "Delete a draft",

"parameters": [

{ "name": "slug", "in": "query", "required": true, "schema": { "type": "string" } }

],

"responses": {

"200": { "description": "Deleted (idempotent).", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } } } } } },

"400": { "description": "Missing `slug`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },

"401": { "$ref": "#/components/responses/Unauthorized" },

"502": { "$ref": "#/components/responses/StoreError" }

}

}

},

"/api/admin/pages": {

"get": {

"tags": ["Pages"],

"operationId": "listPages",

"summary": "List published pages",

"description": "Slugs of every built documentation page. The empty string is the docs home page.",

"responses": {

"200": {

"description": "Page slugs.",

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["ok", "pages"],

"properties": {

"ok": { "type": "boolean", "const": true },

"pages": { "type": "array", "items": { "type": "string" }, "examples": [["", "reading-experience", "test"]] }

}

}

}

}

},

"401": { "$ref": "#/components/responses/Unauthorized" }

}

},

"delete": {

"tags": ["Pages"],

"operationId": "deletePage",

"summary": "Delete a page",

"description": "Clears the page's shared draft, and — if the page is published — commits the removal of its MDX file to GitHub. Draft-only pages are removed instantly with `draftOnly: true`.",

"parameters": [

{ "name": "slug", "in": "query", "required": true, "schema": { "type": "string" } }

],

"responses": {

"200": {

"description": "Deleted.",

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["ok"],

"properties": {

"ok": { "type": "boolean", "const": true },

"draftOnly": { "type": "boolean", "description": "True when the page only existed as a draft — nothing was committed." }

}

}

}

}

},

"400": { "description": "Missing or invalid `slug`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },

"401": { "$ref": "#/components/responses/Unauthorized" },

"500": { "description": "No GitHub credential available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },

"502": { "description": "GitHub rejected the read or delete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }

}

}

},

"/api/admin/publish": {

"post": {

"tags": ["Publish"],

"operationId": "publishPage",

"summary": "Publish a page",

"description": "Commits the page's MDX (and any uploaded assets) to the docs repository. GitHub sessions commit with the signed-in user's token, so the commit is attributed to them; PIN sessions use the server-held `GITHUB_PAT`. Assets land under `public/uploads/` and are served at `/uploads/…`.",

"requestBody": {

"required": true,

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["slug", "content"],

"properties": {

"slug": { "type": "string", "examples": ["getting-started"] },

"content": { "type": "string", "description": "Full MDX source to commit." },

"assets": {

"type": "array",

"description": "Uploaded files referenced by the page.",

"items": {

"type": "object",

"required": ["path", "base64"],

"properties": {

"path": { "type": "string", "description": "Site path — must match `/uploads/*`.", "examples": ["/uploads/1783106555893-diagram.png"] },

"base64": { "type": "string", "description": "File body, base64-encoded." }

}

}

}

}

}

}

}

},

"responses": {

"200": {

"description": "Committed. The site rebuilds and the change goes live shortly.",

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["ok", "commitUrl"],

"properties": {

"ok": { "type": "boolean", "const": true },

"commitUrl": { "type": "string", "description": "Link to the commit on GitHub." }

}

}

}

}

},

"400": { "description": "Bad slug, content, or asset path.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },

"401": { "$ref": "#/components/responses/Unauthorized" },

"500": { "description": "No GitHub credential available.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },

"502": { "description": "GitHub rejected the commit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }

}

}

},

"/api/admin/ai/generate": {

"get": {

"tags": ["AI"],

"operationId": "aiAvailability",

"summary": "Check AI availability",

"description": "Whether this deployment can generate content (Workers AI binding present).",

"responses": {

"200": {

"description": "Availability.",

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["ok", "available"],

"properties": {

"ok": { "type": "boolean", "const": true },

"available": { "type": "boolean" }

}

}

}

}

},

"401": { "$ref": "#/components/responses/Unauthorized" }

}

},

"post": {

"tags": ["AI"],

"operationId": "aiGenerate",

"summary": "Generate documentation or an image",

"description": "With `kind: \"doc\"` (the default), writes markdown for the editor to splice in as editable blocks — optionally grounded in web search results, which are cited inline. With `kind: \"image\"`, returns a generated image as a data URL that the editor stores through the regular upload pipeline.",

"requestBody": {

"required": true,

"content": {

"application/json": {

"schema": {

"type": "object",

"required": ["prompt"],

"properties": {

"kind": { "type": "string", "enum": ["doc", "image"], "default": "doc" },

"prompt": { "type": "string", "examples": ["setting up webhooks"] },

"pageTitle": { "type": "string", "description": "Title of the page being edited (doc only)." },

"pageContext": { "type": "string", "description": "Existing page content, for tone and to avoid repetition (doc only)." },

"useSearch": { "type": "boolean", "description": "Ground the writing in web search results (doc only; needs TAVILY_API_KEY or BRAVE_API_KEY)." }

}

}

}

}

},

"responses": {

"200": {

"description": "Generated content.",

"content": {

"application/json": {

"schema": {

"oneOf": [

{

"type": "object",

"title": "Documentation",

"required": ["ok", "markdown", "sources"],

"properties": {

"ok": { "type": "boolean", "const": true },

"markdown": { "type": "string", "description": "Markdown body content, ready to parse into editor blocks." },

"sources": {

"type": "array",

"description": "Web sources used for grounding (empty without `useSearch`).",

"items": {

"type": "object",

"required": ["title", "url", "snippet"],

"properties": {

"title": { "type": "string" },

"url": { "type": "string" },

"snippet": { "type": "string" }

}

}

}

}

},

{

"type": "object",

"title": "Image",

"required": ["ok", "dataUrl", "contentType"],

"properties": {

"ok": { "type": "boolean", "const": true },

"dataUrl": { "type": "string", "description": "Generated image as a data URL." },

"contentType": { "type": "string", "examples": ["image/jpeg"] }

}

}

]

}

}

}

},

"400": { "description": "Missing prompt.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },

"401": { "$ref": "#/components/responses/Unauthorized" },

"502": { "description": "The AI provider failed or is not configured.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }

}

}

}

}

}