# Build on approved documents

Source: https://versodocs.com/docs

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 API](https://versodocs.com/docs/api.md): JSON over HTTPS for scripts, internal tools and CI. API key auth, ETags, cursor pagination.
- [MCP server](https://versodocs.com/docs/mcp.md): 30 tools for Claude Code, Cursor, Copilot and claude.ai. Connect with one click (OAuth) or a key.
- [Agent workflows](https://versodocs.com/docs/agents.md): Agents review proposals, revise their own, publish approved ones and manage docs & folders, within safety rules.
- [AI reviewers](https://versodocs.com/docs/ai-reviewers.md): Every proposal reviewed against your checklist on VersoDocs AI, your own LLM key, or a bot you run. Advisory verdicts.
- [Slack](https://versodocs.com/docs/slack.md): Review notifications in a channel, approve from Slack, link previews and /versodocs search.
- [Microsoft Teams](https://versodocs.com/docs/teams.md): Proposals, verdicts and published versions posted to a channel via a Teams Workflows webhook.
- [GitHub App](https://versodocs.com/docs/github.md): A PR check that flags outdated spec references, and approved docs mirrored into your repo.
- [CLI & GitHub](https://versodocs.com/docs/cli.md): Pull 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](https://versodocs.com/openapi.json) describes the REST API.

## Quickstart

1. **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.
2. **Find your org slug**: it is the segment after `/org/` in any VersoDocs URL (`versodocs.com/org/acme/…` → `acme`).
3. **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 docs`, `GET docs/{documentId}`, `GET docs/by-path`, `GET webhooks`, `POST webhooks`, `DELETE webhooks/{webhookId}`, `GET webhooks/samples`; MCP: `search_docs`, `list_docs`, `get_doc`, `check_reference`; CLI: `login`, `pull`, `status`, `check` |
| **Version history** | — | ✓ | ✓ | REST: `GET docs/{documentId}/versions`, `?version=N (doc reads)`; MCP: `list_versions`; CLI: `pull --version N`, `pull --frozen` |
| **Version diffs** | — | ✓ | ✓ | REST: `GET docs/{documentId}/diff`; MCP: `diff_versions`; CLI: `diff`, `check (change summary)` |
| **Search** | — | ✓ | ✓ | REST: `GET search`, `GET docs?q=` |
| **Workspace tree** | — | ✓ | ✓ | REST: `GET tree`; MCP: `get_doc_tree` |
| **Attachments** | — | ✓ | ✓ | REST: `GET docs/{documentId}/attachments`, `GET docs/{documentId}/attachments/{attachmentId}`; MCP: `list_attachments`, `get_attachment_url` |
| **CI spec check** | — | ✓ | ✓ | REST: `GET docs/{documentId}/current`, `GET docs/current`; CLI: `pr-check` |
| **Agent context pack + llms.txt** | — | ✓ | ✓ | REST: `GET context-pack`, `GET llms.txt`; MCP: `get_context_pack` |
| **Jira + Linear issue links** | — | ✓ | ✓ | REST: `GET docs/{documentId}/issue-links`, `POST docs/{documentId}/issue-links`, `GET proposals/{proposalId}/issue-links`, `POST proposals/{proposalId}/issue-links`; MCP: `list_links`, `link_issue` |
| **Propose changes** | — | 25 / month, one-click connections only | ✓ | REST: `POST docs/{documentId}/proposals`, `POST docs/{documentId}/attachments`, `POST docs/{documentId}/attachments/{attachmentId}/confirm`; MCP: `propose_change`, `upload_attachment` |
| **Review proposals** | — | ✓ | ✓ | REST: `GET proposals`, `GET proposals/{proposalId}`, `POST proposals/{proposalId}/comments`, `PATCH proposals/{proposalId}/comments/{commentId}`, `GET docs/{documentId}/comments`, `POST docs/{documentId}/comments`, `PATCH docs/{documentId}/comments/{commentId}`, `POST proposals/{proposalId}/reviews`; MCP: `list_proposals`, `get_proposal`, `comment_on_proposal`, `resolve_comment`, `submit_review`, `list_document_comments`, `comment_on_document`, `resolve_document_comment` |
| **Revise & close agent proposals** | — | One-click connections only | ✓ | REST: `PATCH proposals/{proposalId}`, `POST proposals/{proposalId}/close`; MCP: `update_proposal`, `close_proposal` |
| **Manage docs & folders** | — | — | ✓ | REST: `POST docs`, `PATCH docs/{documentId}`, `DELETE docs/{documentId}`, `POST folders`, `PATCH folders/{folderId}`, `DELETE folders/{folderId}`; MCP: `create_doc`, `create_folder`, `rename_doc`, `move_doc`, `delete_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](https://versodocs.com/pricing).

## For AI agents

These docs are also published as plain Markdown for LLMs and coding agents, following the [llms.txt](https://llmstxt.org) convention:

- [/llms.txt](https://versodocs.com/llms.txt): an index of the developer docs and key product pages, with one line per link.
- [/llms-full.txt](https://versodocs.com/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](https://versodocs.com/docs.md), [/docs/api.md](https://versodocs.com/docs/api.md), [/docs/agents.md](https://versodocs.com/docs/agents.md), [/docs/ai-reviewers.md](https://versodocs.com/docs/ai-reviewers.md), [/docs/slack.md](https://versodocs.com/docs/slack.md), [/docs/teams.md](https://versodocs.com/docs/teams.md), [/docs/github.md](https://versodocs.com/docs/github.md), [/docs/mcp.md](https://versodocs.com/docs/mcp.md), [/docs/cli.md](https://versodocs.com/docs/cli.md).

To let an agent read your organization's own approved documents, connect it to the [MCP server](https://versodocs.com/docs/mcp.md).