canonical: https://jentic.com/apis/etherpad.local/etherpad # Etherpad API Jentic publishes the only available OpenAPI specification for Etherpad API, keeping it validated and agent-ready. Etherpad is an open-source real-time collaborative editor that scales to thousands of simultaneous users and runs on the customer's own server. The HTTP API exposes everything the editor exposes in the UI: pads, groups, authors, sessions, chat, content (HTML, text, attributes), and revision history. Most operations are mirrored on both GET and POST verbs, and authentication is a single apikey query parameter scoped to the Etherpad instance. ## For AI agents Create and manage Etherpad pads, groups, sessions, and authors, and read or write their text, HTML, and chat content from a self-hosted collaborative editor. ## Scope Does not handle email delivery, video conferencing, or user identity beyond Etherpad authors - use for pad, group, author, session, content, and chat operations only. ## Capabilities - Create and delete pads, including pads scoped to a group with custom expiry - Read and write pad text, HTML, and Etherpad-specific attributes - Append text or chat messages to a live pad without overwriting existing content - Manage authors and map external user IDs to Etherpad author IDs - Open and revoke sessions that grant authors access to group pads - List pads in a group, list authors of a pad, and list chat history - Generate revision diffs and pad differences in HTML for change tracking ## Use cases ### Meeting note prefill from a calendar event When a meeting is scheduled, a calendar integration calls /createPad with a deterministic pad name, then /setText (or /setHTML) to push a templated agenda into the new pad. The meeting URL points participants directly at the Etherpad instance, so they collaboratively edit the same document during the call. After the meeting, /getText returns the final notes for archiving. Example prompt: POST /createPad with padID 'team-standup-2026-06-10', then POST /setHTML with the rendered agenda template, and finally POST /appendChatMessage to ping participants when the call starts. ### Group-scoped pads for a customer-facing workspace A SaaS product gives each customer a private workspace by calling /createGroupIfNotExistsFor with the customer's external ID, /createAuthorIfNotExistsFor for each user, and /createSession to grant access to the group's pads. New documents are created with /createGroupPad. The session model means individual pads do not need their own ACLs - group membership controls access. Example prompt: POST /createGroupIfNotExistsFor with the customer's external ID, then for each user POST /createAuthorIfNotExistsFor and /createSession, then POST /createGroupPad for each new document. ### Cleanup and archival of stale pads Administrators reduce server load by listing each group's pads via /listPads, fetching last-edit metadata via /getLastEdited, and deleting any pad that hasn't been touched in 90 days with /deletePad. The same flow can archive content first by calling /getHTML and writing the result to object storage before deleting. Example prompt: GET /listPads for each group, then for each padID GET /getLastEdited, archive /getHTML if older than 90 days, and POST /deletePad. ### AI agent summarising a live pad on demand An AI agent in a meeting tool fetches the current pad text via /getText through Jentic, summarises it with an LLM, and writes the summary back as a chat message via /appendChatMessage so participants see it inline. The Etherpad apikey stays in your Jentic One instance, so the agent never sees it directly even when running across multiple Etherpad instances. Example prompt: Search Jentic for 'get Etherpad pad text', execute GET /getText with the padID, summarise the result, then execute POST /appendChatMessage to post the summary into the same pad. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/createPad` | Create a new pad | | POST | `/setText` | Set the text content of a pad | | POST | `/setHTML` | Set the HTML content of a pad | | GET | `/getText` | Get the text content of a pad | | GET | `/getHTML` | Get the HTML content of a pad | | POST | `/appendChatMessage` | Append a chat message to a pad | | POST | `/createGroupPad` | Create a pad inside a group | | POST | `/createSession` | Open a session granting an author access to a group | ## Key resources - **Pads** — Create, copy, move, delete, and read content from pads - **Pad Content** — Get and set text, HTML, attributes, and append text or chat messages - **Groups** — Create groups, list their pads, and delete groups - **Authors** — Create authors and map external user IDs to Etherpad author IDs - **Sessions** — Open and revoke sessions to grant access to group pads - **Chat** — Read and append chat messages on pads - **Revisions** — Generate diffs, list revisions, and inspect change history ## Why Jentic - **Setup:** Wiring the Etherpad API by hand means passing the apikey as a query parameter on every call, pointing at your own Etherpad host, and sorting the pad, group, author, session, and chat operations yourself. Through Jentic you install once, import the Etherpad API from the API Directory, store the apikey once, and your agent calls it. - **Permission scoping:** The Etherpad API identifies pads and groups by query parameter rather than a URL-path resource, so scope the agent to the operations it needs, such as creating a pad or reading its text. You choose which operations are allowed, so a write like setText is not included unless you add it. - **Credential handling:** Your Etherpad apikey is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create a pad' or 'append a chat message to a pad', and Jentic returns the matching Etherpad operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **EspoCRM REST API** — EspoCRM holds the customer record that an Etherpad workspace is created for. - **Freshdesk API** — Freshdesk tickets can link to a dedicated Etherpad pad for collaborative resolution notes. - **Estimate Rocket API** — Estimate Rocket projects can pair with an Etherpad pad for shared site notes. ## FAQ ### Why is there no official OpenAPI spec for Etherpad API? The Etherpad project documents its HTTP API in markdown reference pages but does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Etherpad API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Etherpad API use? Etherpad uses a single apikey passed as a query parameter named 'apikey'. The key is stored in APIKEY.txt on the Etherpad server. Through Jentic, the apikey is held encrypted in the vault and the agent only ever holds a scoped execution token. ### Can I append text to a live pad without overwriting it? Yes - POST /appendText adds content to the end of an existing pad without disturbing the current text. There is also POST /appendChatMessage for adding a chat message into the pad's chat panel rather than the document body. ### What are the rate limits for the Etherpad API? Because Etherpad is self-hosted, there is no vendor-imposed rate limit; capacity is bounded by the server you run it on and any reverse-proxy limits you put in front of it. For bulk imports use the dedicated content-setting endpoints (/setText, /setHTML) once per pad rather than appending repeatedly. ### How do I create a new pad through Jentic? Search Jentic for 'create an Etherpad pad'. Jentic returns POST /createPad with the padID and optional initial-text schema. Execute it; if you want pretty content rather than plain text, follow up with POST /setHTML using the same padID. ### Why are most operations available on both GET and POST? Etherpad's HTTP API was designed for embedding in environments where some clients can only issue GET requests. Both verbs accept the same query parameters and produce the same response, so for write operations you should still prefer POST in any new integration. ### Can I limit what my agent is allowed to do with the Etherpad API? Yes. Because you run Jentic One yourself, your own rules decide which Etherpad operations the agent may call and which credentials it can use. You can allow only the operations a task needs, such as GET /getText to read a pad or POST /createPad to make one, and leave writes like POST /setText or POST /deletePad out unless you explicitly add them. Since Etherpad identifies pads and groups by query parameter rather than a URL path, this per-operation allowlist is how you keep an agent read-only or bound to a narrow set of actions.