API Guide
The interactive SynckHub server reference includes all registered server routes: reads, writes, uploads, deletes, administrative operations, maintenance, callbacks, and protocol endpoints. Its full OpenAPI JSON and route inventory are generated from pinned server source.
Use the server base URL and credentials from your authenticated SynckHub session. Common and Clearinghouse are backend service boundaries, not additional APIs for application clients to call through this reference.
API families
| Family | Use it for | Documentation |
|---|---|---|
| Platform | Repository items, access rules, search, audit, chat, AI, mail, calendar, cases, and structured data | Platform API guide · Complete reference |
| Uploads and coauthoring | Upload finalization, shared links, Office WOPI, and Yjs | Lifecycle guide |
| Federation | SynckHub-side federation, invites, synchronization, and mounts | Federation guide |
| Repository Integration | Machine authentication and existing read workflows | Integration guide · Profile OpenAPI |
Start with authentication and errors. The reference has one complete server catalog. The legacy integration JSON remains available for existing read clients. For writes, follow upload and revision workflows. A catalog entry does not grant permission: administrative and service operations require their own credentials, and some protocols are mounted only when configured.
Current HTTP and MCP capabilities
This table describes the source contracts used by these guides, not a promise
that every deployment runs that build. The full catalog’s x-source records its
exact backend commit. Check the target server’s release before adopting a route.
Existing MCP tools require per-user OAuth and repository/item permissions;
ordinary HTTP routes require their documented HTTP credentials.
MCP OAuth credentials are restricted to the infrastructure’s /mcp endpoint;
never use them for ordinary HTTP uploads, finalization, blob downloads or Common
APIs. Missing or expired credentials on protected MCP calls return HTTP 401 with
WWW-Authenticate so the client can refresh or reconnect. OAuth token failures
use error/error_description; invalid_grant means the code or refresh grant
cannot be used and may require a new authorization. Other API errors retain
code/message.
Read connections use synckhub.mcp.read. The optional synckhub.mcp.write scope
is granted when connecting and remains limited by the user’s repository and item
permissions. New consent never upgrades an older read-only refresh token. Write
tools support new files and same-file revisions through resumable HTTP byte
transfer. Deployment and partner-client acceptance must be checked separately.
| Capability | SynckHub HTTP | Remote MCP today |
|---|---|---|
| New file / same-file content revision | Bound intent, tus and finish; recipes | Prepare/upload/complete; HTTP byte-transfer capability required |
| Conditional content replacement | Expected persisted head and write identity required | get_file_content_head + prepare_file_revision + complete_file_upload |
| Folder creation, rename, move, metadata, tags | Existing operation-specific routes and permissions | Not exposed |
| Trash/restore, revision restore, named versions, locks, shared links | Existing routes; lifecycle, lock and sharing rules apply | Not exposed |
| Arbitrary file comments | No generic FILE comment API; use existing type-specific comments or Markdown notes | Not exposed |
| Item discovery, search and derived-text reads | Existing reads | Nine read tools; content requires available derived text |
| Original bytes and signed download URL | Independent of text extraction | No download-URL tool |
| PDF OCR | Explicit on-demand image-only PDF workflow | No OCR request tool |
| Audit events | Existing audit authorization required; mutation history also lives in VCS | No audit tool |
| Cases, tasks, calendars, contacts and companies | Existing typed routes | Generic discovery does not provide full typed records |
| Deletion-aware incremental sync / item webhooks | No supported complete delta or item-webhook contract | Not exposed |
| Restricted service tokens / universal Idempotency-Key | Not supported by the current repo-ADMIN token and write contracts | Not supported |
MCP availability does not limit the HTTP catalog. Admin, maintenance and terminal delete routes remain documented with their required authority; they are not ordinary agent capabilities.
API discipline
- authenticate first
- resolve routing context
- send repository requests to the owning SynckHub server
- handle error envelopes deterministically