Beezifi PDF for developers

Upload PDFs, read their text, comment on them, fill in forms, organize pages, redact, protect, sign and export, from your own code or an AI assistant. Every change runs through the same command engine as the editor, so anyone with the document open sees it happen.

Quickstart

  1. Sign in, open the account menu and choose AI connections (MCP). Create an access token (it starts with bzp_).
  2. Set two environment variables:
    export PDF_URL=https://your-host
    export PDF_TOKEN=bzp_…
  3. Upload a PDF and highlight a phrase:
    curl -s -X POST "$PDF_URL/api/documents/import" \
      -H "Authorization: Bearer $PDF_TOKEN" -F "files=@contract.pdf"
    # → {"id":"…","title":"contract","pages":12}
    
    curl -s -X POST "$PDF_URL/api/documents/$ID/mark-text" \
      -H "Authorization: Bearer $PDF_TOKEN" -H "Content-Type: application/json" \
      -d '{"query":"termination","type":"highlight","contents":"Check notice period"}'
    
    curl -s "$PDF_URL/api/documents/$ID/export?format=pdf" \
      -H "Authorization: Bearer $PDF_TOKEN" -o reviewed.pdf

Authentication

Send Authorization: Bearer <token> with every request. Use a personal access token (bzp_…) for scripts and assistants, or the session token POST /auth/login returns. Tokens act as you: they can open what you can open, with your role in each document (viewer, commenter, editor or owner). Tokens are stored only as SHA-256 hashes and can be revoked at any time; an access token cannot create more tokens.

Core concepts

  • Documents are made of pages. Each page comes from an uploaded PDF (a source file, stored once and never changed) or is blank, and has a rotation and an optional crop.
  • Everything added to a page is an item: comments (notes, highlights, shapes, ink, stamps, measurements…) and content (text, pictures, links, form fields, Fill & Sign marks, redaction marks, recognized text).
  • Positions are PDF points (1/72 inch) from the top-left corner of the page as stored, before rotation and cropping. A US Letter page is 612 × 792.
  • Pages are referenced by 1-based number or by id. Ids stay the same when pages move.
  • Commands are the only way a document changes. They are validated, ordered by the server and undoable in the editor.
  • Downloads are standard PDFs: comments become PDF annotations with appearances, fields are AcroForm fields, bookmarks and page labels are written into the catalog.

Errors

Errors are JSON: {"error": "…", "code": "forbidden", "requestId": "…"}. Codes: invalid_request (400), unauthorized (401; also password_required or password_incorrect when an uploaded PDF needs its password), forbidden (403: your role, or the PDF's own security settings), not_found (404), payload_too_large (413), rate_limited (429).

Rate limits

600 requests a minute per token by default (the server's API_RATE_LIMIT), and 240 a minute for MCP. Uploads up to 100 MB per file and 3000 pages per document by default. OCR handles up to 5 pages per request.

SDKs

Both SDKs wrap the REST API with retries, typed errors and helpers for common jobs.

JavaScript / TypeScript

import { BeezifiPdf } from '@beezifi/pdf';
const pdf = new BeezifiPdf();                       // reads PDF_URL and PDF_TOKEN
const doc = await pdf.documents.upload('contract.pdf');
await doc.highlight('termination', { comment: 'Check notice period' });
await doc.fill({ 'Full name': 'Ada Lovelace', Agree: true });
await doc.download('pdf', 'reviewed.pdf');

Download @beezifi/pdf 1.0.0

Python

from beezifi_pdf import BeezifiPdf
pdf = BeezifiPdf()
doc = pdf.documents.upload("contract.pdf")
doc.highlight("termination", comment="Check notice period")
doc.download("pdf", "reviewed.pdf")

Download beezifi-pdf for Python 1.0.0

Other languages

Generate a client from the OpenAPI 3.1 spec, or call the endpoints directly.

Guide: review a PDF

POST /documents/{id}/mark-text   {"query":"net 30","type":"underline","contents":"Should be net 45"}
POST /documents/{id}/commands    {"commands":[
  {"id":"item.add","params":{"page":1,"item":{"type":"note","x":520,"y":40,"contents":"Summary on page 3"}}},
  {"id":"item.add","params":{"page":3,"item":{"type":"stamp","stamp":"Approved","x":400,"y":680,"w":170,"h":56}}},
  {"id":"comment.reply","params":{"id":"<comment id>","text":"Agreed"}},
  {"id":"comment.status","params":{"id":"<comment id>","status":"Accepted"}}]}
GET  /documents/{id}/export?format=comments-html    # a printable summary of every comment

Guide: fill in forms

GET  /documents/{id}/summary          # "fields": [{name, type, value, options…}]
POST /documents/{id}/commands         {"commands":[{"id":"form.set","params":{"values":{"Full name":"Ada Lovelace","Agree":true}}}]}
POST /documents/{id}/form/detect      # turn blanks and boxes into fields
GET  /documents/{id}/export?format=pdf&flatten=fields

Guide: files in and out

POST /documents/import      files=@a.pdf files=@b.jpg mode=combine     # one document
POST /documents/combine     {"documents":[{"id":"…"},{"id":"…","pages":"1-3"}]}
POST /documents/{id}/split  {"every":10,"output":"zip"}
POST /documents/{id}/export {"format":"pdf","encrypt":{"userPassword":"open","ownerPassword":"owner","permissions":{"print":true,"modify":false}}}
GET  /documents/{id}/export?format=docx   # or pptx, html, md, txt, rtf, png, jpeg, images, xfdf, fdf

REST API

Generated from openapi.json. Base URL: /api.

Loading the reference…

Realtime events

Connect to wss://your-host/ws?id=<document id>&token=<token> to follow a document live. The first message is init with the whole document; then every change arrives as op with the command that made it, in the server's order. Other messages: join, leave and sel (who is looking at which page and items), saved, reload (after a version restore or redaction) and reject.

{"type":"op","seq":42,"user":{"id":7,"name":"Maya Chen"},"cmd":{"id":"item.add","params":{…}}}

Commands

Every command the editor and the API run. Send them to POST /documents/{id}/commands.

Loading…

Names and options

Accepted values for item types, stamps, paper sizes, redaction patterns, fonts and OCR languages, from GET /options.

Loading…

MCP for AI assistants

Beezifi PDF hosts a Model Context Protocol server at POST /mcp (stateless Streamable HTTP). Create a token in the app (account menu › AI connections), then:

claude mcp add --transport http beezifi-pdf https://your-host/mcp --header "Authorization: Bearer bzp_…"

Tools: list_documents, get_document, read_page, render_page, find_text, create_document, add_comment (highlight a phrase just by naming it), list_comments, reply_to_comment, list_form_fields, fill_form, organize_pages, extract_pages, combine_documents, set_bookmarks, set_metadata, redact, ocr_pages, compare_documents, check_accessibility, export_text, export_pdf, run_commands, list_commands and save_version. Each runs as the token's user with the same access checks as the app; comments are credited to "Name (AI)".

Changelog

1.0.0 · First release: documents, pages, comments, forms, bookmarks, labels, page marks, attachments, redaction, encryption, digital signatures, OCR, compare, exports, realtime and MCP.

Support

Write to support@beezifi.com. Include the requestId from the error response.