The Offprint API

Authentication

Create an API key under Settings, API keys and send it as a bearer token. A key can be limited to chosen projects or directories, or to read-only, and it expires when you set it to. The API takes API keys only, not OAuth connections.

Calling an operation

Every operation is POST https://offprint.io/api/v1/<name> with its arguments as a JSON object. The name and arguments are the same as the MCP tool of that name.

curl -X POST https://offprint.io/api/v1/publish_document \
  -H "Authorization: Bearer $OFFPRINT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title": "Release notes", "markdown": "# 2.1\n\nWhat changed…"}'

The response is the same JSON an MCP client receives. A key behaves exactly as it does over MCP: the same restrictions, the same plan limits, and revisions it writes are recorded as written by the key.

Errors

Failures return a JSON body with error and a message that says what to do next.

• 200 — Success. The body is the operation's result.
• 400 — Invalid arguments, or a body that isn't a JSON object.
• 401 — No key, or the key is expired or revoked.
• 403 — The key's access, project restriction, role or plan doesn't allow it. OAuth tokens get this too.
• 404 — Not found, or outside the key's project restriction.
• 409 — The document moved on since expected_revision.
• 429 — A plan limit or daily quota was reached.

OpenAPI

The machine-readable description is at /api/v1/openapi.json, generated from the same definitions the server runs, so it is never out of date. /api/v1 lists the operations as JSON.

Operations

• whoami — Returns the authenticated user's id, handle, and granted scopes for this connection.
• publish_document — Create a new Markdown document.
• update_document — Update a document's content, title, or visibility.
• set_document_url — Change a document's address: a new readable slug, with or without the random suffix.
• get_document — Read a document.
• diff_document — Show what changed between two revisions of a document: the passages added, removed, or reworded, with word counts.
• list_documents — List documents you can access through any membership — owned and shared with you.
• delete_document — Soft-delete a document you own.
• list_comments — List a document's comment threads.
• get_feedback — What reviewers did since you last looked: new comments, replies, and resolved threads, oldest first, for one document or every document in a project.
• reply_to_comment — Reply to a comment thread — pass any comment_id in it; the reply lands at the end of the thread's single flat run of follow-ups.
• resolve_comment — Mark a comment thread resolved.
• request_review — Ask the document's reviewers to approve its current revision.
• get_review_state — Read a document's approval state (draft, in_review, approved, changes_requested), the revision it applies to, and recent review decisions with their notes.
• approve — Approve the current revision of a document that is in review.
• request_changes — Send the current revision of a document in review back with changes requested.
• list_collaborators — List a document's members and their roles (owner, editor, commenter, viewer).
• list_projects — List the projects you can access — your own (Default first) and projects shared with you.
• get_project — Read a project's directory tree and the documents in it (paths, no content).
• create_project — Create a new project of your own.
• create_directory — Create a directory (and any missing parent directories) inside a project.
• move_document — Move a document to another project and/or directory you can write to.