{ "swagger": "2.0", "info": { "description": "This API powers slashdocs, a collaborative workspace where agents and people publish self-contained HTML documents, comment on specific text ranges inside them, and publish new versions.", "title": "slashdocs API", "contact": {}, "version": "v1" }, "basePath": "/", "paths": { "/.well-known/slashdocs.json": { "get": { "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Deployment discovery", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.discoveryResponse" } } } } }, "/commit.txt": { "get": { "produces": [ "text/plain" ], "tags": [ "discovery" ], "summary": "Build commit SHA", "responses": { "200": { "description": "OK", "schema": { "type": "string" } } } } }, "/v/{id}/{version_id}": { "get": { "produces": [ "text/html" ], "tags": [ "render" ], "summary": "Render version wrapper", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Version ID", "name": "version_id", "in": "path", "required": true }, { "type": "string", "description": "Render token", "name": "token", "in": "query", "required": true }, { "type": "integer", "description": "Seq of the source to render. Without it, or when the server no longer has that seq, the content of the version.", "name": "seq", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "string" } } } } }, "/v1/access-requests": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "The newest first, across every document on which the caller manages access. Each request names its document.", "tags": [ "documents" ], "summary": "List requests for access to the documents that the caller manages", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-repo_DocumentAccessRequest" } } } } }, "/v1/auth/cli/credentials": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "List CLI credentials", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-repo_CLICredential" } } } } }, "/v1/auth/cli/credentials/{id}": { "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "auth" ], "summary": "Revoke CLI credential", "parameters": [ { "type": "string", "description": "Credential ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/v1/auth/cli/exchange": { "post": { "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Exchange CLI login code", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.cliExchangeResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/auth/google/callback": { "get": { "tags": [ "auth" ], "summary": "OIDC login callback", "parameters": [ { "type": "string", "description": "OAuth code", "name": "code", "in": "query", "required": true }, { "type": "string", "description": "OAuth state", "name": "state", "in": "query", "required": true } ], "responses": { "302": { "description": "Found" } } } }, "/v1/auth/google/start": { "get": { "tags": [ "auth" ], "summary": "Start OIDC login", "parameters": [ { "type": "string", "description": "web or cli", "name": "mode", "in": "query" }, { "type": "string", "description": "web redirect", "name": "redirect", "in": "query" }, { "type": "string", "description": "CLI loopback redirect", "name": "cli_redirect", "in": "query" }, { "type": "string", "description": "PKCE challenge", "name": "code_challenge", "in": "query" }, { "type": "string", "description": "CLI correlation state; web state is generated by the server", "name": "state", "in": "query" } ], "responses": { "302": { "description": "Found" } } } }, "/v1/auth/logout": { "post": { "description": "Clears the session cookie. CLI credentials stay valid.", "tags": [ "auth" ], "summary": "End the browser session", "responses": { "204": { "description": "No Content" } } } }, "/v1/auth/oidc/callback": { "get": { "tags": [ "auth" ], "summary": "OIDC login callback", "parameters": [ { "type": "string", "description": "OAuth code", "name": "code", "in": "query", "required": true }, { "type": "string", "description": "OAuth state", "name": "state", "in": "query", "required": true } ], "responses": { "302": { "description": "Found" } } } }, "/v1/auth/oidc/start": { "get": { "tags": [ "auth" ], "summary": "Start OIDC login", "parameters": [ { "type": "string", "description": "web or cli", "name": "mode", "in": "query" }, { "type": "string", "description": "web redirect", "name": "redirect", "in": "query" }, { "type": "string", "description": "CLI loopback redirect", "name": "cli_redirect", "in": "query" }, { "type": "string", "description": "PKCE challenge", "name": "code_challenge", "in": "query" }, { "type": "string", "description": "CLI correlation state; web state is generated by the server", "name": "state", "in": "query" } ], "responses": { "302": { "description": "Found" } } } }, "/v1/config": { "get": { "produces": [ "application/json" ], "tags": [ "discovery" ], "summary": "Deployment configuration", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.configResponse" } } } } }, "/v1/documents": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "documents" ], "summary": "List documents", "parameters": [ { "type": "string", "description": "Slack-style search of titles and text: words, \\", "name": "q", "in": "query" }, { "type": "string", "description": "IANA time zone for date modifiers; defaults to UTC", "name": "tz", "in": "query" }, { "type": "string", "description": "Deprecated exact label filter; use q=label:\u003clabel\u003e", "name": "label", "in": "query" }, { "type": "integer", "description": "Page size: 25 by default, 100 at most", "name": "limit", "in": "query" }, { "type": "integer", "description": "The number of documents to skip", "name": "offset", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.documentListResponse" } } } }, "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "consumes": [ "multipart/form-data" ], "produces": [ "application/json" ], "tags": [ "documents" ], "summary": "Create document", "parameters": [ { "type": "string", "description": "Document title", "name": "title", "in": "formData", "required": true }, { "type": "file", "description": "Single-file HTML", "name": "file", "in": "formData", "required": true }, { "type": "string", "description": "The folder for the document. The caller needs editor on it. The default is the root.", "name": "folder_id", "in": "formData" }, { "type": "string", "description": "Default sharing applied at create: viewer, commenter, editor or private. Overrides the server-wide default.", "name": "default_permission", "in": "formData" } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.createDocumentResponse" } } } } }, "/v1/documents/{id}": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "documents" ], "summary": "Get document", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.Document" } } } }, "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "documents" ], "summary": "Delete document", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } }, "patch": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "documents" ], "summary": "Update document", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.Document" } } } } }, "/v1/documents/{id}/access-requests": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "The newest first. People who manage access see every request. Other callers see only their own request, so that they know it waits. A grant on the document to the requester removes the request.", "tags": [ "documents" ], "summary": "List requests for access to a document", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-repo_AccessRequest" } } } }, "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Records the request for the people who manage access, and notifies the current owner when notifications are enabled. The response does not reveal whether the document or owner exists. Repeated requests are coalesced.", "tags": [ "documents" ], "summary": "Request access to a document", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "202": { "description": "Accepted", "schema": { "type": "object", "additionalProperties": { "type": "string" } } } } } }, "/v1/documents/{id}/access-requests/{requester_type}/{requester_id}": { "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Removes the request without a grant. The requester can ask again.", "tags": [ "documents" ], "summary": "Decline a request for access to a document", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "enum": [ "user", "service_account" ], "type": "string", "description": "Requester type", "name": "requester_type", "in": "path", "required": true }, { "type": "string", "description": "Requester ID", "name": "requester_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/v1/documents/{id}/approvals": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Per-approver decisions on the content of a version (current version by default), merged with pending approvers, plus the derived aggregate status. A decision made on an earlier version with the same content counts, and names that version.", "tags": [ "approvals" ], "summary": "List decisions and aggregate status", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Version ID (defaults to the current version)", "name": "version", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.approvalsListResponse" } } } }, "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Records the caller's decision on the content of a version. The open version is sealed first. The decision vouches for that content, so every version with the same content shows it. Submitting again replaces the previous decision on that content. A rejection needs a note unless the caller has open comment threads on the document (the comments say what to change). Returns 409 version_superseded when the document's content changed since that version, or when seq, the seq that the page of the caller shows, is not the seq of the live document, or when another person typed in the document in the last 10 seconds: the message then says to approve when they are done. With no seq, as from the CLI, the decision is on the live document, and version_id in the answer names the sealed version. A decision on an open version that holds the text of the version before it is for that version.", "tags": [ "approvals" ], "summary": "Submit or update a decision", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.approvalResponse" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.approvalResponse" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/documents/{id}/approvals/{approval_id}": { "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Removes the caller's decision, returning them to pending. Assignment is unaffected.", "tags": [ "approvals" ], "summary": "Revoke own decision", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Approval ID", "name": "approval_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/v1/documents/{id}/approvers": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "approvals" ], "summary": "List assigned approvers", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-server_approvalRequestResponse" } } } }, "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Assigns a user or service account as an approver. The approver must already have at least viewer access on the document. An approver who loses viewer access when a grant is revoked stops being an approver. The request is for no version: the approver decides on the version that they read.", "tags": [ "approvals" ], "summary": "Assign an approver", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.approvalRequestResponse" } } } } }, "/v1/documents/{id}/approvers/{approver_id}": { "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Removes the assignment and revokes all of that approver's decisions on the document.", "tags": [ "approvals" ], "summary": "Remove an approver", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Approval request ID", "name": "approver_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/v1/documents/{id}/changes": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "For the browser, which follows the document while other people edit it. ops are the operations after the seq after, in order. Each one is a list of replacements on the source before it: start and end count UTF-8 bytes, and end is exclusive. The caller applies them in order to the source at after, and then has the source at seq, the live document. sum is the CRC-32 (IEEE) of the UTF-8 bytes of that source. typed is true when the browser editor made every one of the operations. authors made them, and the author of the newest comes first. The response is 409 stale when the log no longer holds every operation after the seq: load the document again.", "tags": [ "versions" ], "summary": "Get the operations after a seq", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "integer", "description": "Seq of the source that the caller has", "name": "after", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.DocumentChanges" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/documents/{id}/comments": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "comments" ], "summary": "List comments", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Thread status: open or resolved. Empty or all lists every thread. Replies travel with their thread.", "name": "status", "in": "query" }, { "type": "string", "description": "Version ID", "name": "version_id", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-server_commentResponse" } } } }, "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Requests with non-empty mentions must use Content-Type application/vnd.slashdocs.comment-mentions+json so mixed-version deployments fail closed instead of dropping metadata.\nThe anchor is a text anchor with a non-empty quote, or a point: anchor.point names an element by target (its data-slashdocs-target value or id), path (its child-index path under the body), or both, and x and y are fractions of its box, from 0 to 1 inside it and from -1000 to 1000 in all. A point may also give page_x and page_y, the spot in CSS pixels from the top left of the page, with viewport_w, the viewport width: they place the pin when a later version no longer has the element, and they alone put a point on the body. The text fields of a point hold the start of the element's text, which finds the element again after the document changes.", "consumes": [ "application/json", "application/vnd.slashdocs.comment-mentions+json" ], "tags": [ "comments" ], "summary": "Create comment", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "description": "Comment body, anchor, and structured mentions", "name": "comment", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.createCommentRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.commentResponse" } } } } }, "/v1/documents/{id}/comments/{comment_id}": { "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "comments" ], "summary": "Delete comment", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Comment ID", "name": "comment_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } }, "patch": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Any request containing the mentions key, including an empty array, must use Content-Type application/vnd.slashdocs.comment-mentions+json so mixed-version deployments fail closed. An anchor with a point moves a point comment to a new spot. Text comments follow their text.", "consumes": [ "application/json", "application/vnd.slashdocs.comment-mentions+json" ], "tags": [ "comments" ], "summary": "Update comment", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Comment ID", "name": "comment_id", "in": "path", "required": true }, { "description": "Fields to update; omitted mentions are preserved unless the body changes", "name": "update", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.patchCommentRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.commentResponse" } }, "409": { "description": "comment_changed: the body is no longer base_body", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/documents/{id}/comments/{comment_id}/reactions/{emoji}": { "put": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Adds the caller's reaction to a comment or reply. Repeating the same reaction is a no-op.", "tags": [ "comments" ], "summary": "Add comment reaction", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Comment ID", "name": "comment_id", "in": "path", "required": true }, { "enum": [ "+1", "-1", "laugh", "hooray", "confused", "heart", "rocket", "eyes", "plus" ], "type": "string", "description": "Reaction slug", "name": "emoji", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } }, "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Removes the caller's reaction from a comment or reply. Removing an absent reaction is a no-op.", "tags": [ "comments" ], "summary": "Remove comment reaction", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Comment ID", "name": "comment_id", "in": "path", "required": true }, { "enum": [ "+1", "-1", "laugh", "hooray", "confused", "heart", "rocket", "eyes", "plus" ], "type": "string", "description": "Reaction slug", "name": "emoji", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/v1/documents/{id}/comments/{comment_id}/read": { "put": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Sets the caller's read time of a thread to now. The thread then shows as read to the caller until someone else adds a message to it. Only the thread's first comment takes a mark: a reply id answers 404.", "tags": [ "comments" ], "summary": "Mark comment thread read", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Thread ID, the id of the thread's first comment", "name": "comment_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "404": { "description": "not_found: no such thread in the document", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/documents/{id}/comments/{comment_id}/replies": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Requests with non-empty mentions must use Content-Type application/vnd.slashdocs.comment-mentions+json so mixed-version deployments fail closed instead of dropping metadata.", "consumes": [ "application/json", "application/vnd.slashdocs.comment-mentions+json" ], "tags": [ "comments" ], "summary": "Create comment reply", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Parent Comment ID", "name": "comment_id", "in": "path", "required": true }, { "description": "Reply body and structured mentions", "name": "reply", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.createCommentReplyRequest" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.commentResponse" } } } } }, "/v1/documents/{id}/edits": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Applies exact find-and-replace edits to the live document on the server and saves the result as a new version. Each old_string must occur exactly once. The edits apply in order, and either all apply or none do. The HTML is never parsed, so everything else stays byte-for-byte the same. When the edits together leave the document as it is, the response is 200 with unchanged set and the current version.", "consumes": [ "application/json" ], "tags": [ "versions" ], "summary": "Edit document text", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "description": "Edits", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.editDocumentRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.editDocumentResponse" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.editDocumentResponse" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/documents/{id}/grants": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "grants" ], "summary": "Create document grant", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.createGrantResponse" } } } } }, "/v1/documents/{id}/grants/{grant_id}": { "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "grants" ], "summary": "Delete document grant", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Grant ID", "name": "grant_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } }, "patch": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "grants" ], "summary": "Update document grant", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Grant ID", "name": "grant_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.Grant" } } } } }, "/v1/documents/{id}/headings": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Lists headings in stored HTML. Explicit HTML IDs are preserved. JavaScript-only headings appear in the viewer when created.", "tags": [ "documents" ], "summary": "List document headings and shareable links", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Version ID (pins links to this version)", "name": "version", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-server_headingResponse" } } } } }, "/v1/documents/{id}/link": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "documents" ], "summary": "Get a shareable link to a document, comment, or heading", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Comment or reply ID", "name": "comment", "in": "query" }, { "type": "string", "description": "Heading ID, including an ID created by document JavaScript", "name": "heading", "in": "query" }, { "type": "string", "description": "Version ID for a heading or document link", "name": "version", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.documentLinkResponse" } } } } }, "/v1/documents/{id}/notifications": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "notifications" ], "summary": "Read your notification preferences for a document", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.NotificationPreferences" } } } }, "put": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Personal preference only. Global disable overrides this preference.", "consumes": [ "application/json" ], "tags": [ "notifications" ], "summary": "Enable or mute your document notifications", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "description": "Notification preference", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.notificationPreferencesRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.NotificationPreferences" } } } } }, "/v1/documents/{id}/ops": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "For the browser editor. Applies replacements by position in the source at base_seq to the live document. start and end count UTF-8 bytes, end is exclusive, and old_html must be the source from start to end at base_seq. Replacements are in order and do not overlap. A replacement whose old_html is its new_html changes nothing: the server drops it, and others never holds one. The operation makes no version: the first operation after a sealed version opens the next version, and the server seals it after 10 minutes with no operation, or before a write that is not typing. When the document had operations after base_seq, the replacements move over them, and others holds those operations in order, as they apply to the source that the caller made (the source at base_seq with its replacements). Text that both put in at one point stays twice, text that either takes out goes, and two replacements of the same words both stay whole, the later one first. sum is the CRC-32 (IEEE) of the UTF-8 bytes of the source at seq: a caller whose source has another sum loads the document again. A retry with the same client_op_id applies nothing and gets the answer of the first attempt. When the server no longer has that answer, the response is 409 stale with details.applied set: the document has the operation, so the caller gets the live document and does not send that text again. summary holds at most 200 characters. The response is 409 stale when the log no longer holds the operations after base_seq, or when base_seq is more than 2000 operations behind: get the live document, and send the text that is not sent yet again on its seq.", "consumes": [ "application/json" ], "tags": [ "versions" ], "summary": "Write an operation of the browser editor", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "description": "Operation", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.operationRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.OperationResult" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "413": { "description": "Request Entity Too Large", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/documents/{id}/versions": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "A version is a checkpoint: a burst of editing in the browser, a push, an edit or a restore. The newest version is open while people type in it: its change_summary then says what changed up to now, and it is not in the list while its content is that of the version before. edited_at is the time of the last operation of a version, or created_at when the server holds none. authors are its creator and the people whose operations it holds.", "tags": [ "versions" ], "summary": "List versions", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-repo_Version" } } } }, "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Saves the uploaded HTML, which must be valid UTF-8, as a new version. When people changed the document after the base, the changes from the base to the upload move onto the live document, and the response has rebased set: the new version is then not the uploaded file. When the upload changes text that people changed after the base, the response is 409 version_conflict and their text stays: get the document and make the change again. details.text, when set, is the sentence that holds that text, in plain words, so that a person can find the place. When the upload is the document as it is, the response is 200 with unchanged set and the current version: no version is made. The base is the content of the base version, when the request has no base_seq or the seq of that version. With a base_seq before the seq of the base version, the base is the document at base_seq: the file was made from the version while it was open. The response is 409 stale when the base is an open version with no base_seq, or when the server no longer has the document at base_seq. It is 422 base_version_not_found when base_version_id is not a version of the document.", "consumes": [ "multipart/form-data" ], "tags": [ "versions" ], "summary": "Create version", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Base version ID", "name": "base_version_id", "in": "formData", "required": true }, { "type": "string", "description": "Change summary", "name": "change_summary", "in": "formData" }, { "type": "integer", "description": "Seq of the base version that the file was made from, from the X-Slashdocs-Seq header of its HTML. Necessary when that version was open.", "name": "base_seq", "in": "formData" }, { "type": "file", "description": "HTML file", "name": "file", "in": "formData", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.createVersionResponse" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.createVersionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "413": { "description": "Request Entity Too Large", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "422": { "description": "Unprocessable Entity", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/documents/{id}/versions/{version_id}": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "The change_summary of the open version says what changed up to now.", "tags": [ "versions" ], "summary": "Get version metadata", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Version ID", "name": "version_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.Version" } } } } }, "/v1/documents/{id}/versions/{version_id}/html": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Gives the content of the version. For the open version that is the live document, and no read seals a version. The header X-Slashdocs-Seq has the seq of the HTML: send it as base_seq with a push that was made from this HTML. With seq, gives the source at that seq. The response is 409 stale for a seq that the version can no longer give.", "produces": [ "text/html" ], "tags": [ "versions" ], "summary": "Get version HTML", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Version ID", "name": "version_id", "in": "path", "required": true }, { "type": "integer", "description": "Seq of the source", "name": "seq", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "type": "string" }, "headers": { "X-Slashdocs-Seq": { "type": "integer", "description": "Seq of the HTML" } } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/documents/{id}/versions/{version_id}/render-token": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Gives a URL that renders the version, and the seq of the source that the URL renders. For an open version that is the seq of the live document now.", "tags": [ "versions" ], "summary": "Create render token", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Version ID", "name": "version_id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.renderTokenResponse" } } } } }, "/v1/documents/{id}/versions/{version_id}/restore": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Saves the content of an earlier version as the newest version, as an edit by the caller. History keeps every version, so a restore can itself be undone by restoring again. When the document has that content now, the response is 200 with unchanged set and the current version.", "consumes": [ "application/json" ], "tags": [ "versions" ], "summary": "Restore version", "parameters": [ { "type": "string", "description": "Document ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Version ID to restore", "name": "version_id", "in": "path", "required": true }, { "description": "Change summary", "name": "body", "in": "body", "schema": { "$ref": "#/definitions/server.restoreVersionRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.createVersionResponse" } }, "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.createVersionResponse" } }, "400": { "description": "Bad Request", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "409": { "description": "Conflict", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/folders": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "With no parameters, lists the folders and documents at the root of the caller. With folder_id or path, lists the contents of that folder. With q or min_role, searches the folders that the caller can see by title, at most 25: min_role keeps only the folders on which the caller has at least that role, and min_role with no q lists every such folder, for a picker such as the move dialog.", "tags": [ "folders" ], "summary": "List or search folders", "parameters": [ { "type": "string", "description": "Folder ID to list", "name": "folder_id", "in": "query" }, { "type": "string", "description": "Folder path to list, such as /A/B", "name": "path", "in": "query" }, { "type": "string", "description": "Words of a folder title", "name": "q", "in": "query" }, { "enum": [ "viewer", "commenter", "editor", "owner" ], "type": "string", "description": "Least role of the caller on each folder of a search", "name": "min_role", "in": "query" } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.folderListResponse" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "409": { "description": "ambiguous_path: more than one folder has a name of the path", "schema": { "$ref": "#/definitions/server.ambiguousPathResponse" } } } } }, "/v1/folders/{id}/documents": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "The caller needs the editor role on the document and on the folder. The caller also needs the editor role on the folder that the document leaves, unless the caller owns the document. permission_warning is set when the folder gives access to more people than the document had.", "tags": [ "folders" ], "summary": "Move a document into a folder", "parameters": [ { "type": "string", "description": "Folder ID", "name": "id", "in": "path", "required": true }, { "description": "The document to move", "name": "body", "in": "body", "required": true, "schema": { "type": "object", "properties": { "document_id": { "type": "string" } } } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.moveDocResponse" } }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/folders/{id}/documents/{doc_id}": { "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "The caller needs the editor role on the document, and on the folder that it leaves unless the caller owns the document.", "tags": [ "folders" ], "summary": "Move a document out of a folder to the root", "parameters": [ { "type": "string", "description": "Folder ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Document ID", "name": "doc_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" }, "403": { "description": "Forbidden", "schema": { "$ref": "#/definitions/server.errorEnvelope" } }, "404": { "description": "Not Found", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/folders/{id}/grants": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "grants" ], "summary": "Create folder grant", "parameters": [ { "type": "string", "description": "Folder ID", "name": "id", "in": "path", "required": true }, { "description": "Grant target and role; google_group principals are resolved from principal.email", "name": "grant", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.grantInput" } } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/repo.Grant" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/google-groups": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "google-groups" ], "summary": "Search verified organization Google Groups", "parameters": [ { "type": "string", "description": "Email or display-name query (minimum 2 characters)", "name": "q", "in": "query", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.googleGroupSearchResponse" } }, "400": { "description": "Bad Request", "schema": { "type": "object", "additionalProperties": true } }, "503": { "description": "Service Unavailable", "schema": { "type": "object", "additionalProperties": true } } } } }, "/v1/me": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "produces": [ "application/json" ], "tags": [ "auth" ], "summary": "Current principal", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.meResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/me/inbox": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "The newest first, at most 50: each document that the caller approves and did not decide on (kind approval), and each open thread on a document of the caller, that they wrote in, or that mentions them, with a message by someone else after their last read or message (kind thread). It holds only documents that the caller can read now.", "tags": [ "documents" ], "summary": "List what waits on the caller", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-repo_InboxItem" } }, "429": { "description": "Too Many Requests", "schema": { "$ref": "#/definitions/server.errorEnvelope" } } } } }, "/v1/me/notifications": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "notifications" ], "summary": "Read your notification preferences", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.NotificationPreferences" } } } }, "put": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "description": "Applies only to the authenticated principal. Document preferences never change access or other users' notifications. Global disable overrides document preferences.", "consumes": [ "application/json" ], "tags": [ "notifications" ], "summary": "Set your notification preferences", "parameters": [ { "description": "Notification preference", "name": "body", "in": "body", "required": true, "schema": { "$ref": "#/definitions/server.notificationPreferencesRequest" } } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.NotificationPreferences" } } } } }, "/v1/service-accounts": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "List service accounts", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-repo_ServiceAccount" } } } }, "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "consumes": [ "application/json" ], "produces": [ "application/json" ], "tags": [ "service-accounts" ], "summary": "Create service account", "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.createServiceAccountResponse" } } } } }, "/v1/service-accounts/transfers": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "List service account ownership transfers", "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-repo_OwnershipTransfer" } } } } }, "/v1/service-accounts/transfers/{id}/accept": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "Accept ownership transfer", "parameters": [ { "type": "string", "description": "Transfer ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.OwnershipTransfer" } } } } }, "/v1/service-accounts/transfers/{id}/decline": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "Decline ownership transfer", "parameters": [ { "type": "string", "description": "Transfer ID", "name": "id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/v1/service-accounts/{id}": { "patch": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "Update service account", "parameters": [ { "type": "string", "description": "Service account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/repo.ServiceAccount" } } } } }, "/v1/service-accounts/{id}/keys": { "get": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "List service account keys", "parameters": [ { "type": "string", "description": "Service account ID", "name": "id", "in": "path", "required": true } ], "responses": { "200": { "description": "OK", "schema": { "$ref": "#/definitions/server.listResponse-repo_ServiceAccountKey" } } } }, "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "Create service account key", "parameters": [ { "type": "string", "description": "Service account ID", "name": "id", "in": "path", "required": true } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/server.serviceAccountKey" } } } } }, "/v1/service-accounts/{id}/keys/{key_id}": { "delete": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "Revoke service account key", "parameters": [ { "type": "string", "description": "Service account ID", "name": "id", "in": "path", "required": true }, { "type": "string", "description": "Key ID", "name": "key_id", "in": "path", "required": true } ], "responses": { "204": { "description": "No Content" } } } }, "/v1/service-accounts/{id}/transfer": { "post": { "security": [ { "bearerAuth": [] }, { "cookieAuth": [] } ], "tags": [ "service-accounts" ], "summary": "Initiate service account ownership transfer", "parameters": [ { "type": "string", "description": "Service account ID", "name": "id", "in": "path", "required": true } ], "responses": { "201": { "description": "Created", "schema": { "$ref": "#/definitions/repo.OwnershipTransfer" } } } } } }, "definitions": { "auth.Principal": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "picture_url": { "type": "string" }, "type": { "$ref": "#/definitions/auth.PrincipalType" } } }, "auth.PrincipalType": { "type": "string", "enum": [ "user", "service_account", "google_group", "anyone", "anonymous" ], "x-enum-varnames": [ "PrincipalUser", "PrincipalServiceAccount", "PrincipalGoogleGroup", "PrincipalAnyone", "PrincipalAnonymous" ] }, "repo.AccessRequest": { "type": "object", "properties": { "requested_at": { "type": "string" }, "requester": { "$ref": "#/definitions/auth.Principal" } } }, "repo.Anchor": { "type": "object", "properties": { "dom_path": { "type": "string" }, "end_offset": { "type": "integer" }, "point": { "description": "Point pins the comment to a spot in an element instead of to the quoted\ntext. The text fields then hold the start of the element's own text,\nwhich finds the element again after the document changes.", "allOf": [ { "$ref": "#/definitions/repo.AnchorPoint" } ] }, "prefix": { "type": "string" }, "quote": { "type": "string" }, "start_offset": { "type": "integer" }, "suffix": { "type": "string" } } }, "repo.AnchorPoint": { "type": "object", "properties": { "label": { "type": "string" }, "page_x": { "type": "number" }, "page_y": { "type": "number" }, "path": { "type": "string" }, "target": { "type": "string" }, "viewport_w": { "type": "number" }, "x": { "type": "number" }, "y": { "type": "number" } } }, "repo.ApprovalSummary": { "type": "object", "properties": { "approved": { "type": "integer" }, "pending": { "type": "integer" }, "rejected": { "type": "integer" }, "total": { "type": "integer" } } }, "repo.CLICredential": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "repo.Document": { "type": "object", "properties": { "approval_status": { "description": "ApprovalStatus and ApprovalSummary are handler-populated (like\nParentFolder) and only present when the document has assigned approvers.", "type": "string" }, "approval_summary": { "$ref": "#/definitions/repo.ApprovalSummary" }, "can_move": { "description": "CanMove is set by GET /v1/documents/{id}: the caller may move it.", "type": "boolean" }, "current_version_id": { "type": "string" }, "id": { "type": "string" }, "labels": { "type": "array", "items": { "type": "string" } }, "owner": { "$ref": "#/definitions/auth.Principal" }, "parent_folder": { "$ref": "#/definitions/repo.FolderBreadcrumb" }, "parent_folder_id": { "type": "string" }, "seq": { "description": "Seq is the sequence number of the live document. Lists do not set it.", "type": "integer" }, "snippet": { "description": "Snippet is set in search results when the text matches. U+0002 and\nU+0003 surround each match.", "type": "string" }, "title": { "type": "string" }, "updated_at": { "type": "string" } } }, "repo.DocumentAccessRequest": { "type": "object", "properties": { "document_id": { "type": "string" }, "document_title": { "type": "string" }, "requested_at": { "type": "string" }, "requester": { "$ref": "#/definitions/auth.Principal" } } }, "repo.DocumentChanges": { "type": "object", "properties": { "authors": { "description": "Authors made those operations. The author of the newest comes first.", "type": "array", "items": { "$ref": "#/definitions/auth.Principal" } }, "ops": { "description": "Ops are the operations after the earlier seq, in order. Each one is a\nlist of replacements on the source before it.", "type": "array", "items": { "type": "array", "items": { "type": "object" } } }, "seq": { "type": "integer" }, "sum": { "description": "Sum is the CRC-32 (IEEE) of the UTF-8 bytes of the source at Seq.", "type": "integer" }, "typed": { "description": "Typed is set when the browser editor made every one of them.", "type": "boolean" }, "version_id": { "type": "string" } } }, "repo.Folder": { "type": "object", "properties": { "ancestors": { "type": "array", "items": { "$ref": "#/definitions/repo.FolderBreadcrumb" } }, "id": { "type": "string" }, "owner": { "$ref": "#/definitions/auth.Principal" }, "parent_folder_id": { "type": "string" }, "title": { "type": "string" } } }, "repo.FolderBreadcrumb": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" } } }, "repo.FolderEntry": { "type": "object", "properties": { "document": { "$ref": "#/definitions/repo.Document" }, "folder": { "$ref": "#/definitions/repo.Folder" }, "last_active": { "type": "string" }, "type": { "type": "string" } } }, "repo.Grant": { "type": "object", "properties": { "document_id": { "type": "string" }, "granted_by": { "$ref": "#/definitions/auth.Principal" }, "id": { "type": "string" }, "principal": { "$ref": "#/definitions/auth.Principal" }, "resource_id": { "type": "string" }, "resource_type": { "type": "string" }, "role": { "$ref": "#/definitions/repo.Role" } } }, "repo.InboxItem": { "type": "object", "properties": { "at": { "type": "string" }, "body": { "type": "string" }, "comment_id": { "type": "string" }, "document_id": { "type": "string" }, "document_title": { "type": "string" }, "from": { "description": "From asked for the approval, or wrote the newest unread message, Body.", "allOf": [ { "$ref": "#/definitions/auth.Principal" } ] }, "kind": { "description": "Kind is \"approval\" for a document to approve, or \"thread\" for a thread\nwith a message to read.", "type": "string" } } }, "repo.NotificationPreferences": { "type": "object", "properties": { "effective_enabled": { "type": "boolean" }, "enabled": { "type": "boolean" } } }, "repo.OperationResult": { "type": "object", "properties": { "others": { "description": "Others are the operations that the document had after the base seq,\nas they apply to the source that the sender made: the state at the base seq with its replacements. The\nsender applies them in order, and then has the source at Seq.", "type": "array", "items": { "type": "array", "items": { "$ref": "#/definitions/textedit.Replacement" } } }, "seq": { "type": "integer" }, "sum": { "description": "Sum is the CRC-32 (IEEE) of the UTF-8 bytes of the source at Seq.", "type": "integer" }, "version_id": { "type": "string" } } }, "repo.OwnershipTransfer": { "type": "object", "properties": { "from_user_id": { "type": "string" }, "id": { "type": "string" }, "service_account_id": { "type": "string" }, "status": { "type": "string" }, "to_user_id": { "type": "string" } } }, "repo.Role": { "type": "string", "enum": [ "", "viewer", "commenter", "editor", "owner" ], "x-enum-varnames": [ "RoleNone", "RoleViewer", "RoleCommenter", "RoleEditor", "RoleOwner" ] }, "repo.ServiceAccount": { "type": "object", "properties": { "disabled": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "$ref": "#/definitions/auth.Principal" } } }, "repo.ServiceAccountKey": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } }, "repo.Version": { "type": "object", "properties": { "authors": { "description": "Authors are the creator of the version and the people whose\noperations it holds.", "type": "array", "items": { "$ref": "#/definitions/auth.Principal" } }, "change_summary": { "type": "string" }, "created_at": { "type": "string" }, "created_by": { "$ref": "#/definitions/auth.Principal" }, "document_id": { "type": "string" }, "edited_at": { "description": "EditedAt is the time of the last operation of the version, or\nCreatedAt when the log holds none.", "type": "string" }, "id": { "type": "string" }, "number": { "type": "integer" }, "open": { "description": "Open is set while people type in the version. Its content is then the\nlive document, and it has no SHA256 until it is sealed.", "type": "boolean" }, "sha256": { "type": "string" } } }, "server.ambiguousPathResponse": { "type": "object", "properties": { "candidates": { "type": "array", "items": { "$ref": "#/definitions/repo.Folder" } }, "error": { "$ref": "#/definitions/server.errorBody" } } }, "server.approvalListItem": { "type": "object", "properties": { "approver": { "$ref": "#/definitions/server.principalResponse" }, "comments_open": { "description": "CommentsOpen and CommentsTotal count the comment threads this approver\nstarted on the document, so a rejection can say \"2 open of 3\".", "type": "integer" }, "comments_total": { "type": "integer" }, "decided_at": { "type": "string" }, "decision": { "type": "string" }, "earlier": { "description": "Earlier is set while the approver is pending on this content: their most\nrecent decision, made on other content of the document. On the current\nversion it lets the UI say \"Approved before the latest edits\".", "allOf": [ { "$ref": "#/definitions/server.earlierDecision" } ] }, "id": { "type": "string" }, "note": { "type": "string" }, "version_id": { "description": "VersionID and VersionNumber name the version the approver decided on.\nIt can be older than the listed version when the content is the same,\nso the UI can say \"Approved on v3\".", "type": "string" }, "version_number": { "type": "integer" } } }, "server.approvalRequestResponse": { "type": "object", "properties": { "approver": { "$ref": "#/definitions/server.principalResponse" }, "document_id": { "type": "string" }, "id": { "type": "string" }, "requested_by": { "$ref": "#/definitions/server.requestedByJSON" } } }, "server.approvalResponse": { "type": "object", "properties": { "approver": { "$ref": "#/definitions/server.principalResponse" }, "decided_at": { "type": "string" }, "decision": { "type": "string" }, "document_id": { "type": "string" }, "id": { "type": "string" }, "note": { "type": "string" }, "version_id": { "type": "string" }, "version_number": { "type": "integer" }, "version_sha256": { "type": "string" } } }, "server.approvalsListResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/server.approvalListItem" } }, "status": { "type": "string" }, "summary": { "$ref": "#/definitions/repo.ApprovalSummary" }, "version_id": { "type": "string" }, "version_number": { "type": "integer" }, "version_sha256": { "type": "string" } } }, "server.cliExchangePrincipal": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "type": { "type": "string" } } }, "server.cliExchangeResponse": { "type": "object", "properties": { "id": { "type": "string" }, "principal": { "$ref": "#/definitions/server.cliExchangePrincipal" }, "token": { "type": "string" } } }, "server.commentMentionPrincipalRef": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#/definitions/server.commentMentionPrincipalType" } } }, "server.commentMentionPrincipalResponse": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "picture_url": { "type": "string" }, "type": { "$ref": "#/definitions/server.commentMentionPrincipalType" } } }, "server.commentMentionPrincipalType": { "type": "string", "enum": [ "user", "service_account" ], "x-enum-varnames": [ "commentMentionPrincipalUser", "commentMentionPrincipalServiceAccount" ] }, "server.commentMentionRequest": { "type": "object", "properties": { "length": { "description": "Length is the range length in UTF-16 code units.", "type": "integer" }, "offset": { "description": "Offset is the zero-based start in UTF-16 code units.", "type": "integer" }, "principal": { "$ref": "#/definitions/server.commentMentionPrincipalRef" } } }, "server.commentMentionResponse": { "type": "object", "properties": { "length": { "description": "Length is the range length in UTF-16 code units.", "type": "integer" }, "offset": { "description": "Offset is the zero-based start in UTF-16 code units.", "type": "integer" }, "principal": { "$ref": "#/definitions/server.commentMentionPrincipalResponse" } } }, "server.commentPlacementResponse": { "type": "object", "properties": { "anchor": { "$ref": "#/definitions/repo.Anchor" }, "confidence": { "type": "number" }, "matched_text": { "type": "string" }, "status": { "type": "string", "enum": [ "attached", "orphaned", "moved" ] }, "version_id": { "type": "string" } } }, "server.commentReactionResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "emoji": { "type": "string" }, "reacted": { "type": "boolean" }, "reactors": { "type": "array", "items": { "$ref": "#/definitions/server.principalResponse" } } } }, "server.commentResponse": { "type": "object", "properties": { "anchor": { "$ref": "#/definitions/repo.Anchor" }, "author": { "$ref": "#/definitions/server.principalResponse" }, "body": { "type": "string" }, "created_at": { "type": "string" }, "created_on_version_id": { "type": "string" }, "current_placement": { "$ref": "#/definitions/server.commentPlacementResponse" }, "edited": { "type": "boolean" }, "id": { "type": "string" }, "mentions": { "type": "array", "items": { "$ref": "#/definitions/server.commentMentionResponse" } }, "parent_comment_id": { "type": "string" }, "reactions": { "type": "array", "items": { "$ref": "#/definitions/server.commentReactionResponse" } }, "replies": { "type": "array", "items": { "$ref": "#/definitions/server.commentResponse" } }, "resolved_at": { "type": "string" }, "selected_text": { "type": "string" }, "status": { "type": "string" }, "unread": { "description": "Unread is set on a thread with a message by someone else that the\nsigned-in reader did not read. Anonymous readers get no read state.", "type": "boolean" } } }, "server.configResponse": { "type": "object", "properties": { "default_doc_permission": { "type": "string" }, "deployment": { "type": "string" }, "everyone_label": { "type": "string" }, "google_groups_enabled": { "type": "boolean" }, "labels_enabled": { "type": "boolean" }, "org_name": { "type": "string" }, "provider_name": { "type": "string" } } }, "server.createCommentReplyRequest": { "type": "object", "properties": { "body": { "type": "string" }, "mentions": { "type": "array", "items": { "$ref": "#/definitions/server.commentMentionRequest" } } } }, "server.createCommentRequest": { "type": "object", "properties": { "anchor": { "$ref": "#/definitions/repo.Anchor" }, "body": { "type": "string" }, "mentions": { "type": "array", "items": { "$ref": "#/definitions/server.commentMentionRequest" } }, "seq": { "description": "Seq is the seq of the document that a text anchor is on: the page\nshows the document at that seq. The anchor then follows the changes\nafter it. With no seq, the anchor is on the live document.", "type": "integer" }, "version_id": { "type": "string" } } }, "server.createDocumentResponse": { "type": "object", "properties": { "current_version_id": { "type": "string" }, "default_grant": { "$ref": "#/definitions/server.defaultGrant" }, "folder_id": { "type": "string" }, "id": { "type": "string" }, "permission_warning": { "$ref": "#/definitions/server.permissionWarning" } } }, "server.createGrantResponse": { "type": "object", "properties": { "granted_by": { "$ref": "#/definitions/server.grantGrantedBy" }, "id": { "type": "string" }, "principal": { "$ref": "#/definitions/server.grantPrincipal" }, "resource": { "$ref": "#/definitions/server.grantResource" }, "role": { "$ref": "#/definitions/repo.Role" } } }, "server.createServiceAccountResponse": { "type": "object", "properties": { "disabled": { "type": "boolean" }, "grants": { "type": "array", "items": {} }, "id": { "type": "string" }, "key": { "$ref": "#/definitions/server.serviceAccountKey" }, "label": { "type": "string" }, "name": { "type": "string" }, "owner": { "$ref": "#/definitions/server.serviceAccountOwner" } } }, "server.createVersionResponse": { "type": "object", "properties": { "base_version_id": { "description": "BaseVersionID is the version before the new version.", "type": "string" }, "change_summary": { "type": "string" }, "id": { "type": "string" }, "number": { "type": "integer" }, "rebased": { "description": "Rebased is set when the document changed after the base of the upload,\nso the new version also holds the changes of other writers, and is\nnot the uploaded file.", "type": "boolean" }, "seq": { "description": "Seq is the seq of the new version.", "type": "integer" }, "sha256": { "type": "string" }, "unchanged": { "description": "Unchanged is set when the content is the document as it is. No\nversion was made, and the response names the current version.", "type": "boolean" } } }, "server.defaultGrant": { "type": "object", "properties": { "grant_id": { "type": "string" }, "principal": { "$ref": "#/definitions/server.defaultGrantPrincipal" }, "role": { "$ref": "#/definitions/repo.Role" } } }, "server.defaultGrantPrincipal": { "type": "object", "properties": { "type": { "$ref": "#/definitions/auth.PrincipalType" } } }, "server.discoveryAuth": { "type": "object", "properties": { "modes": { "type": "array", "items": { "type": "string" } } } }, "server.discoveryResponse": { "type": "object", "properties": { "api_version": { "type": "string" }, "auth": { "$ref": "#/definitions/server.discoveryAuth" }, "name": { "type": "string" } } }, "server.documentLinkResponse": { "type": "object", "properties": { "url": { "type": "string" } } }, "server.documentListResponse": { "type": "object", "properties": { "has_more": { "description": "HasMore reports that more documents follow this page.", "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/repo.Document" } } } }, "server.earlierDecision": { "type": "object", "properties": { "decided_at": { "type": "string" }, "decision": { "type": "string" } } }, "server.editDocumentRequest": { "type": "object", "properties": { "change_summary": { "type": "string" }, "edits": { "type": "array", "items": { "$ref": "#/definitions/textedit.Edit" } } } }, "server.editDocumentResponse": { "type": "object", "properties": { "base_version_id": { "description": "BaseVersionID is the version before the new version.", "type": "string" }, "change_summary": { "type": "string" }, "edits_applied": { "type": "integer" }, "id": { "type": "string" }, "number": { "type": "integer" }, "sha256": { "type": "string" }, "unchanged": { "description": "Unchanged is set when the edits left the document as it is. No version\nwas made, and the response names the current version.", "type": "boolean" } } }, "server.errorBody": { "type": "object", "properties": { "code": { "type": "string" }, "details": {}, "message": { "type": "string" } } }, "server.errorEnvelope": { "type": "object", "properties": { "error": { "$ref": "#/definitions/server.errorBody" } } }, "server.folderListResponse": { "type": "object", "properties": { "folder": { "$ref": "#/definitions/repo.Folder" }, "has_more": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/definitions/repo.FolderEntry" } } } }, "server.googleGroupSearchItem": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } } }, "server.googleGroupSearchResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/server.googleGroupSearchItem" } } } }, "server.grantGrantedBy": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" } } }, "server.grantInput": { "type": "object", "properties": { "address": { "type": "string" }, "principal": { "$ref": "#/definitions/server.grantPrincipalInput" }, "role": { "enum": [ "viewer", "commenter", "editor" ], "allOf": [ { "$ref": "#/definitions/repo.Role" } ] } } }, "server.grantPrincipal": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "$ref": "#/definitions/auth.PrincipalType" } } }, "server.grantPrincipalInput": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "type": { "enum": [ "user", "service_account", "google_group", "anyone" ], "allOf": [ { "$ref": "#/definitions/auth.PrincipalType" } ] } } }, "server.grantResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" } } }, "server.headingResponse": { "type": "object", "properties": { "id": { "type": "string" }, "level": { "type": "integer" }, "text": { "type": "string" }, "url": { "type": "string" } } }, "server.listResponse-repo_AccessRequest": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/repo.AccessRequest" } } } }, "server.listResponse-repo_CLICredential": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/repo.CLICredential" } } } }, "server.listResponse-repo_DocumentAccessRequest": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/repo.DocumentAccessRequest" } } } }, "server.listResponse-repo_InboxItem": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/repo.InboxItem" } } } }, "server.listResponse-repo_OwnershipTransfer": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/repo.OwnershipTransfer" } } } }, "server.listResponse-repo_ServiceAccount": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/repo.ServiceAccount" } } } }, "server.listResponse-repo_ServiceAccountKey": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/repo.ServiceAccountKey" } } } }, "server.listResponse-repo_Version": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/repo.Version" } } } }, "server.listResponse-server_approvalRequestResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/server.approvalRequestResponse" } } } }, "server.listResponse-server_commentResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/server.commentResponse" } } } }, "server.listResponse-server_headingResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/definitions/server.headingResponse" } } } }, "server.meResponse": { "type": "object", "properties": { "principal": { "$ref": "#/definitions/server.principalRef" }, "service_account": { "$ref": "#/definitions/server.meServiceAccount" }, "user": { "$ref": "#/definitions/server.userResponse" } } }, "server.meServiceAccount": { "type": "object", "properties": { "disabled": { "type": "boolean" }, "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "$ref": "#/definitions/server.meServiceOwner" } } }, "server.meServiceOwner": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" } } }, "server.moveDocResponse": { "type": "object", "properties": { "document_id": { "type": "string" }, "folder_id": { "type": "string" }, "moved": { "type": "boolean" }, "permission_warning": { "$ref": "#/definitions/server.permissionWarning" } } }, "server.notificationPreferencesRequest": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }, "server.operationRequest": { "type": "object", "properties": { "base_seq": { "description": "BaseSeq is the seq of the source that the replacements were made on.", "type": "integer" }, "client_op_id": { "description": "ClientOpID names the operation, so that a retry applies nothing and\ngets the answer of the first attempt.", "type": "string" }, "replacements": { "type": "array", "items": { "$ref": "#/definitions/textedit.Replacement" } }, "summary": { "description": "Summary, when set, is a line of what History shows for the version.\nWhen no operation of a version has one, the server names what a reader\nsees change.", "type": "string" } } }, "server.patchCommentRequest": { "type": "object", "properties": { "anchor": { "description": "Anchor moves a point comment to a new spot.", "allOf": [ { "$ref": "#/definitions/repo.Anchor" } ] }, "base_body": { "description": "BaseBody is the body that an edit started from. When set, and another\nedit changed the body since, the patch fails with 409 comment_changed.", "type": "string" }, "body": { "type": "string" }, "mentions": { "type": "array", "items": { "$ref": "#/definitions/server.commentMentionRequest" } }, "status": { "type": "string" } } }, "server.permissionWarning": { "type": "object", "properties": { "kind": { "type": "string" }, "message": { "type": "string" } } }, "server.principalRef": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#/definitions/auth.PrincipalType" } } }, "server.principalResponse": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "picture_url": { "type": "string" }, "type": { "$ref": "#/definitions/auth.PrincipalType" } } }, "server.renderTokenResponse": { "type": "object", "properties": { "seq": { "description": "Seq is the seq of the source that the URL renders.", "type": "integer" }, "token": { "type": "string" }, "url": { "type": "string" } } }, "server.requestedByJSON": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" } } }, "server.restoreVersionRequest": { "type": "object", "properties": { "change_summary": { "type": "string" } } }, "server.serviceAccountKey": { "type": "object", "properties": { "id": { "type": "string" }, "token": { "type": "string" } } }, "server.serviceAccountOwner": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" } } }, "server.userResponse": { "type": "object", "properties": { "email": { "type": "string" }, "id": { "type": "string" }, "name": { "type": "string" }, "picture_url": { "type": "string" } } }, "textedit.Edit": { "type": "object", "properties": { "new_string": { "type": "string" }, "old_string": { "type": "string" }, "replace_all": { "type": "boolean" } } }, "textedit.Replacement": { "type": "object", "properties": { "end": { "type": "integer" }, "new_html": { "type": "string" }, "old_html": { "type": "string" }, "start": { "type": "integer" } } } }, "securityDefinitions": { "bearerAuth": { "type": "apiKey", "name": "Authorization", "in": "header" }, "cookieAuth": { "type": "apiKey", "name": "slashdocs_session", "in": "cookie" } } }