Developer docs

Build on approved documents

VersoDocs exposes the published (Current) version of your organization's documents to code, CI and AI agents. Drafts and proposals in progress never leave VersoDocs. Agents work inside the approval workflow: they propose changes and review proposals (advisory verdicts only), and on Pro can publish a proposal only after people approved it.

Three ways in

REST APIJSON over HTTPS for scripts, internal tools and CI. API key auth, ETags, cursor pagination.MCP server30 tools for Claude Code, Cursor, Copilot and claude.ai. Connect with one click (OAuth) or a key.Agent workflowsAgents review proposals, revise their own, publish approved ones and manage docs & folders, within safety rules.AI reviewersEvery proposal reviewed against your checklist on VersoDocs AI, your own LLM key, or a bot you run. Advisory verdicts.SlackReview notifications in a channel, approve from Slack, link previews and /versodocs search.Microsoft TeamsProposals, verdicts and published versions posted to a channel via a Teams Workflows webhook.GitHub AppA PR check that flags outdated spec references, and approved docs mirrored into your repo.CLI & GitHubPull specs into the repo as Markdown, lock versions, auto-sync PRs, fail CI on spec drift.

All three share one credential system, one per-key rate limit and one plan table, so the same key works everywhere and a limit never differs between surfaces. A machine-readable OpenAPI 3.1 spec describes the REST API.

Quickstart

Create an API key. In VersoDocs, open Organization settings → Developer (owners and admins) and create a key. It starts with vsd_ and is shown once.
Find your org slug: it is the segment after /org/ in any VersoDocs URL (versodocs.com/org/acme/… → acme).
Call the API:

bash

export VERSODOCS_TOKEN=vsd_…
curl -H "Authorization: Bearer $VERSODOCS_TOKEN" \
  "https://versodocs.com/api/v1/orgs/acme/docs?limit=5"

Then read one document as Markdown, by the path shown in its URL:

bash

curl -H "Authorization: Bearer $VERSODOCS_TOKEN" \
  "https://versodocs.com/api/v1/orgs/acme/docs/by-path?path=eng/apis/payments-api&format=md"

Connect an AI agent instead (no key needed: it signs in with OAuth on first use):

bash

claude mcp add --transport http versodocs https://versodocs.com/api/mcp

Or pull specs into a repository:

bash

npx -y @versodocs/cli@0 login --org acme
npx -y @versodocs/cli@0 pull --folder eng/specs --out-dir docs/specs

Authentication

Every request carries Authorization: Bearer <token>. Two credential kinds exist, and both count toward the plan's key limit:

Credential	Prefix	Lifetime	Valid on
API key (Settings → Developer)	`vsd_`	Until revoked	REST API, MCP server, CLI (incl. `versodocs pr-check`)
OAuth access token (one-click MCP connect)	`vsd_at_`	1 hour (refresh token vsd_rt_ rotates, 30 days)	MCP server only (`/api/mcp`); the REST API answers 401

Keys are organization-scoped: the org comes from the credential, and a key used against another org's URL gets 404. Revocation is immediate.

Plan access matrix

Every plan includes API access. Limits are per key (or per connected app) and shared across REST, MCP and the CLI.

	Free	Team	Pro
Active keys + connected apps	1	5	20
Rate limit (per key)	30 req/min	120 req/min	600 req/min
Burst	30 requests	120 requests	300 requests
Scopes (API key)	`docs:read`	`docs:read` `proposals:review`	`docs:read` `docs:propose` `proposals:review` `docs:write` `proposals:publish`
Scopes (one-click connection)	`docs:read`	`docs:read` `docs:propose` `proposals:review`	`docs:read` `docs:propose` `proposals:review` `docs:write` `proposals:publish`
Agent proposals	—	25 / month, one-click connections only	Unlimited, keys and connections
Workspaces visible	The active workspace	All workspaces	All, or one (scoped key)

Feature	Free	Team	Pro	Where
Read Current docs	✓	✓	✓	REST`GET docsGET docs/{documentId}GET docs/by-pathGET webhooksPOST webhooksDELETE webhooks/{webhookId}GET webhooks/samples`MCP`search_docslist_docsget_doccheck_reference`CLI`loginpullstatuscheck`
Version history	—	✓	✓	REST`GET docs/{documentId}/versions?version=N (doc reads)`MCP`list_versions`CLI`pull --version Npull --frozen`
Version diffs	—	✓	✓	REST`GET docs/{documentId}/diff`MCP`diff_versions`CLI`diffcheck (change summary)`
Search	—	✓	✓	REST`GET searchGET docs?q=`
Workspace tree	—	✓	✓	REST`GET tree`MCP`get_doc_tree`
Attachments	—	✓	✓	REST`GET docs/{documentId}/attachmentsGET docs/{documentId}/attachments/{attachmentId}`MCP`list_attachmentsget_attachment_url`
CI spec check	—	✓	✓	REST`GET docs/{documentId}/currentGET docs/current`CLI`pr-check`
Agent context pack + llms.txt	—	✓	✓	REST`GET context-packGET llms.txt`MCP`get_context_pack`
Jira + Linear issue links	—	✓	✓	REST`GET docs/{documentId}/issue-linksPOST docs/{documentId}/issue-linksGET proposals/{proposalId}/issue-linksPOST proposals/{proposalId}/issue-links`MCP`list_linkslink_issue`
Propose changes	—	25 / month, one-click connections only	✓	REST`POST docs/{documentId}/proposalsPOST docs/{documentId}/attachmentsPOST docs/{documentId}/attachments/{attachmentId}/confirm`MCP`propose_changeupload_attachment`
Review proposals	—	✓	✓	REST`GET proposalsGET proposals/{proposalId}POST proposals/{proposalId}/commentsPATCH proposals/{proposalId}/comments/{commentId}GET docs/{documentId}/commentsPOST docs/{documentId}/commentsPATCH docs/{documentId}/comments/{commentId}POST proposals/{proposalId}/reviews`MCP`list_proposalsget_proposalcomment_on_proposalresolve_commentsubmit_reviewlist_document_commentscomment_on_documentresolve_document_comment`
Revise & close agent proposals	—	One-click connections only	✓	REST`PATCH proposals/{proposalId}POST proposals/{proposalId}/close`MCP`update_proposalclose_proposal`
Manage docs & folders	—	—	✓	REST`POST docsPATCH docs/{documentId}DELETE docs/{documentId}POST foldersPATCH folders/{folderId}DELETE folders/{folderId}`MCP`create_doccreate_folderrename_docmove_docdelete_doc`
Publish approved proposals	—	—	✓	REST`POST proposals/{proposalId}/publish`MCP`publish_proposal`
API audit log	—	—	✓	API calls and MCP tool calls are sampled into the org audit log.
Workspace-scoped keys	—	—	✓	Bind a key to a single workspace in Settings → Developer.

A call outside the org's plan returns 403 with code: "plan_feature", the required_plan and an upgrade_url. MCP lists the tools whose scope the credential holds; a plan-locked one returns the same explanation as a tool error. See pricing.

For AI agents

These docs are also published as plain Markdown for LLMs and coding agents, following the llms.txt convention:

/llms.txt: an index of the developer docs and key product pages, with one line per link.
/llms-full.txt: every developer docs page concatenated into one Markdown file.
Each docs page has a Markdown twin at the same URL plus .md: /docs.md, /docs/api.md, /docs/agents.md, /docs/ai-reviewers.md, /docs/slack.md, /docs/teams.md, /docs/github.md, /docs/mcp.md, /docs/cli.md.

To let an agent read your organization's own approved documents, connect it to the MCP server.