POST
add_comment
/v1/files/{file_id}/commentsComment without altering a file; a comment-only grant needs no edit scope.
APIs
URSY.cloud Machine API
Typed private workspace resources. URSY.ID delegated access is advertised when enabled in protected-resource metadata. Operator grants remain supported. Conditional writes use If-Match; JSON mutations require Idempotency-Key. Raw chunk PUT is idempotent by upload ID, index and hash. Resource/type scopes are documented in the capability catalogue.
Contract
- Version
- 1.8.3
- Base URL
https://api.ursy.cloud- Published source
- OpenAPI ↗
Endpoints are extracted from this version. Original snapshots are retained when a source changes.
Authentication
Requirements are recorded per operation. An API can contain both public and protected endpoints.
Read the authentication guide →Endpoints
POST
apply_document_edit
/v1/documents/{file_id}/edit-plans/{plan_id}/applyApply the exact document proposal after checking its base version.
POST
apply_file_edit
/v1/files/{file_id}/edit-plans/{plan_id}/applyApply this grant’s unexpired proposal only if the base ETag still matches.
POST
apply_note_edit
/v1/notes/{file_id}/edit-plans/{plan_id}/applyApply the exact note proposal after checking its base version.
POST
apply_presentation_edit
/v1/presentations/{file_id}/edit-plans/{plan_id}/applyApply the exact presentation proposal after checking its base version.
POST
apply_publication_edit
/v1/publications/{file_id}/edit-plans/{plan_id}/applyApply the exact publication proposal after checking its base version.
POST
apply_share_plan
/v1/files/{file_id}/share-plans/{share_plan_id}/applyApply the unchanged, explicitly approved plan; rechecks current permissions and ETag.
POST
apply_spreadsheet_edit
/v1/spreadsheets/{file_id}/edit-plans/{plan_id}/applyApply the exact spreadsheet proposal after checking its base version.
POST
cancel_task
/v1/tasks/{task_id}/cancelCancel a task and remove its temporary result; saved files remain intact.
POST
cancel_upload
/v1/uploads/{upload_id}/cancelDiscard only uncommitted staging chunks. Completed saved versions are preserved.
POST
complete_upload
/v1/uploads/{upload_id}/completeVerify length, MIME, hash and quota, then save a canonical Drive file/version.
POST
Inspect create_documentPOST
create_download_grant
/v1/files/{file_id}/download-grantsAuthorize a five-minute binary download of the exact current manifest. The original bearer is required at delivery.
POST
Inspect create_filePOST
Inspect create_notePOST
create_presentation
/v1/presentationsCreate a private native presentation with immutable initial version.
POST
create_publication
/v1/publicationsCreate a private native publication with immutable initial version.
POST
create_scratch
/v1/scratchCreate a private draft outside the canonical file list. Expires after 30 days.
POST
create_share_plan
/v1/files/{file_id}/share-plansPropose one expiring share for the exact file version. Owner approval is always required.
POST
create_spreadsheet
/v1/spreadsheetsCreate a private native spreadsheet with immutable initial version.
POST
create_task_download
/v1/tasks/{task_id}/downloadAuthorize five-minute private ZIP delivery using this same current grant.
POST
create_team
/v1/teamsBind the owner’s current canonical workspace to an ID-owned organisation. Existing files retain IDs and versions.
POST
create_upload
/v1/uploadsBegin a private raw-byte upload. New files need files.create; replacement needs files.write, current ETag and an auto-apply policy.
POST
create_webhook
/v1/webhooksRegister an HTTPS receiver; prove the returned secret before events are sent. Receives IDs only, never file text or names.
POST
create_workspace_export
/v1/workspace-exportsQueue an export of currently authorised resources after explicit owner approval. Includes integrity manifest; optional versions/comments require their read scopes.
DELETE
Inspect discard_scratchGET
download_binary
/v1/downloads/{download_id}/contentVerified attachment bytes. Requires the original still-active grant and an unexpired download record. A URL alone authorizes nothing. HEAD returns the same headers without bytes.
GET
download_workspace_export
/v1/tasks/{task_id}/contentPrivate ZIP with per-entry checksums. Original active grant and five-minute authorization required.
GET
export_file
/v1/files/{file_id}/exportExport one bounded native file to JSON, text, Markdown or CSV when supported.
GET
get_api_metrics
/v1/metricsRead seven-day aggregate operation/status/duration counters, without user or content data.
GET
get_changes
/v1/changesRead authorized mutation events; status reports browser coverage and its activation time.
GET
get_edit_plan
/v1/files/{file_id}/edit-plans/{plan_id}Read a proposal made by this grant, including bounded preview and expiry.
GET
Inspect get_file_metadataGET
Inspect get_schemaGET
Inspect get_scratchGET
Inspect get_service_infoGET
get_share_plan
/v1/files/{file_id}/share-plans/{share_plan_id}Read a pending share proposal and its hosted approval URL.
GET
Inspect get_statusGET
get_task
/v1/tasks/{task_id}Read background task status and progress. Queued means approval received and waiting for the ordinary worker.
GET
get_upload
/v1/uploads/{upload_id}Read resumable upload status; the original grant and current resource bounds are required.
POST
import_file
/v1/importsImport bounded UTF-8 TXT, Markdown or CSV as a new native file. CSV formulas become literal text.
GET
Inspect list_appsGET
Inspect list_capabilitiesGET
Inspect list_commentsGET
Inspect list_filesGET
Inspect list_formatsGET
Inspect list_scratchGET
Inspect list_sharesGET
Inspect list_tasksGET
list_team_memberships
/v1/team-membershipsRead current URSY.ID organisations and roles for the authenticated Cloud subject.
GET
list_templates
/v1/templatesRead deterministic native templates for a document, note, budget and deck.
GET
list_versions
/v1/files/{file_id}/versionsList immutable version metadata with bounded cursor pagination.
GET
list_webhooks
/v1/webhooksList this grant’s notification subscriptions, verification state and delivery failures.
GET
Inspect list_workspacesPOST
promote_scratch
/v1/scratch/{draft_id}/promoteCreate a canonical file from the exact draft; needs creation, native write and destination access.
POST
propose_document_edit
/v1/documents/{file_id}/edit-plansPropose typed document edits with version safety.
POST
propose_file_edit
/v1/files/{file_id}/edit-plansPreview typed edits bound to the current ETag; does not alter the file.
POST
Inspect propose_note_editPOST
propose_presentation_edit
/v1/presentations/{file_id}/edit-plansPropose typed presentation edits with version safety.
POST
propose_publication_edit
/v1/publications/{file_id}/edit-plansPropose typed publication edits with version safety.
POST
propose_spreadsheet_edit
/v1/spreadsheets/{file_id}/edit-plansPropose typed spreadsheet edits with version safety.
PUT
put_upload_chunk
/v1/uploads/{upload_id}/chunks/{index}Raw binary transport; send exactly one chunk with its SHA-256. Retry the same index with identical bytes. Control operations are also available through MCP.
GET
Inspect read_documentGET
read_file
/v1/files/{file_id}/contentRead a bounded native content snapshot. Uploaded binary chunks are not returned.
GET
Inspect read_noteGET
read_presentation
/v1/presentations/{file_id}Read the authorized native presentation and current ETag.
GET
Inspect read_publicationGET
read_sheet_range
/v1/spreadsheets/{file_id}/ranges/{range}Read up to 1,000 cells from the stored grid; formulas are source text, not server-recalculated values.
GET
Inspect read_spreadsheetGET
read_version
/v1/files/{file_id}/versions/{version_id}Read one authorized native historical version and its provenance.
POST
reopen_comment
/v1/files/{file_id}/comments/{comment_id}/reopenReopen your own resolved comment with its current comment ETag.
POST
resolve_comment
/v1/files/{file_id}/comments/{comment_id}/resolveResolve your own comment without changing the file.
POST
restore_version_plan
/v1/files/{file_id}/restore-plansPropose a historical native version as a new version; preserves history.
DELETE
Inspect revoke_shareDELETE
Inspect revoke_webhookPOST
search_content
/v1/content-searchSearch text inside authorized native files; JSON body keeps terms out of URL logs. Requires files.list and each returned type read scope.
GET
Inspect search_workspaceDELETE
trash_file
/v1/files/{file_id}Move one file to recoverable trash with its current ETag; folders with children are rejected.
PATCH
update_comment
/v1/files/{file_id}/comments/{comment_id}Edit your own comment with its current comment ETag.
PATCH
update_file_metadata
/v1/files/{file_id}Rename or move a file with its current ETag; identity remains stable.
POST
update_team_member
/v1/teams/{organisation_id}/members/{subject}Change an ID-owned membership with optimistic version safety; roles cap every subsequent API request.
Inspect the accepted OpenAPI document
{
"openapi": "3.1.0",
"info": {
"title": "URSY.cloud Machine API",
"version": "1.8.3",
"description": "Typed private workspace resources. URSY.ID delegated access is advertised when enabled in protected-resource metadata. Operator grants remain supported. Conditional writes use If-Match; JSON mutations require Idempotency-Key. Raw chunk PUT is idempotent by upload ID, index and hash. Resource/type scopes are documented in the capability catalogue."
},
"servers": [
{
"url": "https://api.ursy.cloud"
},
{
"url": "https://ursy.cloud/api"
}
],
"paths": {
"/v1/service": {
"get": {
"operationId": "get_service_info",
"description": "Describe the supported Cloud machine API and authentication.",
"security": [],
"x-required-scope": null,
"x-resource-bounds-enforced": true,
"x-risk": "R0",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/service/v1"
]
},
"name": {
"type": "string"
},
"version": {
"type": "string"
},
"api": {
"type": "string",
"pattern": "^https://"
},
"mcp": {
"type": "string",
"pattern": "^https://"
},
"openapi": {
"type": "string",
"pattern": "^https://"
},
"developer_manifest": {
"type": "string",
"pattern": "^https://"
},
"authentication": {
"type": "object",
"additionalProperties": false,
"properties": {
"mode": {
"type": "string"
},
"identity_authority": {
"type": "string",
"pattern": "^https://"
},
"delegated_oauth_ready": {
"type": "boolean"
},
"provisioning": {
"type": "string"
}
},
"required": [
"mode",
"identity_authority",
"delegated_oauth_ready",
"provisioning"
]
},
"privacy": {
"type": "object",
"additionalProperties": false,
"properties": {
"private_results_sponsored": {
"type": "boolean"
},
"private_content_in_ad_telemetry": {
"type": "boolean"
},
"private_responses_cacheable": {
"type": "boolean"
}
},
"required": [
"private_results_sponsored",
"private_content_in_ad_telemetry",
"private_responses_cacheable"
]
},
"limits": {
"type": "object",
"additionalProperties": false,
"properties": {
"upload_bytes": {
"type": "integer",
"minimum": 0
},
"upload_chunk_bytes": {
"type": "integer",
"minimum": 0
},
"upload_session_seconds": {
"type": "integer",
"minimum": 0
},
"download_grant_seconds": {
"type": "integer",
"minimum": 0
},
"request_bytes": {
"type": "integer",
"minimum": 0
},
"response_bytes": {
"type": "integer",
"minimum": 0
},
"list_page": {
"type": "integer",
"minimum": 0
},
"sheet_range_cells": {
"type": "integer",
"minimum": 0
},
"edit_operations": {
"type": "integer",
"minimum": 0
},
"grant_max_seconds": {
"type": "integer",
"minimum": 0
},
"reads_per_minute": {
"type": "integer",
"minimum": 0
},
"writes_per_minute": {
"type": "integer",
"minimum": 0
},
"idempotency_seconds": {
"type": "integer",
"minimum": 0
},
"edit_plan_seconds": {
"type": "integer",
"minimum": 0
},
"review_plan_seconds": {
"type": "integer",
"minimum": 0
},
"list_cursor_seconds": {
"type": "integer",
"minimum": 0
},
"change_cursor_seconds": {
"type": "integer",
"minimum": 0
},
"rate_limit_key": {
"type": "string"
}
},
"required": [
"upload_bytes",
"upload_chunk_bytes",
"upload_session_seconds",
"download_grant_seconds",
"request_bytes",
"response_bytes",
"list_page",
"sheet_range_cells",
"edit_operations",
"grant_max_seconds",
"reads_per_minute",
"writes_per_minute",
"idempotency_seconds",
"edit_plan_seconds",
"review_plan_seconds",
"list_cursor_seconds",
"change_cursor_seconds",
"rate_limit_key"
]
},
"storage_quota_bytes": {
"type": "integer",
"minimum": 0
},
"unsupported": {
"type": "array",
"items": {
"type": "string"
}
},
"request_id": {
"type": "string"
}
},
"required": [
"schema",
"name",
"version",
"api",
"mcp",
"openapi",
"developer_manifest",
"authentication",
"privacy",
"limits",
"storage_quota_bytes",
"unsupported"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/apps": {
"get": {
"operationId": "list_apps",
"description": "List seven apps with actual machine and browser execution boundaries.",
"security": [],
"x-required-scope": null,
"x-resource-bounds-enforced": true,
"x-risk": "R0",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"apps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"enum": [
"drive",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf"
]
},
"name": {
"type": "string"
},
"browser_status": {
"type": "string"
},
"machine_status": {
"type": "string"
},
"private": {
"type": "boolean"
},
"url": {
"type": "string",
"pattern": "^https://"
}
},
"required": [
"id",
"name",
"browser_status",
"machine_status",
"private",
"url"
]
},
"minItems": 7,
"maxItems": 7
},
"request_id": {
"type": "string"
}
},
"required": [
"apps"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/formats": {
"get": {
"operationId": "list_formats",
"description": "List native schemas, export formats and editor limitations.",
"security": [],
"x-required-scope": null,
"x-resource-bounds-enforced": true,
"x-risk": "R0",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"formats": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"document"
]
},
"native": {
"type": "string"
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"exports": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "string"
}
},
"required": [
"type",
"native",
"schema",
"exports",
"limit"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"spreadsheet"
]
},
"native": {
"type": "string"
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"exports": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "string"
}
},
"required": [
"type",
"native",
"schema",
"exports",
"limit"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"presentation"
]
},
"native": {
"type": "string"
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"exports": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "string"
}
},
"required": [
"type",
"native",
"schema",
"exports",
"limit"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"note"
]
},
"native": {
"type": "string"
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"exports": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "string"
}
},
"required": [
"type",
"native",
"schema",
"exports",
"limit"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"publication"
]
},
"native": {
"type": "string"
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"exports": {
"type": "array",
"items": {
"type": "string"
}
},
"limit": {
"type": "string"
}
},
"required": [
"type",
"native",
"schema",
"exports",
"limit"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"pdf"
]
},
"machine_processing": {
"type": "boolean"
},
"browser_operations": {
"type": "array",
"items": {
"type": "string"
}
},
"server_ocr": {
"type": "boolean"
}
},
"required": [
"type",
"machine_processing",
"browser_operations",
"server_ocr"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"uploaded_file"
]
},
"machine_content_read": {
"type": "boolean"
},
"metadata": {
"type": "boolean"
},
"max_original_bytes": {
"type": "integer",
"minimum": 0
}
},
"required": [
"type",
"machine_content_read",
"metadata",
"max_original_bytes"
]
}
]
},
"minItems": 7,
"maxItems": 7
},
"csv_export_formula_policy": {
"type": "string"
},
"request_id": {
"type": "string"
}
},
"required": [
"formats",
"csv_export_formula_policy"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/status": {
"get": {
"operationId": "get_status",
"description": "Read API build and authorization availability; contains no private usage.",
"security": [],
"x-required-scope": null,
"x-resource-bounds-enforced": true,
"x-risk": "R0",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/status/v1"
]
},
"status": {
"type": "string",
"enum": [
"operational",
"degraded",
"maintenance"
]
},
"authentication": {
"type": "string"
},
"version": {
"type": "string"
},
"operation_count": {
"type": "integer",
"minimum": 0
},
"mcp_protocol": {
"type": "string"
},
"authentication_modes": {
"type": "array",
"items": {
"type": "string"
}
},
"delegated_oauth_ready": {
"type": "boolean"
},
"private_sponsorship": {
"type": "boolean"
},
"change_feed": {
"type": "object",
"additionalProperties": false,
"properties": {
"coverage": {
"type": "string"
},
"legacy_browser_changes_included": {
"type": "boolean"
},
"cursor_lifetime_seconds": {
"type": "integer",
"minimum": 0
},
"coverage_since": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"resync_guidance": {
"type": "string"
}
},
"required": [
"coverage",
"legacy_browser_changes_included",
"cursor_lifetime_seconds",
"coverage_since",
"resync_guidance"
]
},
"comment_lifecycle": {
"type": "boolean"
},
"human_proposal_review": {
"type": "boolean"
},
"uploads": {
"type": "boolean"
},
"binary_downloads": {
"type": "boolean"
},
"content_search": {
"type": "boolean"
},
"sharing": {
"type": "boolean"
},
"tasks": {
"type": "boolean"
},
"scratch": {
"type": "boolean"
},
"imports": {
"type": "boolean"
},
"webhooks": {
"type": "boolean"
},
"teams": {
"type": "boolean"
},
"sdk": {
"type": "boolean"
},
"limits": {
"type": "object",
"additionalProperties": false,
"properties": {
"upload_bytes": {
"type": "integer",
"minimum": 0
},
"upload_chunk_bytes": {
"type": "integer",
"minimum": 0
},
"upload_session_seconds": {
"type": "integer",
"minimum": 0
},
"download_grant_seconds": {
"type": "integer",
"minimum": 0
},
"request_bytes": {
"type": "integer",
"minimum": 0
},
"response_bytes": {
"type": "integer",
"minimum": 0
},
"list_page": {
"type": "integer",
"minimum": 0
},
"sheet_range_cells": {
"type": "integer",
"minimum": 0
},
"edit_operations": {
"type": "integer",
"minimum": 0
},
"grant_max_seconds": {
"type": "integer",
"minimum": 0
},
"reads_per_minute": {
"type": "integer",
"minimum": 0
},
"writes_per_minute": {
"type": "integer",
"minimum": 0
},
"idempotency_seconds": {
"type": "integer",
"minimum": 0
},
"edit_plan_seconds": {
"type": "integer",
"minimum": 0
},
"review_plan_seconds": {
"type": "integer",
"minimum": 0
},
"list_cursor_seconds": {
"type": "integer",
"minimum": 0
},
"change_cursor_seconds": {
"type": "integer",
"minimum": 0
},
"rate_limit_key": {
"type": "string"
}
},
"required": [
"upload_bytes",
"upload_chunk_bytes",
"upload_session_seconds",
"download_grant_seconds",
"request_bytes",
"response_bytes",
"list_page",
"sheet_range_cells",
"edit_operations",
"grant_max_seconds",
"reads_per_minute",
"writes_per_minute",
"idempotency_seconds",
"edit_plan_seconds",
"review_plan_seconds",
"list_cursor_seconds",
"change_cursor_seconds",
"rate_limit_key"
]
},
"status_meaning": {
"type": "string"
},
"request_id": {
"type": "string"
}
},
"required": [
"schema",
"status",
"authentication",
"version",
"operation_count",
"mcp_protocol",
"authentication_modes",
"delegated_oauth_ready",
"private_sponsorship",
"change_feed",
"comment_lifecycle",
"human_proposal_review",
"uploads",
"binary_downloads",
"content_search",
"sharing",
"tasks",
"scratch",
"imports",
"webhooks",
"teams",
"sdk",
"limits",
"status_meaning"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/capabilities": {
"get": {
"operationId": "list_capabilities",
"description": "Read typed operations, scopes, risks and input schemas.",
"security": [],
"x-required-scope": null,
"x-resource-bounds-enforced": true,
"x-risk": "R0",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/capabilities/v1"
]
},
"capabilities": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string"
},
"method": {
"type": "string",
"enum": [
"GET",
"POST",
"PATCH",
"DELETE"
]
},
"path": {
"type": "string"
},
"description": {
"type": "string"
},
"scope": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"write": {
"type": "boolean"
},
"risk": {
"type": "string",
"enum": [
"R0",
"R1",
"R2",
"R3",
"R4"
]
},
"inputSchema": {
"type": "object",
"additionalProperties": true,
"description": "A JSON Schema 2020-12 document; vocabulary keywords are extensible."
},
"outputSchema": {
"type": "object",
"additionalProperties": true,
"description": "A JSON Schema 2020-12 document; vocabulary keywords are extensible."
},
"family": {
"type": "string"
},
"kind": {
"type": "string"
}
},
"required": [
"name",
"method",
"path",
"description",
"scope",
"write",
"risk",
"inputSchema",
"outputSchema"
]
}
},
"request_id": {
"type": "string"
}
},
"required": [
"schema",
"capabilities"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/schemas/{name}": {
"get": {
"operationId": "get_schema",
"description": "Read the JSON schema and examples for a native workspace format.",
"security": [],
"x-required-scope": null,
"x-resource-bounds-enforced": true,
"x-risk": "R0",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
}
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "name",
"in": "path",
"required": true,
"schema": {
"type": "string",
"enum": [
"document",
"spreadsheet",
"presentation",
"note",
"publication"
]
}
}
]
}
},
"/v1/templates": {
"get": {
"operationId": "list_templates",
"description": "Read deterministic native templates for a document, note, budget and deck.",
"security": [],
"x-required-scope": null,
"x-resource-bounds-enforced": true,
"x-risk": "R0",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"templates": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"version": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"document"
]
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"docs"
]
},
"blocks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"minItems": 1,
"maxItems": 200
},
"settings": {
"type": "object",
"additionalProperties": false,
"properties": {
"page": {
"type": "string",
"enum": [
"A4",
"Letter"
]
},
"reading": {
"type": "string",
"enum": [
"paged",
"continuous"
]
}
},
"required": [
"page",
"reading"
]
},
"annotations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"block": {
"type": "integer",
"minimum": 0,
"maximum": 199
},
"text": {
"type": "string",
"maxLength": 500,
"x-ursy-maxBytes": 500
}
},
"required": [
"block",
"text"
]
},
"minItems": 0,
"maxItems": 100
}
},
"required": [
"kind",
"blocks"
]
}
},
"required": [
"id",
"version",
"type",
"schema",
"content"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"version": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"spreadsheet"
]
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"sheets"
]
},
"sheets": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 80,
"x-ursy-maxBytes": 80
},
"cells": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 2000
}
},
"required": [
"name",
"cells"
]
},
"minItems": 1,
"maxItems": 10
},
"formats": {
"anyOf": [
{
"type": "object",
"maxProperties": 5000,
"patternProperties": {
"^[0-9]+:[0-9]+:[0-9]+$": {
"type": "object",
"additionalProperties": false,
"properties": {
"align": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
},
"wrap": {
"type": "boolean"
}
}
}
},
"additionalProperties": false
},
{
"type": "array",
"maxItems": 0
}
]
},
"validation": {
"anyOf": [
{
"type": "object",
"maxProperties": 5000,
"patternProperties": {
"^[0-9]+:[0-9]+:[0-9]+$": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"number"
]
}
},
"required": [
"type"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"list"
]
},
"values": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1000,
"x-ursy-maxBytes": 1000
},
"minItems": 1,
"maxItems": 20
}
},
"required": [
"type",
"values"
]
}
]
}
},
"additionalProperties": false
},
{
"type": "array",
"maxItems": 0
}
]
},
"widths": {
"anyOf": [
{
"type": "array",
"items": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 600
},
"minItems": 0,
"maxItems": 64
},
"minItems": 0,
"maxItems": 10
},
{
"type": "object",
"maxProperties": 10,
"patternProperties": {
"^[0-9]+$": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 600
},
"minItems": 0,
"maxItems": 64
}
},
"additionalProperties": false
}
]
},
"univer": {
"type": "string",
"maxLength": 700000,
"readOnly": true,
"description": "Browser snapshot. Presence makes the workbook read-only through API v1."
}
},
"required": [
"kind",
"sheets"
],
"description": "Rows in each sheet must have equal length. Range APIs allow up to 1000 cells. Formula source is preserved, not calculated. API writes allow SUM, AVERAGE, MIN, MAX, COUNT, IF, ROUND and ABS only. Native write JSON is at most 1000000 bytes."
}
},
"required": [
"id",
"version",
"type",
"schema",
"content"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"version": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"presentation"
]
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"format": {
"type": "string",
"enum": [
"ursy/slides-native"
]
},
"schemaVersion": {
"type": "integer",
"enum": [
1
]
},
"theme": {
"type": "string",
"enum": [
"midnight",
"daylight",
"studio"
]
},
"slides": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"format",
"schemaVersion",
"theme",
"slides"
]
}
},
"required": [
"id",
"version",
"type",
"schema",
"content"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"version": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"note"
]
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
},
"pinned": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
},
"required": [
"title",
"content"
]
}
},
"required": [
"id",
"version",
"type",
"schema",
"content"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"version": {
"type": "string"
},
"type": {
"type": "string",
"enum": [
"publication"
]
},
"schema": {
"type": "string",
"pattern": "^https://"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"format": {
"type": "string",
"enum": [
"ursy/publish-native"
]
},
"schemaVersion": {
"type": "integer",
"enum": [
1
]
},
"pages": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"name": {
"type": "string",
"maxLength": 120,
"x-ursy-maxBytes": 120
},
"size": {
"type": "string",
"enum": [
"a4",
"letter",
"square",
"business-card"
]
},
"orientation": {
"type": "string",
"enum": [
"portrait",
"landscape"
]
},
"background": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"elements": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"text",
"shape"
]
},
"x": {
"type": "number",
"minimum": 0,
"maximum": 98
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 98
},
"w": {
"type": "number",
"minimum": 2,
"maximum": 100
},
"h": {
"type": "number",
"minimum": 2,
"maximum": 100
},
"rotation": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"fill": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"color": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 160
},
"align": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
},
"weight": {
"type": "integer",
"enum": [
400,
600,
700,
800
]
}
},
"required": [
"id",
"type",
"x",
"y",
"w",
"h",
"rotation",
"text",
"fill",
"color",
"fontSize",
"align",
"weight"
]
},
"minItems": 0,
"maxItems": 80
}
},
"required": [
"id",
"name",
"size",
"orientation",
"background",
"elements"
]
},
"minItems": 1,
"maxItems": 24
}
},
"required": [
"format",
"schemaVersion",
"pages"
]
}
},
"required": [
"id",
"version",
"type",
"schema",
"content"
]
}
]
},
"minItems": 5
},
"request_id": {
"type": "string"
}
},
"required": [
"templates"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/workspaces": {
"get": {
"operationId": "list_workspaces",
"description": "Read the workspace explicitly selected by this grant.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.workspace.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"workspaces": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"minItems": 1,
"maxItems": 1
},
"actor": {
"type": "object",
"additionalProperties": true
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"workspaces",
"actor"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/files": {
"get": {
"operationId": "list_files",
"description": "List authorized file metadata with a signed keyset cursor. No file contents.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.list",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"minItems": 0,
"maxItems": 100
},
"next_cursor": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"has_more": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"items",
"next_cursor",
"has_more"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048,
"x-ursy-maxBytes": 2048
}
},
{
"name": "parent_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
}
},
{
"name": "name_contains",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 100,
"x-ursy-maxBytes": 100
}
},
{
"name": "include_trash",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
}
]
},
"post": {
"operationId": "create_file",
"description": "Create a private folder or typed native file in an explicitly granted parent.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.create",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication"
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"content": {
"type": "object"
}
},
"required": [
"type",
"name"
]
}
}
}
}
}
},
"/v1/search": {
"get": {
"operationId": "search_workspace",
"description": "Search authorized filenames and file types; no cross-workspace search.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.list",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"minItems": 0,
"maxItems": 100
},
"next_cursor": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"has_more": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"items",
"next_cursor",
"has_more"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048,
"x-ursy-maxBytes": 2048
}
},
{
"name": "parent_id",
"in": "query",
"required": false,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
}
},
{
"name": "name_contains",
"in": "query",
"required": true,
"schema": {
"type": "string",
"maxLength": 100,
"x-ursy-maxBytes": 100
}
}
]
}
},
"/v1/content-search": {
"post": {
"operationId": "search_content",
"description": "Search text inside authorized native files; JSON body keeps terms out of URL logs. Requires files.list and each returned type read scope.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.search.content",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"results": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"matches": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 242,
"x-ursy-maxBytes": 242
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"block_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"slide_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"page_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"element_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"field": {
"type": "string",
"enum": [
"title",
"body",
"notes",
"content"
]
},
"sheet_index": {
"type": "integer",
"minimum": 0
},
"row_index": {
"type": "integer",
"minimum": 0
},
"column_index": {
"type": "integer",
"minimum": 0
},
"range": {
"type": "string",
"pattern": "^[A-Z]+[1-9][0-9]*$"
}
}
}
},
"required": [
"text",
"anchor"
]
},
"minItems": 1,
"maxItems": 3
}
},
"required": [
"file",
"version_id",
"matches"
]
},
"minItems": 0,
"maxItems": 50
},
"content_is_untrusted": {
"const": true
},
"match_mode": {
"type": "string",
"enum": [
"case_insensitive_literal_substring"
]
},
"consistency": {
"type": "string"
},
"next_cursor": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"has_more": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"results",
"content_is_untrusted",
"match_mode",
"consistency",
"next_cursor",
"has_more"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"query": {
"type": "string",
"minLength": 1,
"maxLength": 120
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 50
},
"cursor": {
"type": "string",
"maxLength": 2048,
"x-ursy-maxBytes": 2048
},
"type": {
"type": "string",
"enum": [
"document",
"spreadsheet",
"presentation",
"note",
"publication"
]
}
},
"required": [
"query"
]
}
}
}
}
}
},
"/v1/uploads": {
"post": {
"operationId": "create_upload",
"description": "Begin a private raw-byte upload. New files need files.create; replacement needs files.write, current ETag and an auto-apply policy.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.upload",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"upload": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
},
"state": {
"type": "string",
"enum": [
"pending",
"completed",
"cancelled"
]
},
"name": {
"type": "string"
},
"mime": {
"type": "string"
},
"size": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"chunk_bytes": {
"const": 1048576
},
"chunk_count": {
"type": "integer",
"minimum": 0
},
"received_bytes": {
"type": "integer",
"minimum": 0
},
"next_chunk_index": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"file_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"chunk_url_template": {
"type": "string"
},
"chunk_method": {
"type": "string",
"enum": [
"PUT"
]
},
"authorization": {
"type": "string"
}
},
"required": [
"id",
"state",
"name",
"mime",
"size",
"sha256",
"chunk_bytes",
"chunk_count",
"received_bytes",
"next_chunk_index",
"expires_at",
"file_id",
"version_id",
"chunk_url_template",
"chunk_method",
"authorization"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"upload"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "If-Match",
"in": "header",
"required": false,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 180,
"x-ursy-maxBytes": 180,
"description": "UTF-8 display filename, 1-180 bytes, preserved as supplied. Spaces and ordinary Unicode are supported. No leading/trailing whitespace or dot, path separators, reserved device names, control/format characters or executable/double extensions. Use a supported extension/MIME pair; for example Project notes.txt."
},
"mime": {
"type": "string",
"maxLength": 128,
"x-ursy-maxBytes": 128
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 26214400
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
"required": [
"name",
"mime",
"size",
"sha256"
]
}
}
}
}
}
},
"/v1/uploads/{upload_id}": {
"get": {
"operationId": "get_upload",
"description": "Read resumable upload status; the original grant and current resource bounds are required.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.upload",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"upload": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
},
"state": {
"type": "string",
"enum": [
"pending",
"completed",
"cancelled"
]
},
"name": {
"type": "string"
},
"mime": {
"type": "string"
},
"size": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"chunk_bytes": {
"const": 1048576
},
"chunk_count": {
"type": "integer",
"minimum": 0
},
"received_bytes": {
"type": "integer",
"minimum": 0
},
"next_chunk_index": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"file_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"chunk_url_template": {
"type": "string"
},
"chunk_method": {
"type": "string",
"enum": [
"PUT"
]
},
"authorization": {
"type": "string"
}
},
"required": [
"id",
"state",
"name",
"mime",
"size",
"sha256",
"chunk_bytes",
"chunk_count",
"received_bytes",
"next_chunk_index",
"expires_at",
"file_id",
"version_id",
"chunk_url_template",
"chunk_method",
"authorization"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"upload"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "upload_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
}
}
]
}
},
"/v1/uploads/{upload_id}/complete": {
"post": {
"operationId": "complete_upload",
"description": "Verify length, MIME, hash and quota, then save a canonical Drive file/version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.upload",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"upload": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
},
"state": {
"type": "string",
"enum": [
"pending",
"completed",
"cancelled"
]
},
"name": {
"type": "string"
},
"mime": {
"type": "string"
},
"size": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"chunk_bytes": {
"const": 1048576
},
"chunk_count": {
"type": "integer",
"minimum": 0
},
"received_bytes": {
"type": "integer",
"minimum": 0
},
"next_chunk_index": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"file_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"chunk_url_template": {
"type": "string"
},
"chunk_method": {
"type": "string",
"enum": [
"PUT"
]
},
"authorization": {
"type": "string"
}
},
"required": [
"id",
"state",
"name",
"mime",
"size",
"sha256",
"chunk_bytes",
"chunk_count",
"received_bytes",
"next_chunk_index",
"expires_at",
"file_id",
"version_id",
"chunk_url_template",
"chunk_method",
"authorization"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"upload"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "upload_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/uploads/{upload_id}/cancel": {
"post": {
"operationId": "cancel_upload",
"description": "Discard only uncommitted staging chunks. Completed saved versions are preserved.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.upload",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"upload": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
},
"state": {
"type": "string",
"enum": [
"pending",
"completed",
"cancelled"
]
},
"name": {
"type": "string"
},
"mime": {
"type": "string"
},
"size": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"chunk_bytes": {
"const": 1048576
},
"chunk_count": {
"type": "integer",
"minimum": 0
},
"received_bytes": {
"type": "integer",
"minimum": 0
},
"next_chunk_index": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"file_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"chunk_url_template": {
"type": "string"
},
"chunk_method": {
"type": "string",
"enum": [
"PUT"
]
},
"authorization": {
"type": "string"
}
},
"required": [
"id",
"state",
"name",
"mime",
"size",
"sha256",
"chunk_bytes",
"chunk_count",
"received_bytes",
"next_chunk_index",
"expires_at",
"file_id",
"version_id",
"chunk_url_template",
"chunk_method",
"authorization"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"upload"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "upload_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/files/{file_id}/download-grants": {
"post": {
"operationId": "create_download_grant",
"description": "Authorize a five-minute binary download of the exact current manifest. The original bearer is required at delivery.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.binary.read",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"download": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^dl_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"version_id": {
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
"url": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"size": {
"type": "integer",
"minimum": 1,
"maximum": 26214400
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"authorization": {
"type": "string"
}
},
"required": [
"id",
"file_id",
"version_id",
"url",
"expires_at",
"size",
"sha256",
"authorization"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"download"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/files/{file_id}": {
"get": {
"operationId": "get_file_metadata",
"description": "Read stable identity, current version, ETag and human URL.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
]
},
"patch": {
"operationId": "update_file_metadata",
"description": "Rename or move a file with its current ETag; identity remains stable.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
}
}
}
}
},
"delete": {
"operationId": "trash_file",
"description": "Move one file to recoverable trash with its current ETag; folders with children are rejected.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.trash",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/files/{file_id}/content": {
"get": {
"operationId": "read_file",
"description": "Read a bounded native content snapshot. Uploaded binary chunks are not returned.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"content": {
"type": "object",
"additionalProperties": true
},
"content_is_untrusted": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"content",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
]
}
},
"/v1/files/{file_id}/versions": {
"get": {
"operationId": "list_versions",
"description": "List immutable version metadata with bounded cursor pagination.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.versions.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"versions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"minItems": 0,
"maxItems": 100
},
"next_cursor": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"has_more": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"versions",
"next_cursor",
"has_more"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048,
"x-ursy-maxBytes": 2048
}
}
]
}
},
"/v1/files/{file_id}/versions/{version_id}": {
"get": {
"operationId": "read_version",
"description": "Read one authorized native historical version and its provenance.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.versions.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"version_id": {
"type": "string"
},
"version": {
"type": "object",
"additionalProperties": true
},
"content": {
"type": "object",
"additionalProperties": true
},
"content_is_untrusted": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"version_id",
"version",
"content",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "version_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^ver_[1-9][0-9]{0,14}$"
}
}
]
}
},
"/v1/files/{file_id}/edit-plans": {
"post": {
"operationId": "propose_file_edit",
"description": "Preview typed edits bound to the current ETag; does not alter the file.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^plan_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"base_etag": {
"type": "string"
},
"summary": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"proposed_content": {
"type": "object",
"additionalProperties": true
},
"expires_at": {
"type": "string"
},
"applied_version_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requires_confirmation": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"approval_url": {
"type": "string"
},
"actor": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"file_id",
"base_etag",
"summary",
"operations",
"proposed_content",
"expires_at"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"operations": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"insert_block"
]
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"after_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
}
},
"required": [
"op",
"block_id",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_text"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"find": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"replace": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"block_id",
"find",
"replace"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_note"
]
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
}
},
"required": [
"op"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_values"
]
},
"sheet_index": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"range": {
"type": "string",
"pattern": "^[A-Z]{1,2}[1-9][0-9]{0,3}(:[A-Z]{1,2}[1-9][0-9]{0,3})?$"
},
"values": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 1000
}
},
"required": [
"op",
"range",
"values"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"add_slide"
]
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide_id",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"slide_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_publication_text"
]
},
"page_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"element_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"page_id",
"element_id",
"text"
]
}
]
}
},
"summary": {
"type": "string",
"maxLength": 240,
"x-ursy-maxBytes": 240
}
},
"required": [
"operations",
"summary"
]
}
}
}
}
}
},
"/v1/files/{file_id}/edit-plans/{plan_id}": {
"get": {
"operationId": "get_edit_plan",
"description": "Read a proposal made by this grant, including bounded preview and expiry.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^plan_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"base_etag": {
"type": "string"
},
"summary": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"proposed_content": {
"type": "object",
"additionalProperties": true
},
"expires_at": {
"type": "string"
},
"applied_version_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requires_confirmation": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"approval_url": {
"type": "string"
},
"actor": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"file_id",
"base_etag",
"summary",
"operations",
"proposed_content",
"expires_at"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^plan_[0-9a-f]{32}$"
}
}
]
}
},
"/v1/files/{file_id}/edit-plans/{plan_id}/apply": {
"post": {
"operationId": "apply_file_edit",
"description": "Apply this grant\u2019s unexpired proposal only if the base ETag still matches.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^plan_[0-9a-f]{32}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/files/{file_id}/restore-plans": {
"post": {
"operationId": "restore_version_plan",
"description": "Propose a historical native version as a new version; preserves history.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.versions.restore",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^plan_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"base_etag": {
"type": "string"
},
"summary": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"proposed_content": {
"type": "object",
"additionalProperties": true
},
"expires_at": {
"type": "string"
},
"applied_version_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requires_confirmation": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"approval_url": {
"type": "string"
},
"actor": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"file_id",
"base_etag",
"summary",
"operations",
"proposed_content",
"expires_at"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"version_id": {
"type": "string",
"pattern": "^ver_[1-9][0-9]{0,14}$"
}
},
"required": [
"version_id"
]
}
}
}
}
}
},
"/v1/files/{file_id}/comments": {
"get": {
"operationId": "list_comments",
"description": "Read comments on an authorized file with actor identity.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.comments.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"comments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^cmt_[1-9][0-9]*$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"text": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"block_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"slide_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"range": {
"type": "string",
"maxLength": 30,
"x-ursy-maxBytes": 30
}
}
},
"actor": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"open",
"resolved"
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"resolved_at": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"file_id",
"text",
"anchor",
"actor",
"status",
"etag",
"created_at",
"updated_at",
"resolved_at"
]
},
"minItems": 0,
"maxItems": 100
},
"content_is_untrusted": {
"const": true
},
"next_cursor": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"has_more": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"comments",
"content_is_untrusted",
"next_cursor",
"has_more"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048,
"x-ursy-maxBytes": 2048
}
}
]
},
"post": {
"operationId": "add_comment",
"description": "Comment without altering a file; a comment-only grant needs no edit scope.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.comments.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"comment": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^cmt_[1-9][0-9]*$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"text": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"block_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"slide_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"range": {
"type": "string",
"maxLength": 30,
"x-ursy-maxBytes": 30
}
}
},
"actor": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"open",
"resolved"
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"resolved_at": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"file_id",
"text",
"anchor",
"actor",
"status",
"etag",
"created_at",
"updated_at",
"resolved_at"
]
},
"content_is_untrusted": {
"const": true
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"comment",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"block_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"slide_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"range": {
"type": "string",
"maxLength": 30,
"x-ursy-maxBytes": 30
}
}
}
},
"required": [
"text"
]
}
}
}
}
}
},
"/v1/files/{file_id}/comments/{comment_id}": {
"patch": {
"operationId": "update_comment",
"description": "Edit your own comment with its current comment ETag.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.comments.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"comment": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^cmt_[1-9][0-9]*$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"text": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"block_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"slide_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"range": {
"type": "string",
"maxLength": 30,
"x-ursy-maxBytes": 30
}
}
},
"actor": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"open",
"resolved"
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"resolved_at": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"file_id",
"text",
"anchor",
"actor",
"status",
"etag",
"created_at",
"updated_at",
"resolved_at"
]
},
"content_is_untrusted": {
"const": true
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"comment",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "comment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^cmt_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
}
},
"required": [
"text"
]
}
}
}
}
}
},
"/v1/files/{file_id}/comments/{comment_id}/resolve": {
"post": {
"operationId": "resolve_comment",
"description": "Resolve your own comment without changing the file.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.comments.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"comment": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^cmt_[1-9][0-9]*$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"text": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"block_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"slide_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"range": {
"type": "string",
"maxLength": 30,
"x-ursy-maxBytes": 30
}
}
},
"actor": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"open",
"resolved"
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"resolved_at": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"file_id",
"text",
"anchor",
"actor",
"status",
"etag",
"created_at",
"updated_at",
"resolved_at"
]
},
"content_is_untrusted": {
"const": true
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"comment",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "comment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^cmt_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/files/{file_id}/comments/{comment_id}/reopen": {
"post": {
"operationId": "reopen_comment",
"description": "Reopen your own resolved comment with its current comment ETag.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.comments.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"comment": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^cmt_[1-9][0-9]*$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"text": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"anchor": {
"type": "object",
"additionalProperties": false,
"properties": {
"block_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"slide_id": {
"type": "string",
"maxLength": 64,
"x-ursy-maxBytes": 64
},
"range": {
"type": "string",
"maxLength": 30,
"x-ursy-maxBytes": 30
}
}
},
"actor": {
"type": "object",
"additionalProperties": true
},
"status": {
"type": "string",
"enum": [
"open",
"resolved"
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"resolved_at": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"file_id",
"text",
"anchor",
"actor",
"status",
"etag",
"created_at",
"updated_at",
"resolved_at"
]
},
"content_is_untrusted": {
"const": true
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"comment",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "comment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^cmt_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/changes": {
"get": {
"operationId": "get_changes",
"description": "Read authorized mutation events; status reports browser coverage and its activation time.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.list",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"events": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"minItems": 0,
"maxItems": 100
},
"legacy_browser_changes_included": {
"type": "boolean"
},
"next_cursor": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"has_more": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"events",
"legacy_browser_changes_included",
"next_cursor",
"has_more"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"type": "string",
"maxLength": 2048,
"x-ursy-maxBytes": 2048
}
}
]
}
},
"/v1/files/{file_id}/export": {
"get": {
"operationId": "export_file",
"description": "Export one bounded native file to JSON, text, Markdown or CSV when supported.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.export",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"format": {
"type": "string",
"enum": [
"native",
"txt",
"markdown",
"csv"
]
},
"mime": {
"type": "string"
},
"content": {
"type": "string"
},
"bytes": {
"type": "integer"
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"content_is_untrusted": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file_id",
"format",
"mime",
"content",
"bytes",
"sha256",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "format",
"in": "query",
"required": true,
"schema": {
"type": "string",
"enum": [
"native",
"txt",
"markdown",
"csv"
]
}
}
]
}
},
"/v1/spreadsheets/{file_id}/ranges/{range}": {
"get": {
"operationId": "read_sheet_range",
"description": "Read up to 1,000 cells from the stored grid; formulas are source text, not server-recalculated values.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.sheets.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"sheet_index": {
"type": "integer"
},
"range": {
"type": "string"
},
"values": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 0,
"maxItems": 64
},
"minItems": 0,
"maxItems": 1000
},
"representation": {
"type": "string"
},
"server_recalculated": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"sheet_index",
"range",
"values",
"representation",
"server_recalculated"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "range",
"in": "path",
"required": true,
"schema": {
"type": "string",
"maxLength": 30,
"x-ursy-maxBytes": 30
}
},
{
"name": "sheet_index",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 9
}
}
]
}
},
"/v1/documents/{file_id}": {
"get": {
"operationId": "read_document",
"description": "Read the authorized native document and current ETag.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.documents.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"docs"
]
},
"blocks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"minItems": 1,
"maxItems": 200
},
"settings": {
"type": "object",
"additionalProperties": false,
"properties": {
"page": {
"type": "string",
"enum": [
"A4",
"Letter"
]
},
"reading": {
"type": "string",
"enum": [
"paged",
"continuous"
]
}
},
"required": [
"page",
"reading"
]
},
"annotations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"block": {
"type": "integer",
"minimum": 0,
"maximum": 199
},
"text": {
"type": "string",
"maxLength": 500,
"x-ursy-maxBytes": 500
}
},
"required": [
"block",
"text"
]
},
"minItems": 0,
"maxItems": 100
}
},
"required": [
"kind",
"blocks"
]
},
"content_is_untrusted": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"content",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
]
}
},
"/v1/documents": {
"post": {
"operationId": "create_document",
"description": "Create a private native document with immutable initial version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.create",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"docs"
]
},
"blocks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"minItems": 1,
"maxItems": 200
},
"settings": {
"type": "object",
"additionalProperties": false,
"properties": {
"page": {
"type": "string",
"enum": [
"A4",
"Letter"
]
},
"reading": {
"type": "string",
"enum": [
"paged",
"continuous"
]
}
},
"required": [
"page",
"reading"
]
},
"annotations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"block": {
"type": "integer",
"minimum": 0,
"maximum": 199
},
"text": {
"type": "string",
"maxLength": 500,
"x-ursy-maxBytes": 500
}
},
"required": [
"block",
"text"
]
},
"minItems": 0,
"maxItems": 100
}
},
"required": [
"kind",
"blocks"
]
}
},
"required": [
"name"
]
}
}
}
}
}
},
"/v1/documents/{file_id}/edit-plans": {
"post": {
"operationId": "propose_document_edit",
"description": "Propose typed document edits with version safety.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.documents.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^plan_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"base_etag": {
"type": "string"
},
"summary": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"proposed_content": {
"type": "object",
"additionalProperties": true
},
"expires_at": {
"type": "string"
},
"applied_version_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requires_confirmation": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"approval_url": {
"type": "string"
},
"actor": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"file_id",
"base_etag",
"summary",
"operations",
"proposed_content",
"expires_at"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"operations": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"insert_block"
]
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"after_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
}
},
"required": [
"op",
"block_id",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_text"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"find": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"replace": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"block_id",
"find",
"replace"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_note"
]
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
}
},
"required": [
"op"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_values"
]
},
"sheet_index": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"range": {
"type": "string",
"pattern": "^[A-Z]{1,2}[1-9][0-9]{0,3}(:[A-Z]{1,2}[1-9][0-9]{0,3})?$"
},
"values": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 1000
}
},
"required": [
"op",
"range",
"values"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"add_slide"
]
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide_id",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"slide_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_publication_text"
]
},
"page_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"element_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"page_id",
"element_id",
"text"
]
}
]
}
},
"summary": {
"type": "string",
"maxLength": 240,
"x-ursy-maxBytes": 240
}
},
"required": [
"operations",
"summary"
]
}
}
}
}
}
},
"/v1/documents/{file_id}/edit-plans/{plan_id}/apply": {
"post": {
"operationId": "apply_document_edit",
"description": "Apply the exact document proposal after checking its base version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.documents.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^plan_[0-9a-f]{32}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/spreadsheets/{file_id}": {
"get": {
"operationId": "read_spreadsheet",
"description": "Read the authorized native spreadsheet and current ETag.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.sheets.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"sheets"
]
},
"sheets": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 80,
"x-ursy-maxBytes": 80
},
"cells": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 2000
}
},
"required": [
"name",
"cells"
]
},
"minItems": 1,
"maxItems": 10
},
"formats": {
"anyOf": [
{
"type": "object",
"maxProperties": 5000,
"patternProperties": {
"^[0-9]+:[0-9]+:[0-9]+$": {
"type": "object",
"additionalProperties": false,
"properties": {
"align": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
},
"wrap": {
"type": "boolean"
}
}
}
},
"additionalProperties": false
},
{
"type": "array",
"maxItems": 0
}
]
},
"validation": {
"anyOf": [
{
"type": "object",
"maxProperties": 5000,
"patternProperties": {
"^[0-9]+:[0-9]+:[0-9]+$": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"number"
]
}
},
"required": [
"type"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"list"
]
},
"values": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1000,
"x-ursy-maxBytes": 1000
},
"minItems": 1,
"maxItems": 20
}
},
"required": [
"type",
"values"
]
}
]
}
},
"additionalProperties": false
},
{
"type": "array",
"maxItems": 0
}
]
},
"widths": {
"anyOf": [
{
"type": "array",
"items": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 600
},
"minItems": 0,
"maxItems": 64
},
"minItems": 0,
"maxItems": 10
},
{
"type": "object",
"maxProperties": 10,
"patternProperties": {
"^[0-9]+$": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 600
},
"minItems": 0,
"maxItems": 64
}
},
"additionalProperties": false
}
]
},
"univer": {
"type": "string",
"maxLength": 700000,
"readOnly": true,
"description": "Browser snapshot. Presence makes the workbook read-only through API v1."
}
},
"required": [
"kind",
"sheets"
],
"description": "Rows in each sheet must have equal length. Range APIs allow up to 1000 cells. Formula source is preserved, not calculated. API writes allow SUM, AVERAGE, MIN, MAX, COUNT, IF, ROUND and ABS only. Native write JSON is at most 1000000 bytes."
},
"content_is_untrusted": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"content",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
]
}
},
"/v1/spreadsheets": {
"post": {
"operationId": "create_spreadsheet",
"description": "Create a private native spreadsheet with immutable initial version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.create",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"kind": {
"type": "string",
"enum": [
"sheets"
]
},
"sheets": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 80,
"x-ursy-maxBytes": 80
},
"cells": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 2000
}
},
"required": [
"name",
"cells"
]
},
"minItems": 1,
"maxItems": 10
},
"formats": {
"anyOf": [
{
"type": "object",
"maxProperties": 5000,
"patternProperties": {
"^[0-9]+:[0-9]+:[0-9]+$": {
"type": "object",
"additionalProperties": false,
"properties": {
"align": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
},
"wrap": {
"type": "boolean"
}
}
}
},
"additionalProperties": false
},
{
"type": "array",
"maxItems": 0
}
]
},
"validation": {
"anyOf": [
{
"type": "object",
"maxProperties": 5000,
"patternProperties": {
"^[0-9]+:[0-9]+:[0-9]+$": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"number"
]
}
},
"required": [
"type"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"type": {
"type": "string",
"enum": [
"list"
]
},
"values": {
"type": "array",
"items": {
"type": "string",
"maxLength": 1000,
"x-ursy-maxBytes": 1000
},
"minItems": 1,
"maxItems": 20
}
},
"required": [
"type",
"values"
]
}
]
}
},
"additionalProperties": false
},
{
"type": "array",
"maxItems": 0
}
]
},
"widths": {
"anyOf": [
{
"type": "array",
"items": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 600
},
"minItems": 0,
"maxItems": 64
},
"minItems": 0,
"maxItems": 10
},
{
"type": "object",
"maxProperties": 10,
"patternProperties": {
"^[0-9]+$": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 600
},
"minItems": 0,
"maxItems": 64
}
},
"additionalProperties": false
}
]
},
"univer": {
"type": "string",
"maxLength": 700000,
"readOnly": true,
"description": "Browser snapshot. Presence makes the workbook read-only through API v1."
}
},
"required": [
"kind",
"sheets"
],
"description": "Rows in each sheet must have equal length. Range APIs allow up to 1000 cells. Formula source is preserved, not calculated. API writes allow SUM, AVERAGE, MIN, MAX, COUNT, IF, ROUND and ABS only. Native write JSON is at most 1000000 bytes."
}
},
"required": [
"name"
]
}
}
}
}
}
},
"/v1/spreadsheets/{file_id}/edit-plans": {
"post": {
"operationId": "propose_spreadsheet_edit",
"description": "Propose typed spreadsheet edits with version safety.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.sheets.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^plan_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"base_etag": {
"type": "string"
},
"summary": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"proposed_content": {
"type": "object",
"additionalProperties": true
},
"expires_at": {
"type": "string"
},
"applied_version_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requires_confirmation": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"approval_url": {
"type": "string"
},
"actor": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"file_id",
"base_etag",
"summary",
"operations",
"proposed_content",
"expires_at"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"operations": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"insert_block"
]
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"after_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
}
},
"required": [
"op",
"block_id",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_text"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"find": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"replace": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"block_id",
"find",
"replace"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_note"
]
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
}
},
"required": [
"op"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_values"
]
},
"sheet_index": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"range": {
"type": "string",
"pattern": "^[A-Z]{1,2}[1-9][0-9]{0,3}(:[A-Z]{1,2}[1-9][0-9]{0,3})?$"
},
"values": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 1000
}
},
"required": [
"op",
"range",
"values"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"add_slide"
]
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide_id",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"slide_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_publication_text"
]
},
"page_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"element_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"page_id",
"element_id",
"text"
]
}
]
}
},
"summary": {
"type": "string",
"maxLength": 240,
"x-ursy-maxBytes": 240
}
},
"required": [
"operations",
"summary"
]
}
}
}
}
}
},
"/v1/spreadsheets/{file_id}/edit-plans/{plan_id}/apply": {
"post": {
"operationId": "apply_spreadsheet_edit",
"description": "Apply the exact spreadsheet proposal after checking its base version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.sheets.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^plan_[0-9a-f]{32}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/presentations/{file_id}": {
"get": {
"operationId": "read_presentation",
"description": "Read the authorized native presentation and current ETag.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.slides.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"format": {
"type": "string",
"enum": [
"ursy/slides-native"
]
},
"schemaVersion": {
"type": "integer",
"enum": [
1
]
},
"theme": {
"type": "string",
"enum": [
"midnight",
"daylight",
"studio"
]
},
"slides": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"format",
"schemaVersion",
"theme",
"slides"
]
},
"content_is_untrusted": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"content",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
]
}
},
"/v1/presentations": {
"post": {
"operationId": "create_presentation",
"description": "Create a private native presentation with immutable initial version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.create",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"format": {
"type": "string",
"enum": [
"ursy/slides-native"
]
},
"schemaVersion": {
"type": "integer",
"enum": [
1
]
},
"theme": {
"type": "string",
"enum": [
"midnight",
"daylight",
"studio"
]
},
"slides": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"format",
"schemaVersion",
"theme",
"slides"
]
}
},
"required": [
"name"
]
}
}
}
}
}
},
"/v1/presentations/{file_id}/edit-plans": {
"post": {
"operationId": "propose_presentation_edit",
"description": "Propose typed presentation edits with version safety.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.slides.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^plan_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"base_etag": {
"type": "string"
},
"summary": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"proposed_content": {
"type": "object",
"additionalProperties": true
},
"expires_at": {
"type": "string"
},
"applied_version_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requires_confirmation": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"approval_url": {
"type": "string"
},
"actor": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"file_id",
"base_etag",
"summary",
"operations",
"proposed_content",
"expires_at"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"operations": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"insert_block"
]
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"after_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
}
},
"required": [
"op",
"block_id",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_text"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"find": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"replace": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"block_id",
"find",
"replace"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_note"
]
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
}
},
"required": [
"op"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_values"
]
},
"sheet_index": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"range": {
"type": "string",
"pattern": "^[A-Z]{1,2}[1-9][0-9]{0,3}(:[A-Z]{1,2}[1-9][0-9]{0,3})?$"
},
"values": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 1000
}
},
"required": [
"op",
"range",
"values"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"add_slide"
]
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide_id",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"slide_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_publication_text"
]
},
"page_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"element_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"page_id",
"element_id",
"text"
]
}
]
}
},
"summary": {
"type": "string",
"maxLength": 240,
"x-ursy-maxBytes": 240
}
},
"required": [
"operations",
"summary"
]
}
}
}
}
}
},
"/v1/presentations/{file_id}/edit-plans/{plan_id}/apply": {
"post": {
"operationId": "apply_presentation_edit",
"description": "Apply the exact presentation proposal after checking its base version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.slides.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^plan_[0-9a-f]{32}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/notes/{file_id}": {
"get": {
"operationId": "read_note",
"description": "Read the authorized native note and current ETag.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.notes.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
},
"pinned": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
},
"required": [
"title",
"content"
]
},
"content_is_untrusted": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"content",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
]
}
},
"/v1/notes": {
"post": {
"operationId": "create_note",
"description": "Create a private native note with immutable initial version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.create",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"title": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
},
"pinned": {
"type": "boolean"
},
"archived": {
"type": "boolean"
}
},
"required": [
"title",
"content"
]
}
},
"required": [
"name"
]
}
}
}
}
}
},
"/v1/notes/{file_id}/edit-plans": {
"post": {
"operationId": "propose_note_edit",
"description": "Propose typed note edits with version safety.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.notes.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^plan_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"base_etag": {
"type": "string"
},
"summary": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"proposed_content": {
"type": "object",
"additionalProperties": true
},
"expires_at": {
"type": "string"
},
"applied_version_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requires_confirmation": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"approval_url": {
"type": "string"
},
"actor": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"file_id",
"base_etag",
"summary",
"operations",
"proposed_content",
"expires_at"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"operations": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"insert_block"
]
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"after_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
}
},
"required": [
"op",
"block_id",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_text"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"find": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"replace": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"block_id",
"find",
"replace"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_note"
]
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
}
},
"required": [
"op"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_values"
]
},
"sheet_index": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"range": {
"type": "string",
"pattern": "^[A-Z]{1,2}[1-9][0-9]{0,3}(:[A-Z]{1,2}[1-9][0-9]{0,3})?$"
},
"values": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 1000
}
},
"required": [
"op",
"range",
"values"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"add_slide"
]
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide_id",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"slide_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_publication_text"
]
},
"page_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"element_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"page_id",
"element_id",
"text"
]
}
]
}
},
"summary": {
"type": "string",
"maxLength": 240,
"x-ursy-maxBytes": 240
}
},
"required": [
"operations",
"summary"
]
}
}
}
}
}
},
"/v1/notes/{file_id}/edit-plans/{plan_id}/apply": {
"post": {
"operationId": "apply_note_edit",
"description": "Apply the exact note proposal after checking its base version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.notes.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^plan_[0-9a-f]{32}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/publications/{file_id}": {
"get": {
"operationId": "read_publication",
"description": "Read the authorized native publication and current ETag.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.publish.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"format": {
"type": "string",
"enum": [
"ursy/publish-native"
]
},
"schemaVersion": {
"type": "integer",
"enum": [
1
]
},
"pages": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"name": {
"type": "string",
"maxLength": 120,
"x-ursy-maxBytes": 120
},
"size": {
"type": "string",
"enum": [
"a4",
"letter",
"square",
"business-card"
]
},
"orientation": {
"type": "string",
"enum": [
"portrait",
"landscape"
]
},
"background": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"elements": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"text",
"shape"
]
},
"x": {
"type": "number",
"minimum": 0,
"maximum": 98
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 98
},
"w": {
"type": "number",
"minimum": 2,
"maximum": 100
},
"h": {
"type": "number",
"minimum": 2,
"maximum": 100
},
"rotation": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"fill": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"color": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 160
},
"align": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
},
"weight": {
"type": "integer",
"enum": [
400,
600,
700,
800
]
}
},
"required": [
"id",
"type",
"x",
"y",
"w",
"h",
"rotation",
"text",
"fill",
"color",
"fontSize",
"align",
"weight"
]
},
"minItems": 0,
"maxItems": 80
}
},
"required": [
"id",
"name",
"size",
"orientation",
"background",
"elements"
]
},
"minItems": 1,
"maxItems": 24
}
},
"required": [
"format",
"schemaVersion",
"pages"
]
},
"content_is_untrusted": {
"type": "boolean"
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"content",
"content_is_untrusted"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
]
}
},
"/v1/publications": {
"post": {
"operationId": "create_publication",
"description": "Create a private native publication with immutable initial version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.files.create",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"content": {
"type": "object",
"additionalProperties": false,
"properties": {
"format": {
"type": "string",
"enum": [
"ursy/publish-native"
]
},
"schemaVersion": {
"type": "integer",
"enum": [
1
]
},
"pages": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"name": {
"type": "string",
"maxLength": 120,
"x-ursy-maxBytes": 120
},
"size": {
"type": "string",
"enum": [
"a4",
"letter",
"square",
"business-card"
]
},
"orientation": {
"type": "string",
"enum": [
"portrait",
"landscape"
]
},
"background": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"elements": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"text",
"shape"
]
},
"x": {
"type": "number",
"minimum": 0,
"maximum": 98
},
"y": {
"type": "number",
"minimum": 0,
"maximum": 98
},
"w": {
"type": "number",
"minimum": 2,
"maximum": 100
},
"h": {
"type": "number",
"minimum": 2,
"maximum": 100
},
"rotation": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"fill": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"color": {
"type": "string",
"pattern": "^#[a-fA-F0-9]{6}$"
},
"fontSize": {
"type": "number",
"minimum": 8,
"maximum": 160
},
"align": {
"type": "string",
"enum": [
"left",
"center",
"right"
]
},
"weight": {
"type": "integer",
"enum": [
400,
600,
700,
800
]
}
},
"required": [
"id",
"type",
"x",
"y",
"w",
"h",
"rotation",
"text",
"fill",
"color",
"fontSize",
"align",
"weight"
]
},
"minItems": 0,
"maxItems": 80
}
},
"required": [
"id",
"name",
"size",
"orientation",
"background",
"elements"
]
},
"minItems": 1,
"maxItems": 24
}
},
"required": [
"format",
"schemaVersion",
"pages"
]
}
},
"required": [
"name"
]
}
}
}
}
}
},
"/v1/publications/{file_id}/edit-plans": {
"post": {
"operationId": "propose_publication_edit",
"description": "Propose typed publication edits with version safety.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.publish.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^plan_[a-f0-9]{32}$"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"base_etag": {
"type": "string"
},
"summary": {
"type": "string"
},
"operations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"proposed_content": {
"type": "object",
"additionalProperties": true
},
"expires_at": {
"type": "string"
},
"applied_version_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"requires_confirmation": {
"type": "boolean"
},
"review_status": {
"type": "string",
"enum": [
"pending",
"approved",
"rejected"
]
},
"approval_url": {
"type": "string"
},
"actor": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"id",
"file_id",
"base_etag",
"summary",
"operations",
"proposed_content",
"expires_at"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file",
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"operations": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"insert_block"
]
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
},
"after_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"block": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"type": {
"type": "string",
"enum": [
"paragraph",
"heading1",
"heading2",
"bullet",
"number",
"quote",
"divider",
"table"
]
},
"segments": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"rows": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"underline": {
"type": "boolean"
},
"link": {
"type": "string",
"maxLength": 2048,
"pattern": "^(https?://|mailto:)"
}
},
"required": [
"text"
]
},
"minItems": 0,
"maxItems": 100
},
"minItems": 1,
"maxItems": 26
},
"minItems": 1,
"maxItems": 100
}
},
"required": [
"type",
"segments"
],
"description": "IDs are stable and unique. A divider has no segments. Table rows require an empty segments array; each cell is a segment list. Combined text is limited to 750000 bytes."
}
},
"required": [
"op",
"block_id",
"block"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_block"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"block_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_text"
]
},
"block_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"find": {
"type": "string",
"minLength": 1,
"maxLength": 10000
},
"replace": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"block_id",
"find",
"replace"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_note"
]
},
"content": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"tags": {
"type": "array",
"items": {
"type": "string",
"maxLength": 40,
"x-ursy-maxBytes": 40
},
"minItems": 0,
"maxItems": 20
}
},
"required": [
"op"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_values"
]
},
"sheet_index": {
"type": "integer",
"minimum": 0,
"maximum": 9
},
"range": {
"type": "string",
"pattern": "^[A-Z]{1,2}[1-9][0-9]{0,3}(:[A-Z]{1,2}[1-9][0-9]{0,3})?$"
},
"values": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"minItems": 1,
"maxItems": 64
},
"minItems": 1,
"maxItems": 1000
}
},
"required": [
"op",
"range",
"values"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"add_slide"
]
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"replace_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"slide": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"title": {
"type": "string",
"maxLength": 200,
"x-ursy-maxBytes": 200
},
"body": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
},
"notes": {
"type": "string",
"maxLength": 5000,
"x-ursy-maxBytes": 5000
},
"layout": {
"type": "string",
"enum": [
"title",
"title-body",
"quote",
"blank"
]
},
"background": {
"type": "string",
"enum": [
"ink",
"ocean",
"plum",
"forest",
"sunrise",
"paper"
]
}
},
"required": [
"id",
"title",
"body",
"notes",
"layout",
"background"
]
}
},
"required": [
"op",
"slide_id",
"slide"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"delete_slide"
]
},
"slide_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
}
},
"required": [
"op",
"slide_id"
]
},
{
"type": "object",
"additionalProperties": false,
"properties": {
"op": {
"type": "string",
"enum": [
"set_publication_text"
]
},
"page_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"element_id": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,64}$"
},
"text": {
"type": "string",
"maxLength": 10000,
"x-ursy-maxBytes": 10000
}
},
"required": [
"op",
"page_id",
"element_id",
"text"
]
}
]
}
},
"summary": {
"type": "string",
"maxLength": 240,
"x-ursy-maxBytes": 240
}
},
"required": [
"operations",
"summary"
]
}
}
}
}
}
},
"/v1/publications/{file_id}/edit-plans/{plan_id}/apply": {
"post": {
"operationId": "apply_publication_edit",
"description": "Apply the exact publication proposal after checking its base version.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.publish.write",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
},
"request_id": {
"type": "string"
},
"replayed": {
"type": "boolean"
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^plan_[0-9a-f]{32}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/scratch": {
"post": {
"operationId": "create_scratch",
"description": "Create a private draft outside the canonical file list. Expires after 30 days.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.scratch.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"draft": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^draft_[a-f0-9]{32}$"
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"document",
"spreadsheet",
"presentation",
"note",
"publication"
]
},
"expires_at": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"draft",
"promoted"
]
},
"file_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"content": {
"type": "object",
"additionalProperties": true
},
"content_is_untrusted": {
"const": true
}
},
"required": [
"id",
"name",
"type",
"expires_at",
"state",
"file_id",
"content",
"content_is_untrusted"
]
}
},
"required": [
"draft"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"document",
"spreadsheet",
"presentation",
"note",
"publication"
]
},
"content": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"name",
"type"
]
}
}
}
}
},
"get": {
"operationId": "list_scratch",
"description": "List up to 50 drafts belonging to this grant.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.scratch.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"drafts": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^draft_[a-f0-9]{32}$"
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"document",
"spreadsheet",
"presentation",
"note",
"publication"
]
},
"expires_at": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"draft",
"promoted"
]
},
"file_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"content": {
"type": "object",
"additionalProperties": true
},
"content_is_untrusted": {
"const": true
}
},
"required": [
"id",
"name",
"type",
"expires_at",
"state",
"file_id",
"content",
"content_is_untrusted"
]
},
"minItems": 0,
"maxItems": 50
}
},
"required": [
"drafts"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/scratch/{draft_id}": {
"get": {
"operationId": "get_scratch",
"description": "Preview untrusted draft content and its revision.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.scratch.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"draft": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^draft_[a-f0-9]{32}$"
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"document",
"spreadsheet",
"presentation",
"note",
"publication"
]
},
"expires_at": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"draft",
"promoted"
]
},
"file_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"content": {
"type": "object",
"additionalProperties": true
},
"content_is_untrusted": {
"const": true
}
},
"required": [
"id",
"name",
"type",
"expires_at",
"state",
"file_id",
"content",
"content_is_untrusted"
]
}
},
"required": [
"draft"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "draft_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^draft_[a-f0-9]{32}$"
}
}
]
},
"delete": {
"operationId": "discard_scratch",
"description": "Discard a staged draft without changing saved workspace files.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.scratch.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"discarded": {
"const": true
}
},
"required": [
"discarded"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "draft_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^draft_[a-f0-9]{32}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/scratch/{draft_id}/promote": {
"post": {
"operationId": "promote_scratch",
"description": "Create a canonical file from the exact draft; needs creation, native write and destination access.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.scratch.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "draft_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^draft_[a-f0-9]{32}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
}
}
}
}
}
},
"/v1/imports": {
"post": {
"operationId": "import_file",
"description": "Import bounded UTF-8 TXT, Markdown or CSV as a new native file. CSV formulas become literal text.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.import",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"file": {
"type": "object",
"additionalProperties": false,
"properties": {
"schema": {
"type": "string",
"enum": [
"ursy.cloud/file/v1"
]
},
"id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"workspace_id": {
"type": "string",
"pattern": "^ws_[1-9][0-9]*$"
},
"parent_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"type": {
"type": "string",
"enum": [
"folder",
"document",
"spreadsheet",
"presentation",
"note",
"publication",
"pdf",
"uploaded_file"
]
},
"current_version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"etag": {
"type": "string",
"pattern": "^\"[a-f0-9]{64}\"$"
},
"state": {
"type": "string",
"enum": [
"active",
"trashed"
]
},
"created_at": {
"type": "string"
},
"updated_at": {
"type": "string"
},
"human_url": {
"type": "string"
}
},
"required": [
"schema",
"id",
"workspace_id",
"parent_id",
"name",
"type",
"current_version_id",
"etag",
"state",
"created_at",
"updated_at",
"human_url"
]
}
},
"required": [
"file"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"name": {
"type": "string",
"maxLength": 190,
"x-ursy-maxBytes": 190
},
"format": {
"type": "string",
"enum": [
"txt",
"markdown",
"csv"
]
},
"text": {
"type": "string",
"maxLength": 500000,
"x-ursy-maxBytes": 500000
},
"parent_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
"required": [
"name",
"format",
"text"
]
}
}
}
}
}
},
"/v1/files/{file_id}/share-plans": {
"post": {
"operationId": "create_share_plan",
"description": "Propose one expiring share for the exact file version. Owner approval is always required.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.share.plan",
"x-resource-bounds-enforced": true,
"x-risk": "R3",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"mode": {
"type": "string"
},
"base_etag": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"share_expires_at": {
"type": "string"
},
"requires_confirmation": {
"const": true
},
"approval_url": {
"type": "string"
},
"applied_share_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"file_id",
"mode",
"base_etag",
"expires_at",
"share_expires_at",
"requires_confirmation",
"approval_url",
"applied_share_id"
]
}
},
"required": [
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"mode": {
"type": "string",
"enum": [
"specific_person",
"link_view",
"link_comment",
"link_edit",
"public_view"
]
},
"recipient_sub": {
"type": "string",
"maxLength": 128,
"x-ursy-maxBytes": 128
},
"expires_in": {
"type": "integer",
"minimum": 300,
"maximum": 2592000
}
},
"required": [
"mode",
"expires_in"
]
}
}
}
}
}
},
"/v1/files/{file_id}/share-plans/{share_plan_id}": {
"get": {
"operationId": "get_share_plan",
"description": "Read a pending share proposal and its hosted approval URL.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.share.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"plan": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"mode": {
"type": "string"
},
"base_etag": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"share_expires_at": {
"type": "string"
},
"requires_confirmation": {
"const": true
},
"approval_url": {
"type": "string"
},
"applied_share_id": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"file_id",
"mode",
"base_etag",
"expires_at",
"share_expires_at",
"requires_confirmation",
"approval_url",
"applied_share_id"
]
}
},
"required": [
"plan"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "share_plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^shareplan_[a-f0-9]{32}$"
}
}
]
}
},
"/v1/files/{file_id}/share-plans/{share_plan_id}/apply": {
"post": {
"operationId": "apply_share_plan",
"description": "Apply the unchanged, explicitly approved plan; rechecks current permissions and ETag.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.share.apply",
"x-resource-bounds-enforced": true,
"x-risk": "R3",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"share": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"mode": {
"type": "string",
"enum": [
"specific_person",
"link_view",
"link_comment",
"link_edit",
"public_view"
]
},
"url": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"revoked": {
"type": "boolean"
},
"indexable": {
"const": false
}
},
"required": [
"id",
"file_id",
"mode",
"url",
"expires_at",
"revoked",
"indexable"
]
}
},
"required": [
"share"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
},
{
"name": "share_plan_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^shareplan_[a-f0-9]{32}$"
}
},
{
"name": "If-Match",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^\"[0-9a-f]{64}\"$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/files/{file_id}/shares": {
"get": {
"operationId": "list_shares",
"description": "List this grant\u2019s shares for a permitted file.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.share.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"shares": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"file_id": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
"mode": {
"type": "string",
"enum": [
"specific_person",
"link_view",
"link_comment",
"link_edit",
"public_view"
]
},
"url": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"revoked": {
"type": "boolean"
},
"indexable": {
"const": false
}
},
"required": [
"id",
"file_id",
"mode",
"url",
"expires_at",
"revoked",
"indexable"
]
},
"minItems": 0,
"maxItems": 100
}
},
"required": [
"shares"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "file_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
}
}
]
}
},
"/v1/shares/{share_id}": {
"delete": {
"operationId": "revoke_share",
"description": "Revoke a share immediately for subsequent requests.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.share.revoke",
"x-resource-bounds-enforced": true,
"x-risk": "R3",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"revoked": {
"const": true
}
},
"required": [
"revoked"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "share_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^share_[a-f0-9]{32}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/workspace-exports": {
"post": {
"operationId": "create_workspace_export",
"description": "Queue an export of currently authorised resources after explicit owner approval. Includes integrity manifest; optional versions/comments require their read scopes.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.workspace.export",
"x-resource-bounds-enforced": true,
"x-risk": "R3",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"task": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^task_[a-f0-9]{32}$"
},
"type": {
"const": "workspace_export"
},
"state": {
"type": "string",
"enum": [
"confirmation_required",
"queued",
"running",
"completed",
"failed",
"cancelled",
"expired"
]
},
"processed_files": {
"type": "integer",
"minimum": 0
},
"result_bytes": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"approval_url": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_code": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"content_is_untrusted": {
"const": true
}
},
"required": [
"id",
"type",
"state",
"processed_files",
"result_bytes",
"expires_at",
"approval_url",
"error_code",
"content_is_untrusted"
]
}
},
"required": [
"task"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"include_versions": {
"type": "boolean"
},
"include_comments": {
"type": "boolean"
}
}
}
}
}
}
}
},
"/v1/tasks/{task_id}": {
"get": {
"operationId": "get_task",
"description": "Read background task status and progress. Queued means approval received and waiting for the ordinary worker.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.tasks.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"task": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^task_[a-f0-9]{32}$"
},
"type": {
"const": "workspace_export"
},
"state": {
"type": "string",
"enum": [
"confirmation_required",
"queued",
"running",
"completed",
"failed",
"cancelled",
"expired"
]
},
"processed_files": {
"type": "integer",
"minimum": 0
},
"result_bytes": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"approval_url": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_code": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"content_is_untrusted": {
"const": true
}
},
"required": [
"id",
"type",
"state",
"processed_files",
"result_bytes",
"expires_at",
"approval_url",
"error_code",
"content_is_untrusted"
]
}
},
"required": [
"task"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^task_[a-f0-9]{32}$"
}
}
]
}
},
"/v1/tasks": {
"get": {
"operationId": "list_tasks",
"description": "List up to 50 current tasks belonging to this grant.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.tasks.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^task_[a-f0-9]{32}$"
},
"type": {
"const": "workspace_export"
},
"state": {
"type": "string",
"enum": [
"confirmation_required",
"queued",
"running",
"completed",
"failed",
"cancelled",
"expired"
]
},
"processed_files": {
"type": "integer",
"minimum": 0
},
"result_bytes": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"approval_url": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_code": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"content_is_untrusted": {
"const": true
}
},
"required": [
"id",
"type",
"state",
"processed_files",
"result_bytes",
"expires_at",
"approval_url",
"error_code",
"content_is_untrusted"
]
},
"minItems": 0,
"maxItems": 50
}
},
"required": [
"tasks"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/tasks/{task_id}/cancel": {
"post": {
"operationId": "cancel_task",
"description": "Cancel a task and remove its temporary result; saved files remain intact.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.tasks.cancel",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"task": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^task_[a-f0-9]{32}$"
},
"type": {
"const": "workspace_export"
},
"state": {
"type": "string",
"enum": [
"confirmation_required",
"queued",
"running",
"completed",
"failed",
"cancelled",
"expired"
]
},
"processed_files": {
"type": "integer",
"minimum": 0
},
"result_bytes": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"approval_url": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"error_code": {
"oneOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"content_is_untrusted": {
"const": true
}
},
"required": [
"id",
"type",
"state",
"processed_files",
"result_bytes",
"expires_at",
"approval_url",
"error_code",
"content_is_untrusted"
]
}
},
"required": [
"task"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^task_[a-f0-9]{32}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/tasks/{task_id}/download": {
"post": {
"operationId": "create_task_download",
"description": "Authorize five-minute private ZIP delivery using this same current grant.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.workspace.export",
"x-resource-bounds-enforced": true,
"x-risk": "R3",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"download": {
"type": "object",
"additionalProperties": false,
"properties": {
"task_id": {
"type": "string"
},
"url": {
"type": "string"
},
"expires_at": {
"type": "string"
},
"authorization": {
"type": "string"
}
},
"required": [
"task_id",
"url",
"expires_at",
"authorization"
]
}
},
"required": [
"download"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^task_[a-f0-9]{32}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/webhooks": {
"post": {
"operationId": "create_webhook",
"description": "Register an HTTPS receiver; prove the returned secret before events are sent. Receives IDs only, never file text or names.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.webhooks.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"webhook": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"pending",
"active",
"disabled",
"revoked"
]
},
"failures": {
"type": "integer",
"minimum": 0
},
"last_error": {
"type": "string"
}
},
"required": [
"id",
"url",
"state",
"failures",
"last_error"
]
},
"secret": {
"type": "string"
},
"verification": {
"type": "string"
}
},
"required": [
"webhook",
"secret",
"verification"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"url": {
"type": "string",
"maxLength": 1024,
"pattern": "^https://"
}
},
"required": [
"url"
]
}
}
}
}
},
"get": {
"operationId": "list_webhooks",
"description": "List this grant\u2019s notification subscriptions, verification state and delivery failures.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.webhooks.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"webhooks": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string"
},
"state": {
"type": "string",
"enum": [
"pending",
"active",
"disabled",
"revoked"
]
},
"failures": {
"type": "integer",
"minimum": 0
},
"last_error": {
"type": "string"
}
},
"required": [
"id",
"url",
"state",
"failures",
"last_error"
]
},
"minItems": 0,
"maxItems": 10
}
},
"required": [
"webhooks"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/webhooks/{webhook_id}": {
"delete": {
"operationId": "revoke_webhook",
"description": "Stop a notification subscription.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.webhooks.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R2",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"revoked": {
"const": true
}
},
"required": [
"revoked"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "webhook_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^hook_[a-f0-9]{32}$"
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/team-memberships": {
"get": {
"operationId": "list_team_memberships",
"description": "Read current URSY.ID organisations and roles for the authenticated Cloud subject.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.teams.read",
"x-resource-bounds-enforced": true,
"x-risk": "R1",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"memberships": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
},
"minItems": 0,
"maxItems": 100
},
"authority": {
"const": "https://ursy.id/oidc"
}
},
"required": [
"memberships",
"authority"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/teams": {
"post": {
"operationId": "create_team",
"description": "Bind the owner\u2019s current canonical workspace to an ID-owned organisation. Existing files retain IDs and versions.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.teams.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R3",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"result": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"result"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false
}
}
}
}
}
},
"/v1/teams/{organisation_id}/members/{subject}": {
"post": {
"operationId": "update_team_member",
"description": "Change an ID-owned membership with optimistic version safety; roles cap every subsequent API request.",
"security": [
{
"CloudGrant": []
}
],
"x-required-scope": "cloud.teams.manage",
"x-resource-bounds-enforced": true,
"x-risk": "R3",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"result": {
"type": "object",
"additionalProperties": true
}
},
"required": [
"result"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"parameters": [
{
"name": "organisation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"maxLength": 128,
"x-ursy-maxBytes": 128
}
},
{
"name": "subject",
"in": "path",
"required": true,
"schema": {
"type": "string",
"maxLength": 128,
"x-ursy-maxBytes": 128
}
},
{
"name": "Idempotency-Key",
"in": "header",
"required": true,
"schema": {
"type": "string",
"minLength": 8,
"maxLength": 128,
"pattern": "^[A-Za-z0-9._:-]+$"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"role": {
"type": "string",
"enum": [
"owner",
"admin",
"editor",
"commenter",
"viewer"
]
},
"state": {
"type": "string",
"enum": [
"ACTIVE",
"SUSPENDED",
"REVOKED"
]
},
"expected_version": {
"type": "integer",
"minimum": 0
}
},
"required": [
"role",
"state",
"expected_version"
]
}
}
}
}
}
},
"/v1/metrics": {
"get": {
"operationId": "get_api_metrics",
"description": "Read seven-day aggregate operation/status/duration counters, without user or content data.",
"security": [],
"x-required-scope": null,
"x-resource-bounds-enforced": true,
"x-risk": "R0",
"responses": {
"200": {
"description": "Typed operation result; request_id correlates the request.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true,
"properties": {
"schema": {
"const": "ursy.cloud/aggregate-usage/v1"
},
"window_days": {
"const": 7
},
"rows": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"properties": {
"day": {
"type": "string"
},
"operation": {
"type": "string"
},
"surface": {
"type": "string"
},
"status_class": {
"type": "integer"
},
"count": {
"type": "integer"
},
"max_ms": {
"type": "integer"
},
"mean_ms": {
"type": "number"
}
},
"required": [
"day",
"operation",
"surface",
"status_class",
"count",
"max_ms",
"mean_ms"
]
},
"minItems": 0,
"maxItems": 3000
},
"privacy": {
"type": "string"
},
"coverage": {
"type": "string"
}
},
"required": [
"schema",
"window_days",
"rows",
"privacy",
"coverage"
]
}
}
}
},
"default": {
"description": "Stable error envelope. 401 invalid/expired/revoked grant; 403 missing scope; 404 unavailable resource; 409 plan/idempotency conflict; 412 stale ETag; 413 size/quota; 429 rate limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/uploads/{upload_id}/chunks/{index}": {
"put": {
"security": [
{
"CloudGrant": []
}
],
"x-ursy-binary-transport": true,
"operationId": "put_upload_chunk",
"description": "Raw binary transport; send exactly one chunk with its SHA-256. Retry the same index with identical bytes. Control operations are also available through MCP.",
"x-required-scope": "cloud.upload",
"parameters": [
{
"name": "upload_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
}
},
{
"name": "index",
"in": "path",
"required": true,
"schema": {
"type": "integer",
"minimum": 0,
"maximum": 24
}
},
{
"name": "X-Chunk-SHA256",
"in": "header",
"required": true,
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
}
],
"requestBody": {
"required": true,
"description": "Up to 1048576 raw bytes; final chunk is the exact remainder.",
"content": {
"application/octet-stream": []
}
},
"responses": {
"200": {
"description": "Resumable status after storing or replaying the chunk.",
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"upload": {
"type": "object",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"pattern": "^upl_[a-f0-9]{32}$"
},
"state": {
"type": "string",
"enum": [
"pending",
"completed",
"cancelled"
]
},
"name": {
"type": "string"
},
"mime": {
"type": "string"
},
"size": {
"type": "integer",
"minimum": 0
},
"sha256": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
},
"chunk_bytes": {
"const": 1048576
},
"chunk_count": {
"type": "integer",
"minimum": 0
},
"received_bytes": {
"type": "integer",
"minimum": 0
},
"next_chunk_index": {
"type": "integer",
"minimum": 0
},
"expires_at": {
"type": "string"
},
"file_id": {
"oneOf": [
{
"type": "string",
"pattern": "^file_[1-9][0-9]{0,14}$"
},
{
"type": "null"
}
]
},
"version_id": {
"oneOf": [
{
"type": "string",
"pattern": "^ver_[1-9][0-9]*$"
},
{
"type": "null"
}
]
},
"chunk_url_template": {
"type": "string"
},
"chunk_method": {
"type": "string",
"enum": [
"PUT"
]
},
"authorization": {
"type": "string"
}
},
"required": [
"id",
"state",
"name",
"mime",
"size",
"sha256",
"chunk_bytes",
"chunk_count",
"received_bytes",
"next_chunk_index",
"expires_at",
"file_id",
"version_id",
"chunk_url_template",
"chunk_method",
"authorization"
]
},
"replayed": {
"type": "boolean"
},
"request_id": {
"type": "string"
}
},
"required": [
"upload",
"replayed"
]
}
}
}
},
"default": {
"description": "Typed permission, expiry, integrity, size, conflict or storage error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/downloads/{download_id}/content": {
"get": {
"security": [
{
"CloudGrant": []
}
],
"x-ursy-binary-transport": true,
"operationId": "download_binary",
"description": "Verified attachment bytes. Requires the original still-active grant and an unexpired download record. A URL alone authorizes nothing. HEAD returns the same headers without bytes.",
"x-required-scope": "cloud.files.binary.read",
"parameters": [
{
"name": "download_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^dl_[a-f0-9]{32}$"
}
}
],
"responses": {
"200": {
"description": "Raw verified bytes; maximum 25 MiB.",
"headers": {
"X-Content-SHA256": {
"schema": {
"type": "string",
"pattern": "^[a-f0-9]{64}$"
}
},
"Content-Disposition": {
"schema": {
"type": "string"
}
}
},
"content": {
"application/octet-stream": []
}
},
"default": {
"description": "Typed permission, expiry, integrity, size, conflict or storage error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/v1/tasks/{task_id}/content": {
"get": {
"security": [
{
"CloudGrant": []
}
],
"x-ursy-binary-transport": true,
"operationId": "download_workspace_export",
"description": "Private ZIP with per-entry checksums. Original active grant and five-minute authorization required.",
"parameters": [
{
"name": "task_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"pattern": "^task_[a-f0-9]{32}$"
}
}
],
"responses": {
"200": {
"description": "Verified ZIP export.",
"content": {
"application/zip": []
}
},
"default": {
"description": "Typed permission, expiry, integrity, size, conflict or storage error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"Error": {
"type": "object",
"additionalProperties": false,
"properties": {
"error": {
"type": "object",
"additionalProperties": false,
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
},
"request_id": {
"type": "string"
},
"retryable": {
"type": "boolean"
},
"details": {
"type": "object"
}
},
"required": [
"code",
"message",
"request_id",
"retryable",
"details"
]
}
},
"required": [
"error"
]
}
},
"securitySchemes": {
"CloudGrant": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "Cloud access token or ucg_<opaque-secret>",
"description": "A Cloud-audience URSY.ID access token with explicit resource consent, or an operator grant. OIDC ID tokens are not accepted."
}
}
}
}