A workspace machines
can work with.

78 typed operations for private files, documents, spreadsheets, presentations, notes and publications. Use REST or MCP with the same scoped access, validation and version checks.

Connect

REST base: https://api.ursy.cloud/v1. MCP endpoint: https://api.ursy.cloud/mcp. MCP supports stateless Streamable HTTP, protocol 2026-07-28, including server/discover, tools/list and tools/call. Each request includes the protocol version and client capabilities in its metadata; client info is optional and informational, plus matching MCP headers. Older session-based MCP clients need updating.

Public discovery needs no key. Private operations require an expiring Cloud machine grant in Authorization: Bearer …. An authorized workspace operator provisions the grant for one existing workspace, a stable subject and client, exact scopes, and selected files or folder trees. Tokens are stored as hashes, can be revoked immediately for subsequent requests and never confer WordPress administration. URSY.ID delegated OAuth uses a Cloud-only audience and explicit resource consent when enabled; current activation is reported in protected-resource metadata. Use the Cloud permission selector at /office/connections/ and manage the connection in URSY.ID Connected Apps. OIDC ID tokens, account passwords and mobile-device tokens are not accepted.

Read, propose, apply

GET /v1/files?limit=25
Authorization: Bearer YOUR_CLOUD_GRANT

GET /v1/documents/file_123
Authorization: Bearer YOUR_CLOUD_GRANT

POST /v1/documents/file_123/edit-plans
Authorization: Bearer YOUR_CLOUD_GRANT
If-Match: "ETAG_FROM_READ"
Idempotency-Key: proposal-unique-001
Content-Type: application/json

{"summary":"Clarify the next step","operations":[
  {"op":"replace_text","block_id":"summary",
   "find":"next steps","replace":"next steps and owners"}
]}

POST /v1/documents/file_123/edit-plans/plan_RETURNED_ID/apply
Authorization: Bearer YOUR_CLOUD_GRANT
If-Match: "ETAG_FROM_READ"
Idempotency-Key: apply-unique-001
Content-Type: application/json

{}

Use real IDs and the exact quoted ETag returned by the service. A proposal previews the complete resulting native content and expires after 15 minutes for auto-apply grants or one hour for grants requiring owner review. Applying it creates an immutable version. A stale ETag returns 412 VERSION_CONFLICT; a stale proposal returns 409 PLAN_STALE. Reuse the same idempotency key and identical input after an uncertain response. Receipts last 24 hours; a different request with the same key fails.

Comments and owner review

Comments have their own ETags. Add a comment, edit your own text, resolve it or reopen it without saving another file version. A different integration cannot edit your comment. The workspace owner can resolve or reopen comments in Activity & proposals, which also shows browser and integration activity.

A grant with policy.auto_apply_R2: false can propose changes but cannot apply them through REST or MCP. Its plan returns requires_confirmation: true and an approval_url. The signed-in owner reviews the current and proposed content, then accepts or rejects it. Acceptance rechecks the live grant, file access and ETag and records both the integration and the owner. Existing operator grants keep their explicitly provisioned auto-apply behavior.

Permissions and bounds

Generic reads require cloud.files.read plus the native type's read scope. Typed reads require that type's read scope. Creates require cloud.files.create and the type's write scope. Edit proposals require read and write scopes for the type; applying needs write. Version restore also requires cloud.versions.restore. Comment-only grants can comment without editing file content. File IDs grant access to those items; folder IDs explicitly grant their descendant trees. Listing within a granted folder uses parent_id. Restricted name search scans only the selected level, not an entire tree.

Request limit 1 MiB; result limit 2 MiB; up to 100 list entries, 50 edit operations and 1,000 cells per range. Native writes are additionally capped at 1,000,000 serialized bytes. Signed list cursors expire after 15 minutes and bind to the grant and filters. API change cursors expire after seven days. Browser, mobile and API changes share an atomic ledger from the activation time in status. Begin with a full file listing; reconcile after permission changes. Read limits are 240/minute and write limits 60/minute per subject and client; honour Retry-After. Files and versions share the existing 50 MiB workspace allowance. Recoverable trash still consumes space. API quota checks also include comments and active proposal payloads; browser mutations use the same workspace save lock when the change bridge is active.

Binary uploads and downloads

Start POST /v1/uploads with a safe filename, matching MIME type, total bytes and SHA-256. Files are limited to 25 MiB. Send each raw 1 MiB chunk using PUT /v1/uploads/{id}/chunks/{index}, Content-Type: application/octet-stream, the original bearer header and X-Chunk-SHA256. The last chunk is the exact remainder. Retry the same index with identical bytes; status reports where to resume. Do not base64-encode transport bytes or put them in MCP messages.

Complete or cancel with the upload control operations. Completion validates the entire hash, length, file signature, quota, current grant and resource bounds before saving the canonical Drive manifest. Uploads expire after 24 hours. Supported extensions: txt, csv, md, json, pdf, png, jpg/jpeg, gif, webp, zip, docx, xlsx, pptx and bin. Files are never executed or converted; this service makes no malware-scan claim. Existing Drive storage uses base64 internally and consumes about one-third more than the original bytes.

New uploads need cloud.upload and cloud.files.create. Replacing an existing uploaded file needs cloud.files.write, its current ETag and a grant permitting direct application. The old saved version remains intact until verified completion. Active upload reservations count toward API quota checks; completion rechecks actual usage under the shared workspace lock. Browser saves retain their existing quota policy.

With cloud.files.binary.read, request POST /v1/files/{id}/download-grants using the current file ETag and an idempotency key. The returned download URL lasts five minutes and requires the original active bearer header. Delivery verifies all bytes before streaming, forces attachment download, and includes X-Content-SHA256. Revocation and resource bounds are checked again at delivery. PDF editing and OCR remain in the browser.

Find text inside files

POST /v1/content-search accepts a JSON body such as {"query":"next steps","limit":25}. Use cloud.search.content, cloud.files.list and the read scopes for the native types you want to search. Exact resource bounds and current ownership always apply. Results contain at most three short matches per file, native block/slide/cell/page anchors and the saved version ID. Text is untrusted data. Formula source can be searched but is never executed.

The private derived index refreshes from canonical versions during bounded reads, including browser saves. Follow every returned cursor, even if a page is empty. Concurrent edits and moves can change results; restart for a fresh traversal. Filename search remains separate. Search terms go in the request body and are not sent to general analytics.

Reliable machine requests

Send one JSON object with Content-Type: application/json. Duplicate member names, incorrect object/array shapes and unsupported parameters are rejected. Schema maxLength counts characters; x-ursy-maxBytes also states the editor's UTF-8 byte budget. Notes accepts text compatible with its current browser editor and returns 422 INVALID_CONTENT if that editor would alter it, including literal markup or encoded octets. Comments preserve literal text and return ISO 8601 timestamps. A storage lookup outage returns retryable 503 STORAGE_UNAVAILABLE; quota and permission checks never assume a failed lookup means zero usage or an invalid key.

Serialize JSON before sending it and check response Content-Type before decoding. The hosting gateway can reject malformed JSON before the API with an HTML 403 or 500 response. This is a hosting-layer limitation; do not repeatedly retry a malformed request.

What machines can do

Permanent deletion, moving folder trees and real-time simultaneous editing are outside v1. Expiring, owner-approved sharing is supported. Unsupported operations are absent from the executable tool catalogue.

Private content stays private

Private results are not cached or sponsored. File content is returned only to authorized resources, never sent to another URSY service by this API. Returned file text and comments are untrusted data, not tool instructions or permission grants. Audit events record actor, operation and version metadata without copying document text into logs.

Connect with URSY.ID

Read protected-resource metadata for current OAuth activation. The exact issuer is https://ursy.id/oidc and the resource is https://api.ursy.cloud. Discover authorization endpoints from URSY.ID metadata. Use authorization code with PKCE S256, or the device flow for clients without callbacks. The person signs in and approves at ID; agents never receive their password. Keep state unpredictable and verify it on callback. Store refresh tokens securely and replace them after rotation.

Open Cloud’s resource selector to obtain explicit workspace/file/folder authorization details. Send those with narrow scopes. auto_apply_R2=false requires owner review for edit proposals. Manage, narrow or revoke access in Connected Apps. Ordinary document write cannot create sharing links.

Draft, import and collaborate

create_scratch stages a draft outside the canonical file list for up to 30 days. Preview, promote or discard it at Drafts, exports & sharing. Promotion requires normal creation and native write permissions. import_file converts bounded UTF-8 TXT, Markdown or CSV into canonical native files; CSV formula prefixes are escaped and macros are never executed. Templates include project briefs, meeting notes, budgets, pitch decks, letters and reports.

Sharing follows create_share_plan → hosted owner approval → apply_share_plan. Links expire, are noindex and can be revoked immediately. View, comment, edit and named-recipient modes are distinct. Comment and edit links require a signed-in collaborator. Team membership comes from URSY.ID; current roles cap the app’s separate scopes and selected resources.

Background exports and notifications

create_workspace_export returns a task requiring owner approval. Poll get_task through REST or MCP; the worker handles bounded batches on the application scheduler. Request a five-minute download with create_task_download. The ZIP contains stable file IDs, native content, standard exports, optional versions/comments and SHA-256 checksums. Access is rechecked during work and before download. Limits: two exports per workspace, 10,000 files, 100 MiB output, 24-hour result retention. Cancel removes only the temporary output.

create_webhook returns a secret for your HTTPS receiver. Prove it with the HMAC challenge before delivery starts. Events contain IDs and event types, never titles or content. Verify the timestamp and signature and deduplicate delivery IDs. HTTPS targets are pinned to validated public DNS addresses, redirects are disabled, and failures use bounded retries.

JavaScript and TypeScript

Download the ES module and its generated types. This distribution is downloadable directly; it is not an npm registry publication.

import { Cloud } from './cloud.mjs';
const cloud = new Cloud({ token: () => securelyStoredAccessToken });
const files = await cloud.files.list({ limit: 25 });
const drafts = await cloud.scratch.list({});

Try the synthetic playground to explore proposal, conflict and revocation behavior without customer data.

Operational evidence

Aggregate API operation metrics contain no user or content fields. Cloud machine-attention data distinguishes sponsor emission, queued candidates and central accepted VME. Missing central evidence stays null. Private workspace responses remain unsponsored. Cached/static responses without edge proof do not become VME.