{"openapi":"3.1.0","info":{"title":"Docsbook API","version":"2026-09-19","summary":"Ask your documentation, and reach your MCP owner surface, over plain REST.","description":"One workspace API key: the AI chat engine that answers from your documentation, your\nMCP owner surface (orientation, your own reads, and delegating a job to `docsbook_agent`), and a\nnarrow list of configuration settings — each with its own real `GET` or `POST` below.\n\nThis does not include writing documentation, translations or webhooks directly: since 2026-09-18\nthat catalog is reached only by delegating a job to `docsbook_agent`, the same as your own connected\nMCP agent now does.\n\nThis document is generated from the running server, so every operation below is reachable right now —\nnothing here 404s on the first call. Get your key from **Integrations** in your workspace settings.","contact":{"name":"Docsbook","url":"https://docsbook.io","email":"support@docsbook.io"},"license":{"name":"Proprietary","url":"https://docsbook.io/terms"}},"servers":[{"url":"https://docsbook.io","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Chat","description":"Ask your documentation a question and get one grounded answer."},{"name":"Tools","description":"Dispatch any MCP tool by name."},{"name":"Settings","description":"Change one thing about the site to a value the user stated."},{"name":"Create","description":"Bring a documentation site into existence."},{"name":"Agent","description":"The Docsbook agent — one worker you delegate to, and the whole of \"manage the documentation\" on a customer's token."},{"name":"Content","description":"Read and write the documentation itself."},{"name":"Orientation","description":"Find out what this server is, and which project the user means."},{"name":"Product Help","description":"The craft corpus — `docsbook_assistant` — how the work is done well, from Docsbook's published pages, with the pages it drew on. Served to Docsbook's own agent, not to an owner's token."}],"paths":{"/api/v1/chat":{"post":{"operationId":"askDocs","summary":"Ask the documentation a question","description":"Ask this workspace's documentation a question and get one grounded answer back,\nwith the pages it was drawn from. This is the same retrieval and the same model call the Ask AI\nwidget on the published docs site makes — not a second engine — so an answer here and an answer\nthere agree, and a fix to one is a fix to both.\n\nThe call spends from the workspace's own AI budget, the same wallet the widget spends from. There is\nno separate API quota.","tags":["Chat"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"},"example":{"question":"How do I connect a custom domain?","currentPath":"guides/advanced/custom-domain"}}}},"responses":{"200":{"description":"The grounded answer, its sources, and suggested follow-up questions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatResponse"}}}},"400":{"description":"`question` was missing or empty.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"AI chat is switched off for this workspace.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"The workspace's AI spend budget is exhausted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/tools/{tool}":{"post":{"operationId":"callTool","summary":"Call any tool by name","description":"Call a tool by name, over plain REST — no MCP client, no JSON-RPC transport, no\nOAuth dance. The request is dispatched into the exact same server your own MCP-connected agent\nreaches, so it is billed and logged identically: the same flat per-call price off the workspace\nbalance and the same row in the event feed, marked `api` rather than `mcp` so call history can\ntell the two apart.\n\nThis reaches exactly the tools your API key's owner surface does — orientation, delegating a job to\n`docsbook_agent` and watching it, and reading your own documentation and Docsbook's own docs. Most\nof those already have their own path below (**Tools** section) with a real `GET` or `POST` and a\ntyped request; this dispatch-by-name form exists for the handful that do not\n(`create_workspace`, `docsbook_agent`, `docsbook_agent_reply`, `docsbook_agent_stop`) and for\na caller that holds the tool name in a variable rather than a literal.\n\nEverything else this server can do — writing documentation, translations, analytics beyond your own\nproject, webhooks, the product's own memory — is not reachable by name here, on purpose: since\n2026-09-18 that surface belongs to `docsbook_agent`, the background worker your token can start and\nwatch. A tool name outside your owner surface answers `404 TOOL_NOT_FOUND`, never a partial result.\n\nThe workspace is resolved from the API key, so there is no project to name in the body.\n\nThis is the dispatch-by-name form, for a caller that holds the tool name in a variable. Every tool also has its own documented path below, with its real argument schema.","tags":["Tools"],"parameters":[{"name":"tool","in":"path","required":true,"description":"The tool's name, exactly as `GET /api/mcp/tools` reports it.","schema":{"type":"string"},"example":"get_analytics"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","description":"The tool's own arguments, exactly as an MCP client would send them."}}},"example":{"args":{"period":"30d"}}}}},"responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"400":{"description":"`args` was not a JSON object.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`TOOL_NOT_FOUND` — this server serves no tool by that name. Never billed: the call never reached a tool.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/configure_mentions":{"post":{"operationId":"configureMentions","summary":"Configure mentions","description":"Choose what the mention checks watch on one engine: turn the daily check on or off, and set the queries (up to 5) — the exact words a reader would type or ask. Queries a workspace does NOT rank for are the point: those are the ones Search Console can never report on. Use get_mentions to read what the checks found.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"configure_mentions","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"surface":{"type":"string","enum":["ai_overview","google","bing"],"description":"Which engine this arms: ai_overview (Google's AI answer), google or bing (the results page)."},"enabled":{"description":"Whether the daily check runs. Queries are kept either way.","type":"boolean"},"queries":{"description":"The queries to check, up to 5. Replaces the saved list.","type":"array","items":{"type":"string"}},"cron_expression":{"description":"5-field UTC cron for the check. Defaults to a daily early-morning slot.","type":"string"}},"required":["surface"]}}}}}},"/api/v1/tools/create_workspace":{"post":{"operationId":"createWorkspace","summary":"Create workspace","description":"Create a new Docsbook documentation site (workspace) — the FIRST call for 'make a docs site', 'set up documentation', «сделай документацию». Idempotent: a repository that already has a workspace is returned with already_existed: true, so no lookup is needed first. Pages come next: write_docs, which takes MANY files in one call, so a whole first site lands as one commit. GITHUB IS OPTIONAL — this is the tool for BOTH cases:\n• From scratch, no GitHub at all: OMIT repo_full_name. Docsbook creates and hosts the documentation repository itself, under its own GitHub organisation, with its own credentials. The user needs no GitHub account, no connected GitHub app and no repository — never tell them to connect GitHub or bring a repo for this. Then call write_docs to publish the pages you wrote.\n• From the user's OWN repository: pass repo_full_name ('owner/repo'). Use this when they point at a repository of theirs — including the git remote of the checkout they are working in, which counts as pointing at it — it is what the site READS and what its address is made of, so it must be a repository that exists on GitHub. A repository GitHub does not have, or that Docsbook cannot see, is created as a Docsbook-hosted site instead, and the result then reports a different repo_full_name than you asked for.\nIf a workspace for this repo already exists, returns the existing one (already_existed: true).\nALWAYS give the user `site_url` from the result verbatim; never build a link out of a GitHub username or repo name.\n\n**Price** — $0 per call, charged to the workspace balance, the same as over MCP.","tags":["Create"],"x-docsbook-tool":"create_workspace","x-docsbook-family":"create","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"repo_full_name":{"description":"GitHub repository in 'owner/repo' format, e.g. 'acme/docs'. OMIT for a Docsbook-hosted site created from scratch — no GitHub account or repository needed.","type":"string"},"custom_name":{"description":"Display name for the site, e.g. 'Acme API'. Derive it from the product's brand or repo name — never invent one; ask the user if you cannot. It also names the hosted repository, so pass it whenever you create from scratch.","type":"string"}}}}}}}}}},"/api/v1/tools/docsbook_agent":{"post":{"operationId":"docsbookAgent","summary":"Docsbook agent","description":"THE DOCSBOOK AGENT — a general-purpose worker you delegate to. Say what you want in your own words, in any language, and it does the job on the project end to end: reads the repository and the existing pages, works out what should change, writes and restructures the documentation, configures the site, translates, and measures the effect. It knows Docsbook itself — the product's own documentation is part of what it works from — so it does not need to be told how the platform works or what good documentation looks like. DELEGATE THE GOAL, NOT THE STEPS: 'document the new API', 'our quickstart loses people on step 3', 'nobody finds us in AI answers', 'make the pricing page match the product', 'переведи доки на английский', or just a question about the docs you want answered properly. It decides the steps; a caller's guess at them is the one input in the whole run that nobody chose. A REQUEST IS ENOUGH — `workspace_id` is optional. With one project on the account it uses that one; name a project in the request and it resolves it; only a genuinely ambiguous account is asked back, with candidates. SAFE TO HAND WORK TO: every page change is an ordinary git commit in the project's own repository, so it is reviewable and revertible like any other; written pages land at `generated`/`review` status and this path can never mark anything `approved` — sign-off stays a separate, deliberate human act; it asks you rather than guessing when a decision is yours; and `docsbook_agent_stop` ends it at any point. It returns immediately with a `task_id` and then works for minutes, not seconds: poll `docsbook_agent_status`, answer with `docsbook_agent_reply` when it asks, `docsbook_agent_stop` to stop it. One job per intention: two running at once on one project will both be right about the pages and can still disagree about the order they land in.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.","tags":["Agent"],"x-docsbook-tool":"docsbook_agent","x-docsbook-family":"agent","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"request":{"type":"string","minLength":3,"description":"What you want, in the user's own words, in any language. Say the GOAL and the evidence for it ('support keeps asking how to rotate keys'), not a list of steps — the agent decides the steps. Naming the project here also lets workspace_id be omitted."},"label":{"description":"Short name for this job in the list, e.g. 'API reference pass'.","type":"string"}},"required":["request"]}}}}}}}},"/api/v1/tools/docsbook_agent_reply":{"post":{"operationId":"docsbookAgentReply","summary":"Docsbook agent reply","description":"Answer the Docsbook agent's question, or add something to a job it is already working on — the decision it asked for, the fact it could not find, a correction. It picks the job back up with the whole exchange in front of it. Only for a job that is still open; a finished one is finished, start a new one with `docsbook_agent`.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.","tags":["Agent"],"x-docsbook-tool":"docsbook_agent_reply","x-docsbook-family":"agent","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"task_id":{"type":"string","description":"The job to reply to."},"text":{"type":"string","minLength":1,"description":"What you want to tell the agent, in your own words."}},"required":["task_id","text"]}}}}}}}},"/api/v1/docsbook_agent_status":{"get":{"operationId":"docsbookAgentStatus","summary":"Docsbook agent status","description":"What the Docsbook agent is doing on a job, and what came of it — status, progress, the exchange so far, and the result once it is done. `needs_owner` in the result means it asked you something and is waiting: answer with `docsbook_agent_reply`. It reports what it CHANGED and what that should move; it does not hand back the method it used.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable by name at `POST /api/v1/tools/docsbook_agent_status`.","tags":["Agent"],"x-docsbook-tool":"docsbook_agent_status","x-docsbook-family":"agent","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"task_id","in":"query","required":true,"description":"The id docsbook_agent returned.","schema":{"type":"string"}}]}},"/api/v1/tools/docsbook_agent_stop":{"post":{"operationId":"docsbookAgentStop","summary":"Docsbook agent stop","description":"Stop a Docsbook agent job. Work already committed stays — stopping is not an undo, and what landed is ordinary git history you can revert — and the agent's credential for that job is revoked immediately.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.","tags":["Agent"],"x-docsbook-tool":"docsbook_agent_stop","x-docsbook-family":"agent","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"args":{"type":"object","properties":{"task_id":{"type":"string","description":"The job to stop."},"reason":{"description":"Why, for the record.","type":"string"}},"required":["task_id"]}}}}}}}},"/api/v1/docsbook_agent_tasks":{"get":{"operationId":"docsbookAgentTasks","summary":"Docsbook agent tasks","description":"Every job this account has given the Docsbook agent, newest first — what was asked for, what is running now, what finished and how. Narrow to one project with workspace_id.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable by name at `POST /api/v1/tools/docsbook_agent_tasks`.","tags":["Agent"],"x-docsbook-tool":"docsbook_agent_tasks","x-docsbook-family":"agent","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"How many, 1-100. Default 20.","schema":{"type":"number"}}]}},"/api/v1/get_doc_outline":{"get":{"operationId":"getDocOutline","summary":"Get doc outline","description":"List every markdown page in the workspace with a short summary (title, heading count, char count) plus its lifecycle — `status`, `version` and `agentMayBuildFrom`. Use it to discover what pages exist before searching or writing. It is also the REVIEW BOARD for documentation that is governed by status: `status: 'review'` lists what is waiting on a human, `status: 'generated'` what a machine wrote that nobody has read. `counts` always describes the whole prefix, not the filtered rows, so 'four of ninety pages are approved' is one call. Statuses: generated (A machine wrote this page and no human has read it yet.) · draft (Someone is still writing it. Not ready to be read as settled.) · review (Waiting for a human to read it and decide.) · approved (A human read this version and signed off. Safe to build work from.) · locked (Frozen on purpose. Agents may read it and build from it, but may not rewrite it.) · deprecated (Superseded. Kept so its links keep working, not to be relied on.) · archived (History. Neither built from nor edited.)\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable without a token on this workspace's public MCP endpoint.\n\nAlso reachable by name at `POST /api/v1/tools/get_doc_outline`.","tags":["Content"],"x-docsbook-tool":"get_doc_outline","x-docsbook-family":"content","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"path_prefix","in":"query","required":false,"description":"Optional: restrict to pages under this path prefix.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Optional: only pages at this lifecycle status. `counts` still covers them all.","schema":{"type":"string"}}]}},"/api/v1/get_info":{"get":{"operationId":"getInfo","summary":"Get info","description":"What this Docsbook MCP server is and how to work it: the plan tiers and what each unlocks, every tool family with the rule for when it applies and how many tools it holds, how a project is named on every tool, whether this token can write, and how a site is created. Call it once, first, when you have no other orientation.\n\n**Price** — $0 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable without a token on this workspace's public MCP endpoint.\n\nAlso reachable by name at `POST /api/v1/tools/get_info`.","tags":["Orientation"],"x-docsbook-tool":"get_info","x-docsbook-family":"orientation","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[]}},"/api/v1/get_workspace":{"get":{"operationId":"getWorkspace","summary":"Get workspace","description":"Get one project in full — every setting an update_* tool can change, its plan and capabilities, its call to action, its live site_url. Address it the way the user did: a numeric id, 'owner/repo', the repo name alone, the display name, the docs URL or the custom domain — the server resolves the name, so this is the FIRST call when the user names a project, never list_workspaces. A name matching several projects returns AMBIGUOUS_WORKSPACE with the candidates; one matching none returns WORKSPACE_NOT_FOUND with the closest.\n\n**Price** — $0 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable by name at `POST /api/v1/tools/get_workspace`.","tags":["Orientation"],"x-docsbook-tool":"get_workspace","x-docsbook-family":"orientation","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"repo","in":"query","required":false,"description":"'owner/repo', or anything else the user calls the project — a repo name, a display name, a docs URL, a custom domain. Resolved the same way as a textual workspace_id.","schema":{"type":"string"}}]}},"/api/v1/list_docsbook_docs":{"get":{"operationId":"listDocsbookDocs","summary":"List docsbook docs","description":"List EVERY page of Docsbook's own official documentation — the product's full table of contents. The one call that answers 'what can Docsbook do?' without having to guess a search query first: the page list is the feature list. Use it to orient yourself before advising a user what to do, to check whether a capability is documented at all, or when a `search_docsbook_docs` query came back empty and you need to know whether the topic is missing or just worded differently. 🔴 This is the PRODUCT's manual, not the user's documentation — that is `get_doc_outline`.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable without a token on this workspace's public MCP endpoint.\n\nAlso reachable by name at `POST /api/v1/tools/list_docsbook_docs`.","tags":["Product Help"],"x-docsbook-tool":"list_docsbook_docs","x-docsbook-family":"product_help","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"path_prefix","in":"query","required":false,"description":"Optional: only pages under this prefix, e.g. 'guides/' or 'ai/'.","schema":{"type":"string"}}]}},"/api/v1/list_workspaces":{"get":{"operationId":"listWorkspaces","summary":"List workspaces","description":"List your Docsbook documentation projects — one line each: id, repo, name, live URL, plan, whether the assistant is on, and when it last published. This is the PICKER for 'which projects do I have'. When the user already NAMED the project, do not start here: pass the name to get_workspace (or as workspace_id on any tool) and the server resolves it. With `query`, returns only the projects matching a name, repo, domain or URL fragment, best match first — the fallback when a name did not resolve. For a project's full settings call get_workspace on the one you picked.\n\n**Price** — $0 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable by name at `POST /api/v1/tools/list_workspaces`.","tags":["Orientation"],"x-docsbook-tool":"list_workspaces","x-docsbook-family":"orientation","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"query","in":"query","required":false,"description":"Narrow to projects matching this — part of a name, a repo, a domain or a URL. Best match first. Omit to list everything.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Rows to return (default 50). The answer says how many matched in total.","schema":{"type":"integer"}}]}},"/api/v1/read_doc":{"get":{"operationId":"readDoc","summary":"Read doc","description":"Read ONE documentation page in full — its complete markdown, title and repo path. THE step between finding a page and editing it: read it here, change the text, then write_docs the whole file back. Takes the repo path search_docs and get_doc_outline use ('guides/setup.md') or the URL slug the analytics tools return ('guides/setup'); a near-miss with a single candidate is resolved for you (`resolvedFrom` says so), several candidates are listed to choose from. Use it for 'fix the command on the installation page', 'show me the quickstart', «покажи страницу», «поправь строку на странице». Changes nothing; available to any token. The result carries `lifecycle`: the page's `status`, its `version`, and `agent_may_build_from`. 🔴 When that is false the page is NOT a source of truth — a machine drafted it, or a human has not signed it off, or it was superseded. Read it, quote it as a draft, but do not generate work from it, do not cite it as a decision, and say which status it is in. `set_doc_status` is how it gets approved.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable without a token on this workspace's public MCP endpoint.\n\nAlso reachable by name at `POST /api/v1/tools/read_doc`.","tags":["Content"],"x-docsbook-tool":"read_doc","x-docsbook-family":"content","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"path","in":"query","required":true,"description":"The page: a repo file path ('reference/README.md') or its URL slug ('reference/introduction').","schema":{"type":"string"}}]}},"/api/v1/read_docsbook_doc":{"get":{"operationId":"readDocsbookDoc","summary":"Read docsbook doc","description":"Read ONE page of DOCSBOOK'S OWN official documentation in full, verbatim, by the `path` from a `search_docsbook_docs` hit (e.g. 'guides/advanced/custom-domain.md'). Use it when the search snippet is not enough to act on: step-by-step setup, the exact list of options a setting takes, what a limit actually is, what a plan actually includes. Reading the page before you answer is the difference between telling a user which switch to flip and inventing one. 🔴 This is the PRODUCT's manual, not the user's documentation — that is `read_doc`.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable without a token on this workspace's public MCP endpoint.\n\nAlso reachable by name at `POST /api/v1/tools/read_docsbook_doc`.","tags":["Product Help"],"x-docsbook-tool":"read_docsbook_doc","x-docsbook-family":"product_help","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"path","in":"query","required":true,"description":"Path in the official docs, from a search_docsbook_docs hit, e.g. 'ai/chat.md'.","schema":{"type":"string"}}]}},"/api/v1/search":{"get":{"operationId":"search","summary":"Search","description":"FIND A DOCUMENTATION PAGE — start here. Searches the project's documentation by MEANING (embeddings over a pre-built vector index), which finds the right page far more often than literal keyword matching: 'how do I reset a password' lands on a page titled 'Recovering account access', which a word search misses entirely. Use it for any natural-language question — «где написано про…», 'where do we explain X', 'which page covers Y' — and before writing anything, so you edit the page that exists instead of adding a second one about the same thing. A LONG query is welcome, and usually better than a short one: paste the user's whole request, several questions at once included. It is split into its parts, each part searched on its own and the results merged, so a request that asks about four things returns a page for each instead of one blurred average of all four. Cheap and repeatable: the index is built once, ahead of time, so a call here is one lookup against vectors that already exist. Always answers: a project with no vector index yet is searched by full text instead, and `mode` ('semantic' | 'lexical') says which engine replied — no plan is required either way. Returns hits {n, title, headingPath, url, path}, best first — each with a similarity `score` (semantic) or a `snippet` (lexical); call read_doc on `path` for the whole page. Prefer search_docs only when you need a LITERAL string — an error message, a CLI flag, a regex, a file path.\n\n**Price** — $0.3 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable without a token on this workspace's public MCP endpoint.\n\nAlso reachable by name at `POST /api/v1/tools/search`.","tags":["Content"],"x-docsbook-tool":"search","x-docsbook-family":"content","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"query","in":"query","required":true,"description":"What you are looking for, in natural language — a question or a phrase, not keywords.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 8).","schema":{"type":"integer"}}]}},"/api/v1/search_docs":{"get":{"operationId":"searchDocs","summary":"Search docs","description":"Search the workspace's documentation content and return verbatim, citable sections — the call for 'where do we describe…', 'find the page about…', «где у нас описано», «найди в документации». Modes: 'text' (default — full-text with snippets), 'grep' (regex), 'symbol' (fuzzy heading match), 'paths' (glob over file paths). Returns numbered hits {n, title, headingPath, snippet, url}: 280-character snippets, not pages — call read_doc for the whole page before editing it. Available to any token regardless of read/write scope.\n\n**Price** — $0.3 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable by name at `POST /api/v1/tools/search_docs`.","tags":["Content"],"x-docsbook-tool":"search_docs","x-docsbook-family":"content","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"query","in":"query","required":true,"description":"What to find. For 'text'/'grep' a phrase or pattern; for 'symbol' a heading hint; for 'paths' a glob.","schema":{"type":"string"}},{"name":"mode","in":"query","required":false,"description":"Search mode (default 'text').","schema":{"type":"string"}},{"name":"path_prefix","in":"query","required":false,"description":"Optional: restrict 'text'/'grep' results to files under this path prefix.","schema":{"type":"string"}}]}},"/api/v1/search_docsbook_docs":{"get":{"operationId":"searchDocsbookDocs","summary":"Search docsbook docs","description":"WHAT CAN DOCSBOOK DO, AND WHAT SHOULD I DO NEXT — ask this tool, never your own memory. It searches DOCSBOOK'S OWN official documentation (https://docsbook.io) by MEANING, using embeddings, and returns the real pages that answer the question. 🔴 CALL IT FIRST, BEFORE PLANNING OR ANSWERING, whenever the subject is Docsbook itself: 'what can I do here', 'what is Docsbook', 'what does it do', 'what can it do for me', 'what should I do now', 'what do I do next', 'how do I start', 'is X possible', 'can Docsbook do X', 'how does X work', 'how do I turn X on', 'what does this setting do', 'what does my plan include', 'what does it cost', 'why is it behaving like this', «что умеет Docsbook», «что я могу сделать», «что делать дальше», «с чего начать», «как настроить», «сколько стоит», «а можно ли». It covers the whole product: publishing a site from a GitHub repo or from nothing, custom domains, AI chat, search, auto-translation, analytics, SEO and GEO, webhooks, skills and widgets, the MCP server itself, branding, plans, billing and limits. 🔴 THIS IS THE PRODUCT'S MANUAL, NOT THE USER'S DOCUMENTATION. To search the documentation the user is working on, call `search` instead — these are two different corpora, and mixing them up produces a confident answer about the wrong product. TAKES A QUESTION, NOT KEYWORDS, and a long one is better than a short one: paste the user's whole request, several questions at once included — it is split into its parts, each searched separately, and the results merged, so a multi-part request returns a page for every part instead of one blurred average of them all. Needs no token, no workspace and no plan; it is the same for every caller. Returns hits {n, title, headingPath, url, path} best first, with a similarity `score`; `url` is a real https://docsbook.io page you can cite, and `read_docsbook_doc` on `path` gives the whole page. The manual is written in ENGLISH: query it in English even when the user wrote in another language, and answer them in theirs.\n\n**Price** — $0.008 per call, charged to the workspace balance, the same as over MCP.\n\nAlso reachable without a token on this workspace's public MCP endpoint.\n\nAlso reachable by name at `POST /api/v1/tools/search_docsbook_docs`.","tags":["Product Help"],"x-docsbook-tool":"search_docsbook_docs","x-docsbook-family":"product_help","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"query","in":"query","required":true,"description":"The question, in English, in natural language — not keywords. Long is good: paste the user's whole request if it has several parts, each part is searched separately and the results merged.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Max results (default 8).","schema":{"type":"integer"}}]}},"/api/v1/set_chat_hooks":{"post":{"operationId":"setChatHooks","summary":"Set chat hooks","description":"Set pre-, post-, and streaming webhook URLs for the AI chatbot. REQUIRES the PRO plan or above. Pass empty string to clear an individual hook.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"set_chat_hooks","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"pre_url":{"description":"Pre-LLM hook URL — receives {question, session_id, workspace_id}, may return {block, reason} or {inject_context}","type":"string"},"post_url":{"description":"Post-LLM hook URL — fire-and-forget POST with {question, answer, tool_calls, latency_ms}","type":"string"},"streaming_url":{"description":"Streaming events webhook URL — fire-and-forget SSE-style events","type":"string"}}}}}}}},"/api/v1/set_chat_system_prompt":{"post":{"operationId":"setChatSystemPrompt","summary":"Set chat system prompt","description":"Set a custom system prompt for the AI chatbot. Injected with high priority after the default system prompt. REQUIRES PRO or higher.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"set_chat_system_prompt","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"system_prompt":{"type":"string","description":"Custom system prompt text. Pass empty string to clear."}},"required":["system_prompt"]}}}}}},"/api/v1/set_doc_status":{"post":{"operationId":"setDocStatus","summary":"Set doc status","description":"Move ONE documentation page through its lifecycle — the call for 'this spec is approved', 'freeze this decision record', 'mark the old guide deprecated', «эту страницу утвердили», «заморозь», «пометь устаревшей». Statuses: `generated` — A machine wrote this page and no human has read it yet. `draft` — Someone is still writing it. Not ready to be read as settled. `review` — Waiting for a human to read it and decide. `approved` — A human read this version and signed off. Safe to build work from. Agents may build from it. `locked` — Frozen on purpose. Agents may read it and build from it, but may not rewrite it. Agents may build from it. Writes to it are refused. `deprecated` — Superseded. Kept so its links keep working, not to be relied on. `archived` — History. Neither built from nor edited. Writes to it are refused. Each page also carries a `version`, bumped automatically by every write that changes its text. 🔴 APPROVAL IS OF A VERSION, NOT OF A PAGE: editing an approved page sends it back to `review`, because the sign-off was of the text that just changed. That is not a bug to work around by re-approving in the same breath — re-approve after somebody has read the new text. 🔴 This is the only way to reach `approved` or `locked`. `write_docs` cannot set them, so an agent can never approve its own output as part of writing it. Not every move is legal: from each status only the ones listed for it (get_doc_outline shows where every page sits). REQUIRES a read-write MCP token.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Content"],"x-docsbook-tool":"set_doc_status","x-docsbook-family":"content","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"path":{"type":"string","minLength":1,"description":"The page: a repo file path ('specs/auth.md') or its URL slug ('specs/auth')."},"status":{"type":"string","enum":["generated","draft","review","approved","locked","deprecated","archived"],"description":"The status to move it to."},"version":{"description":"Optional explicit version, e.g. '1.0' when a draft becomes the first real release. Omit to keep the page's current version — a status change is not an edit.","type":"string"},"note":{"description":"Why, in the approver's own words. Goes into the commit message and the change record.","type":"string"}},"required":["path","status"]}}}}}},"/api/v1/set_translation_mode":{"post":{"operationId":"setTranslationMode","summary":"Set translation mode","description":"Set the translation workflow mode for a workspace: 'auto' (Docsbook AI), 'manual' (drafts via API), or 'external' (forward to webhook). REQUIRES PRO or higher.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"set_translation_mode","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"mode":{"type":"string","enum":["auto","manual","external"],"description":"Translation workflow mode"},"external_webhook_url":{"description":"Webhook URL (required for 'external' mode, empty string clears)","type":"string"}},"required":["mode"]}}}}}},"/api/v1/update_ai_settings":{"post":{"operationId":"updateAiSettings","summary":"Update ai settings","description":"Configure the AI chatbot. REQUIRES PRO plan. Returns upgrade info for FREE workspaces.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"update_ai_settings","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"ai_enabled":{"description":"Enable or disable the AI chatbot","type":"boolean"},"ai_provider":{"type":"string","enum":["openrouter","openai","gemini","anthropic"]},"ai_api_key":{"description":"API key for the AI provider","type":"string"},"custom_questions":{"description":"Suggested questions in the AI chat","type":"array","items":{"type":"string"}}}}}}}}},"/api/v1/update_branding":{"post":{"operationId":"updateBranding","summary":"Update branding","description":"Update visual branding: colors, fonts, logo, theme, the site's call-to-action URL, and the Site source URL the AI reads facts from. Available on all plans including FREE. Pass the values the user stated. To copy another site's look, get its values first — fetch_url returns the page's prose, not its CSS, so use colours and fonts stated on the page, or ask the user for them; never invent hex values.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"update_branding","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"cta_url":{"description":"Call To Action URL — the ONE page this documentation should drive readers to (pricing, demo booking, signup). https:// only. Treat it as the project's conversion goal: reference it where a page naturally ends in a next step, and surface it as a header button via update_navigation header_links with an accent `color` so it reads as a button rather than a plain link. Pass an empty string to clear it.","type":"string"},"average_product_price_cents":{"description":"What ONE conversion is worth, in CENTS (29900 = $299) — the average revenue from a reader who clicks through to cta_url. The analytics card multiplies it by those readers to report Revenue and Revenue per visitor; without it both stay switched off rather than being guessed. Save it whenever the owner states an average price, order value or plan price. Pass 0 to clear it and switch revenue reporting back off.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"site_source_url":{"description":"Site source — the product's OWN website, the place to read real facts from (pricing, plan names, limits, contacts) instead of inventing them. http(s). Save it as soon as the owner names their website or you fetch one for this project, so later sessions can look facts up there. NOT the same as cta_url (that is a destination for readers; this is an origin for facts). Pass an empty string to clear it.","type":"string"},"logo_url":{"description":"URL for site logo","type":"string"},"icon_url":{"description":"URL for favicon","type":"string"},"custom_name":{"description":"Display name for the docs site","type":"string"},"accent_color":{"description":"Primary accent color as hex (#3b82f6)","type":"string"},"accent_color_dark":{"description":"Accent color for dark mode","type":"string"},"muted_color":{"description":"Muted/secondary color as hex","type":"string"},"muted_color_dark":{"type":"string"},"base_foreground":{"description":"Main text color as hex","type":"string"},"base_foreground_dark":{"type":"string"},"base_background":{"description":"Background color as hex","type":"string"},"base_background_dark":{"type":"string"},"font_family":{"description":"Google Font name for HEADINGS (e.g. 'Inter')","type":"string"},"content_font_family":{"description":"Google Font name for BODY/CONTENT text; falls back to font_family when unset","type":"string"},"default_theme":{"type":"string","enum":["light","dark","system"]},"theme_toggle":{"description":"Show theme toggle to visitors","type":"boolean"},"background_style":{"description":"Visual background style: clean (no effect), muted (soft neutral wash), bold (stronger accent treatment), or gradient (soft radiant glow tied to the accent color — the old background_glow toggle).","type":"string","enum":["clean","muted","bold","gradient"]},"background_glow":{"description":"Legacy on/off toggle — prefer background_style. true sets it to 'gradient'.","type":"boolean"},"search_button_color":{"description":"Custom background color (hex) for the header search bar button. Pass an empty string to clear it back to the default muted background.","type":"string"},"ask_ai_button_color":{"description":"Custom background color (hex) for the header Ask AI button. Pass an empty string to clear it back to the default muted background.","type":"string"}}}}}}}},"/api/v1/update_languages":{"post":{"operationId":"updateLanguages","summary":"Update languages","description":"Set the languages the site is served in — the call for 'we need docs in Spanish and German', «нужна документация на испанском». REQUIRES PRO plan. `enabled_languages` REPLACES the whole set, so pass the existing languages plus the new ones (read them from get_workspace first). Enabling a language does not translate anything by itself: run_translation_pass starts the first pass, and later passes follow the workspace's translation mode. Supported codes: en, es, fr, de, pt, it, ru, zh, ja, ko, ar, hi, tr, pl, nl. Translated pages are served at https://<username>.docsbook.io/<lang>/<repo>/<path> — language is always a PATH SEGMENT under the user subdomain, never a subdomain itself (never https://<lang>.docsbook.io/). `default_language` is the docs' own source language (auto-detected from the repo README when the project is connected) — it is silently dropped from `enabled_languages` if included, since the docs are already written in it and there is nothing to translate.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"update_languages","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled_languages":{"description":"ISO language codes to enable","type":"array","items":{"type":"string"}},"default_language":{"description":"Default language code","type":"string"}}}}}}}},"/api/v1/update_navigation":{"post":{"operationId":"updateNavigation","summary":"Update navigation","description":"Update every curated link on the docs site: header links, social links, FOOTER link columns, folder navigation tabs, left-sidebar page/folder icons, and sidebar label overrides. Available on all plans including FREE. Whether the footer is SHOWN (and its layout, copyright text and CTA) is update_ui_settings — this tool owns what is IN it.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"update_navigation","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"header_links":{"description":"Links shown in the docs header. Full replacement of the set — pass the complete desired list, not a delta. `color` is a hex background that renders the link as a filled button: give it to the workspace's call-to-action link (cta_url from get_workspace / update_branding) and leave it unset on the rest, so exactly one header item reads as the CTA.","type":"array","items":{"type":"object","properties":{"label":{"type":"string"},"url":{"type":"string"},"color":{"type":"string"}},"required":["label","url"]}},"social_links":{"type":"object","properties":{"github":{"type":"string"},"discord":{"type":"string"},"twitter":{"type":"string"},"linkedin":{"type":"string"},"youtube":{"type":"string"},"slack":{"type":"string"}}},"subheader_folders":{"description":"Where each top-level folder of the docs is PLACED. A folder normally has one of two placements, and these flags are how you choose between them:\n• SUBHEADER TAB — a top-level section in the category strip under the header (`inSubheader: true`, `hiddenInSidebar: true`). Selecting the tab scopes the left sidebar to that folder's pages; outside the tab they stay out of the sidebar tree. This is the normal, deliberate arrangement for a LARGE section — a blog, a changelog, a guides or reference set — and it is NOT a misconfiguration waiting to be tidied up.\n• SIDEBAR FOLDER — an ordinary folder in the main sidebar tree (`showInSidebar: true`, `hiddenInSidebar` unset, `inSubheader: false`). No tab; readers expand it in the sidebar.\nget_workspace reports the resolved choice per folder as `placement` (\"subheader_tab\" | \"sidebar_tree\" | \"subheader_tab_and_sidebar_tree\" | \"hidden\") — read that instead of re-deriving it from the three booleans.\nHOW THE THREE COMBINE — two questions, not three settings: (1) is there a tab? `inSubheader`, and nothing else; removing a tab never puts its pages back in the sidebar. (2) are the pages in the ROOT sidebar tree — the tree shown when no tab is active? `showInSidebar` must be true AND `hiddenInSidebar` must not be; `hiddenInSidebar` also drops them from Previous/Next, which `showInSidebar: false` does not. Inside an active tab neither flag applies: a tab always scopes the sidebar to its own folder.\nCOMBINATIONS THAT MEAN NOTHING: `showInSidebar: false` together with `hiddenInSidebar: true` (the root tree already excludes the folder for either reason — the only added effect is Previous/Next); `showInSidebar: true` with `hiddenInSidebar: true` (contradictory, `hiddenInSidebar` wins); any `hiddenInSidebar` on a \"Getting Started\" folder (ignored — it can never be hidden this way). `inSubheader: false` with no root-tree placement leaves the pages reachable only by direct URL or search.\n🔴 DO NOT \"FIX\" A TAB'S `hiddenInSidebar`. Setting it to false on a folder that is a tab repairs nothing: the tab stays, and every page of that folder is MERGED into the root sidebar tree, so the sidebar grows by the whole section and the same pages are reachable twice. Change it only when the owner asks for it.","type":"array","items":{"type":"object","properties":{"folderPath":{"type":"string","description":"Top-level folder path, e.g. '/guides' or 'guides'."},"label":{"type":"string","description":"Tab label. Required when adding a new folder."},"showInSidebar":{"type":"boolean","description":"Do this folder's pages appear in the ROOT sidebar tree — the tree a reader sees when no subheader tab is active? false is the tab-only placement, not a 'hide'. It does NOT control the scoping inside an active tab: a tab always scopes the sidebar to its own folder. Required when adding a new folder."},"openFirstPage":{"description":"Open the folder's first page instead of the folder itself. Defaults to true.","type":"boolean"},"hiddenInSidebar":{"description":"Takes the folder's pages out of the LEFT SIDEBAR tree and out of Previous/Next navigation, leaving the subheader tab untouched. true alongside a tab is the NORMAL way to place a large section (a blog, a changelog) — not a defect: setting it to false merges every page of the folder into the root tree and lengthens the sidebar, so change it only when the owner asks. To remove the TAB instead, use inSubheader: false. Ignored on a 'Getting Started' folder, which can never be hidden this way.","type":"boolean"},"inSubheader":{"description":"Is this folder a tab in the subheader (the category strip under the header)? false removes the tab while keeping the entry's label, icon and sidebar decision. Defaults to true for an entry added here. It says nothing about the sidebar — removing a tab does not put its pages back into the tree.","type":"boolean"},"icon":{"description":"lucide-react icon name in kebab-case (e.g. \"rocket\", \"book-open\"), shown before the tab label. Must be one of: a-arrow-down, a-arrow-up, a-large-small, accessibility, activity, activity-square, air-vent, airplay, alarm-check, alarm-clock, alarm-clock-check, alarm-clock-minus, alarm-clock-off, alarm-clock-plus, alarm-minus, alarm-plus, alarm-smoke, album, alert-circle, alert-octagon, alert-triangle, align-center, align-center-horizontal, align-center-vertical, align-end-horizontal, align-end-vertical, align-horizontal-distribute-center, align-horizontal-distribute-end, align-horizontal-distribute-start, align-horizontal-justify-center, align-horizontal-justify-end, align-horizontal-justify-start, align-horizontal-space-around, align-horizontal-space-between, align-justify, align-left, align-right, align-start-horizontal, align-start-vertical, align-vertical-distribute-center, … (1941 total).","type":"string"}},"required":["folderPath","label","showInSidebar"]}},"sidebar_icons":{"description":"Icons shown next to pages/folders in the left sidebar. Full replacement of the set — pass the complete desired list, not a delta.","type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Page slug (e.g. 'guides/setup') or folder path (e.g. '/guides')"},"icon":{"type":"string","description":"lucide-react icon name in kebab-case (e.g. \"rocket\", \"book-open\"). Must be one of: a-arrow-down, a-arrow-up, a-large-small, accessibility, activity, activity-square, air-vent, airplay, alarm-check, alarm-clock, alarm-clock-check, alarm-clock-minus, alarm-clock-off, alarm-clock-plus, alarm-minus, alarm-plus, alarm-smoke, album, alert-circle, alert-octagon, alert-triangle, align-center, align-center-horizontal, align-center-vertical, align-end-horizontal, align-end-vertical, align-horizontal-distribute-center, align-horizontal-distribute-end, align-horizontal-distribute-start, align-horizontal-justify-center, align-horizontal-justify-end, align-horizontal-justify-start, align-horizontal-space-around, align-horizontal-space-between, align-justify, align-left, align-right, align-start-horizontal, align-start-vertical, align-vertical-distribute-center, … (1941 total — call this tool with an obviously-invalid name once to get the full list back in the error, or ask the user to pick visually in the dashboard)."},"is_folder":{"type":"boolean","description":"true if `path` is a folder, false if it's a page"}},"required":["path","icon","is_folder"]}},"footer_columns":{"description":"The footer's link columns (max 6). Full replacement of the set — pass the complete desired list, not a delta; read the current one from get_workspace `footerColumns`. The footer must also be enabled (update_ui_settings footer_enabled) before a reader sees any of this. Do NOT put social profiles here — they are social_links above, which the footer renders as icons.","type":"array","items":{"type":"object","properties":{"title":{"type":"string","description":"Column heading, e.g. 'Product', 'Company', 'Legal'. Also the column's identity — an empty title is allowed (an untitled column of links) but two columns should not share one."},"links":{"type":"array","items":{"type":"object","properties":{"label":{"type":"string","description":"Link text. Max 60 chars."},"url":{"type":"string","description":"Where it goes: an in-site path ('/pricing'), an absolute URL, or a mailto:/tel:. Other schemes (javascript:, data:) are dropped."}},"required":["label","url"]},"description":"Up to 15 links. A column with no usable links is dropped rather than rendered as a bare heading."}},"required":["title","links"]}},"page_labels":{"description":"Sidebar label overrides. An override changes ONLY the text in the sidebar — never the page's address and never its position in the tree, so no link breaks and nothing is reordered. Use this for 'rename this page in the navigation'; renaming the file itself is a write_docs move, which changes the address (the old one keeps working through the site's redirect map, but links and citations to it become second-hand). Labels are derived from file names, so every README.md renders as \"Introduction\" — this is how several of them get told apart. Overridden labels are still offered for translation, so a renamed page stays localized. Full replacement of the set — pass the complete desired list, not a delta (read the current one from get_workspace `pageLabels`).","type":"array","items":{"type":"object","properties":{"path":{"type":"string","description":"Page slug (e.g. 'guides/setup') or folder path (e.g. '/guides')"},"is_folder":{"type":"boolean","description":"true if `path` is a folder, false if it's a page"},"label":{"type":"string","description":"Text the sidebar shows instead of the file-derived name. Max 120 chars; blank entries are dropped rather than erasing a label."}},"required":["path","is_folder","label"]}}}}}}}}},"/api/v1/update_ui_settings":{"post":{"operationId":"updateUiSettings","summary":"Update ui settings","description":"Show or hide one interface element of the docs site — the header search button, sidebar search, the copy-page menu and its entries, previous/next links, breadcrumbs, scroll-to-top, page feedback, the 'was this helpful' bar, edit-on-GitHub, the Ask AI buttons (header, outline, on selection), copy-as-markdown, and where the language and theme switchers sit. Also the HOME-PAGE LANDING switches (home_hide_sidebar, home_hide_outline, home_wide_content, home_hide_chrome, home_landing_typography), which strip the sidebar, the outline, the column width and the article chrome (breadcrumbs, 'Updated', rating bar, prev/next) off the site's FRONT PAGE ONLY and give its sections landing-page scale so it can read as a landing page — use them for 'make the home page a landing page', 'full-width main page', «сделай главную посадочной», «убери сайдбары на главной». And the SITE FOOTER (whether it exists, its layout, its copyright text, its call-to-action button, and whether it shows the social icons and a theme picker) — 'add a footer', 'put a copyright line at the bottom', «добавь футер». Pass only the toggles the user mentioned; the rest are untouched. Use it for 'hide the search button', 'remove breadcrumbs', «убери кнопку поиска». NOT header links or folder tabs — and NOT the footer's LINK COLUMNS, which are update_navigation's footer_columns. NOT colours or fonts (update_branding). All toggles available on FREE plan.\n\n**Price** — $0.02 per call, charged to the workspace balance, the same as over MCP.","tags":["Settings"],"x-docsbook-tool":"update_ui_settings","x-docsbook-family":"settings","responses":{"200":{"description":"The tool ran. Read `ok` to see whether it succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCallResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"show_search_button":{"description":"The search button in the site header.","type":"boolean"},"show_search_in_sidebar":{"description":"The search box at the top of the left sidebar.","type":"boolean"},"show_copy_page_button":{"type":"boolean"},"show_copy_skills_url":{"description":"Show \"Copy Skills.md URL\" in the Copy page dropdown","type":"boolean"},"show_view_as_markdown":{"description":"Show \"View as Markdown\" in the Copy page dropdown","type":"boolean"},"show_open_in_chatgpt":{"description":"Show \"Open in ChatGPT\" in the Copy page dropdown","type":"boolean"},"show_open_in_claude":{"description":"Show \"Open in Claude\" in the Copy page dropdown","type":"boolean"},"show_open_in_cursor":{"description":"Show \"Open in Cursor\" in the Copy page dropdown","type":"boolean"},"show_open_in_windsurf":{"description":"Show \"Open in Windsurf\" in the Copy page dropdown","type":"boolean"},"show_connect_vscode":{"description":"Show \"Connect to VSCode\" in the Copy page dropdown","type":"boolean"},"show_connect_mcp":{"description":"Show \"Connect MCP\" in the Copy page dropdown — copies a prompt that installs this project's MCP server into any agent","type":"boolean"},"show_prev_next_buttons":{"type":"boolean"},"show_breadcrumbs":{"type":"boolean"},"home_hide_sidebar":{"description":"HOME PAGE ONLY: hide the left navigation rail on the site's front page (its top-level README/index), on desktop — the mobile drawer stays. Every other page keeps its sidebar.","type":"boolean"},"home_hide_outline":{"description":"HOME PAGE ONLY: hide the right-hand \"On this page\" outline on the site's front page.","type":"boolean"},"home_wide_content":{"description":"HOME PAGE ONLY: let the front page's content run the full window width instead of the fixed reading column.","type":"boolean"},"home_hide_chrome":{"description":"HOME PAGE ONLY: remove the article chrome from the front page — the breadcrumb/copy-page bar, the \"Updated\" line, the \"Was this page helpful?\" bar and the previous/next links — so it reads as a landing page, not as page one of a manual.","type":"boolean"},"home_landing_typography":{"description":"HOME PAGE ONLY: landing-page scale for the front page's sections — each h2 becomes a large section title with air above it and the paragraph under it reads as that section's lead. Pair it with hero/stats/cards widgets in the README.","type":"boolean"},"show_scroll_to_top":{"type":"boolean"},"show_page_feedback":{"type":"boolean"},"show_content_feedback":{"type":"boolean"},"show_edit_on_github":{"type":"boolean"},"show_ask_ai_button":{"description":"Show AI chat button (AI must be enabled separately)","type":"boolean"},"show_ask_ai_header":{"type":"boolean"},"show_ask_ai_outline":{"type":"boolean"},"show_ask_ai_on_selection":{"description":"Show floating Ask AI button when user selects text in the docs (AI must be enabled separately)","type":"boolean"},"show_ask_docs_button":{"description":"Floating \"Ask Docs\" pill pinned to the page's bottom-right corner","type":"boolean"},"show_copy_markdown":{"type":"boolean"},"language_in_header":{"type":"boolean"},"theme_in_header":{"type":"boolean"},"language_sidebar_toggle":{"type":"boolean"},"github_edit_base":{"description":"Base URL for Edit on GitHub links","type":"string"},"footer_enabled":{"description":"Show the site footer — the band under every docs page. Off by default. It renders only once it has content: a link column (update_navigation footer_columns), footer_text, a CTA, the logo or the social icons.","type":"boolean"},"footer_layout":{"description":"How the footer's blocks sit: 'columns' (brand block left, link columns right), 'centered' (everything stacked down the middle) or 'minimal' (one row — text left, links and socials right). Placement only; it never turns a block off.","type":"string","enum":["columns","centered","minimal"]},"footer_text":{"description":"Free text under the footer's logo — copyright line, legal entity, postal address. Plain text: line breaks are kept, markup is not. Max 600 chars. Pass an empty string to clear it.","type":"string"},"footer_show_logo":{"description":"Show the site logo in the footer's brand block.","type":"boolean"},"footer_show_socials":{"description":"Show the social icons in the footer. WHICH accounts is not a footer setting — it is the workspace's social_links (update_navigation); this only decides whether the footer draws them.","type":"boolean"},"footer_show_theme_picker":{"description":"Show a three-way light / dark / system picker in the footer.","type":"boolean"},"footer_cta_label":{"description":"Label for an optional call-to-action button in the footer's brand block (e.g. 'Get started'). Without a label no button is drawn. Pass an empty string to remove it.","type":"string"},"footer_cta_url":{"description":"Where the footer's call-to-action button goes. Leave unset to reuse the workspace's own cta_url (see get_workspace) rather than repeating it.","type":"string"}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"dbk_…","description":"Your workspace's API key, from **Integrations** in workspace settings.\n\nThe key reaches your MCP owner surface — orientation, delegating and watching a `docsbook_agent`\njob, reading your own documentation and Docsbook's own docs — plus a narrow, separate list of\nconfiguration settings (branding, navigation, the chatbot, translation mode, mention tracking) each\npublished at its own path below. It does **not** reach documentation writes, translations, webhooks\nor the product's own memory: that catalog is reached by delegating a job to `docsbook_agent`, never\ndirectly over REST. Treat the key as a server-side secret regardless: never ship it in a browser\nbundle or a mobile app. Resetting a key revokes the old one immediately, everywhere."}},"schemas":{"ChatRequest":{"type":"object","required":["question"],"properties":{"question":{"type":"string","description":"What to ask the documentation."},"currentPath":{"type":"string","description":"The page the reader is on, so the answer can prefer nearby context."},"lang":{"type":"string","description":"Answer in this language. Defaults to the workspace's default language."},"sessionId":{"type":"string","description":"Groups several calls as one conversation, the way a multi-turn chat is."},"mentionedPages":{"type":"array","items":{"type":"string"},"description":"Page paths to put in front of the model regardless of what retrieval finds."}}},"ChatResponse":{"type":"object","properties":{"answer":{"type":"string","description":"The answer, in markdown."},"refs":{"type":"array","items":{"type":"object"},"description":"The pages the answer was drawn from."},"follow_up_questions":{"type":"array","items":{"type":"string"}}}},"ToolCallResponse":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","description":"Whether the tool itself succeeded. A tool that ran and refused — an exhausted balance, a plan restriction, a bad argument — answers `200` with `ok: false`: the call was made and billed, and that refusal is its answer."},"result":{"description":"The tool's own JSON answer, already parsed — not a string to parse a second time."},"duration_ms":{"type":"integer","description":"Server-side wall time for the call."}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"Machine-readable error code."},"message":{"type":"string","description":"What went wrong, in one sentence."}}}}}}