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
- Sign in, open the account menu and choose AI connections (MCP). Create an access token (it starts with
bzp_). - Set two environment variables:
export PDF_URL=https://your-host export PDF_TOKEN=bzp_… - 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');
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.