{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Pooshe Developer API", "version": "1.0.0", "summary": "Files, uploads, share links, CRM and quotes for your own code", "description": "Full guide (Persian): https://pooshe.cloud/developers\n\nAuthenticate with `Authorization: Bearer slk_…` (Settings → Advanced → API keys; paid plans). A key acts as the member who created it, with that member's current role. Errors are RFC 9457 problem details. Rate limit: 120 requests per 60 s per key.", "contact": { "name": "Pooshe support", "url": "https://pooshe.cloud/support" } }, "servers": [ { "url": "https://pooshe.cloud/api/v1", "description": "v1 (stable: only additive changes)" } ], "tags": [ { "name": "Key", "description": "The calling API key" }, { "name": "Files", "description": "Folders, search, move and trash (scope files:*)" }, { "name": "Uploads", "description": "Single-request and resumable multipart uploads (scope files:write)" }, { "name": "Documents", "description": "Files, versions and downloads (scope files:*)" }, { "name": "Links", "description": "Share links and their analytics (scope sharing:*)" }, { "name": "CRM", "description": "Contacts, companies, leads, follow-ups, notes, opportunities (scope crm:*)" }, { "name": "Quotes", "description": "Catalog and quotes (scope quotes:*)" }, { "name": "Analytics", "description": "Team report (scope analytics:read)" } ], "security": [ { "apiKey": [] } ], "paths": { "/key": { "get": { "operationId": "getKey", "tags": [ "Key" ], "summary": "The calling key, its workspace and effective scopes", "description": "Any valid key may call this, whatever its scopes. A good first call to check configuration.", "security": [ { "apiKey": [] } ], "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeyInfo" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive": { "get": { "operationId": "listFolder", "tags": [ "Files" ], "summary": "List one folder level (root when folderId is omitted)", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [ { "name": "folderId", "in": "query", "required": false, "description": "Folder id; omit for the root", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1–500, default 200)", "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DriveListing" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`, `invalid_cursor`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/folders": { "get": { "operationId": "listAllFolders", "tags": [ "Files" ], "summary": "Every live folder, flat (build a tree from parentId)", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderTree" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createFolder", "tags": [ "Files" ], "summary": "Create a folder", "description": "Names are unique per parent (case-insensitive); depth ≤ 20.", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `folder_name_taken`, `folder_too_deep`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parentId": { "description": "Omit or null for the root", "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] } }, "required": [ "name" ] }, "example": { "name": "قراردادها" } } } } } }, "/drive/folders/{id}": { "patch": { "operationId": "updateFolder", "tags": [ "Files" ], "summary": "Rename and/or move a folder", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Folder" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `folder_cycle`, `folder_name_taken`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "parentId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] } } } } } } } }, "/drive/folders/{id}/trash": { "post": { "operationId": "trashFolder", "tags": [ "Files" ], "summary": "Move a folder and everything in it to the trash", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderTrashed" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/folders/{id}/restore": { "post": { "operationId": "restoreFolder", "tags": [ "Files" ], "summary": "Restore a trashed folder", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FolderRestored" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/move": { "post": { "operationId": "moveFiles", "tags": [ "Files" ], "summary": "Move files to a folder (all or nothing)", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MoveResult" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "documentIds": { "minItems": 1, "maxItems": 500, "type": "array", "items": { "type": "string", "maxLength": 40 } }, "folderId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] } }, "required": [ "documentIds", "folderId" ] } } } } } }, "/drive/search": { "get": { "operationId": "search", "tags": [ "Files" ], "summary": "Search folders and files by name", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search text (≥ 1 character)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/trash": { "get": { "operationId": "listTrash", "tags": [ "Files" ], "summary": "Trashed folders and files, with the retention period", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Trash" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/drive/trash/{documentId}": { "delete": { "operationId": "deleteFromTrash", "tags": [ "Files" ], "summary": "Delete a trashed file for good (cannot be undone)", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "documentId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/uploads": { "post": { "operationId": "createUpload", "tags": [ "Uploads" ], "summary": "Start a single-request upload (files up to the plan limit)", "description": "Step 1 of 3: reserves quota and returns a version id. Then PUT the bytes and POST finalize. For files over ~50 MB or unreliable networks use upload sessions.", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadTicket" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `unsupported_type`, `file_too_large`, `invalid_size`, `quota_exceeded`, `version_type_mismatch`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255, "examples": [ "proposal.pdf" ] }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Exact size in bytes; the body must match it" }, "mime": { "type": "string", "maxLength": 120 }, "documentId": { "description": "Upload a new version of this file instead of a new file", "type": "string", "maxLength": 40 }, "title": { "type": "string", "maxLength": 200 }, "folderId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] } }, "required": [ "fileName", "size" ] }, "example": { "fileName": "proposal.pdf", "size": 482113, "folderId": null } } } } } }, "/uploads/{versionId}/content": { "put": { "operationId": "putUploadContent", "tags": [ "Uploads" ], "summary": "Send the file bytes (application/octet-stream)", "description": "Content-Length is required and must equal the declared size. Streamed to storage, never buffered.", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadReceived" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `length_required`, `empty_body`, `file_too_large`, `use_upload_session`, `upload_already_received`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/uploads/{versionId}/finalize": { "post": { "operationId": "finalizeUpload", "tags": [ "Uploads" ], "summary": "Commit the upload; scanning and processing start", "description": "Idempotent. The version becomes ready after the virus scan (seconds); poll GET /versions/{id} or subscribe to the document.ready webhook.", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "versionId", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadStatus" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `upload_incomplete`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/upload-sessions": { "post": { "operationId": "createUploadSession", "tags": [ "Uploads" ], "summary": "Start a resumable multipart upload", "description": "Returns the part size and count. PUT each part (any order, retry freely), then POST complete. Sessions last 24 h.", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `unsupported_type`, `file_too_large`, `quota_exceeded`, `storage_unavailable`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fileName": { "type": "string", "minLength": 1, "maxLength": 255 }, "size": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "mime": { "type": "string", "maxLength": 120 }, "title": { "type": "string", "maxLength": 200 }, "documentId": { "type": "string", "maxLength": 40 }, "folderId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] } }, "required": [ "fileName", "size" ] } } } } } }, "/upload-sessions/{id}": { "get": { "operationId": "getUploadSession", "tags": [ "Uploads" ], "summary": "Session state, including the parts already received (to resume)", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadSession" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "abortUploadSession", "tags": [ "Uploads" ], "summary": "Abort a session and release its quota", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/upload-sessions/{id}/parts/{n}": { "put": { "operationId": "putUploadPart", "tags": [ "Uploads" ], "summary": "Upload part n (1-based); Content-Length must equal the planned part size", "description": "Sending the same part again replaces it, so retries are safe without an Idempotency-Key.", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "n", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PartReceived" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `length_required`, `invalid_part_number`, `invalid_part_size`, `upload_session_closed`, `upload_session_expired`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } } } }, "/upload-sessions/{id}/complete": { "post": { "operationId": "completeUploadSession", "tags": [ "Uploads" ], "summary": "Assemble the parts and finalize", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadCompleted" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `upload_incomplete`, `upload_session_closed`, `upload_assembly_failed`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/documents": { "get": { "operationId": "listDocuments", "tags": [ "Documents" ], "summary": "Files the key’s member can see, newest first", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Filter by title", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1–50, default 20)", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/documents/{id}": { "get": { "operationId": "getDocument", "tags": [ "Documents" ], "summary": "One file with all its versions (size, SHA-256, state)", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Document" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateDocument", "tags": [ "Documents" ], "summary": "Rename a file, or set its key pages", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPatched" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "keyPages": { "maxItems": 20, "type": "array", "items": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 } } } } } } } } }, "/documents/{id}/trash": { "post": { "operationId": "trashDocument", "tags": [ "Documents" ], "summary": "Move a file to the trash (its links stop working)", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/documents/{id}/restore": { "post": { "operationId": "restoreDocument", "tags": [ "Documents" ], "summary": "Restore a file from the trash", "security": [ { "apiKey": [ "files:write" ] } ], "x-scope": "files:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/versions/{id}": { "get": { "operationId": "getVersion", "tags": [ "Documents" ], "summary": "A version’s processing state (poll after finalize)", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/versions/{id}/original": { "get": { "operationId": "downloadVersion", "tags": [ "Documents" ], "summary": "Download the original bytes", "description": "Audited. Content-Disposition carries the original file name.", "security": [ { "apiKey": [ "files:read" ] } ], "x-scope": "files:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The file", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links": { "get": { "operationId": "listLinks", "tags": [ "Links" ], "summary": "Share links, newest first", "security": [ { "apiKey": [ "sharing:read" ] } ], "x-scope": "sharing:read", "parameters": [ { "name": "documentId", "in": "query", "required": false, "description": "Only links of this file", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createLink", "tags": [ "Links" ], "summary": "Create a share link for a file", "description": "The URL is in the response only once. Workspace policies (external sharing off, allowed domains, forced watermark) apply.", "security": [ { "apiKey": [ "sharing:write" ] } ], "x-scope": "sharing:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkCreated" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `policy_sharing_off`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "identityMode": { "default": "anonymous", "type": "string", "enum": [ "anonymous", "declared", "verified" ] }, "password": { "anyOf": [ { "type": "string", "minLength": 4, "maxLength": 128 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAtJalali": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "expiresInDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ] }, "maxSessions": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "allowDownload": { "default": false, "type": "boolean" }, "viewerMode": { "default": "standard", "type": "string", "enum": [ "standard", "restricted" ] }, "watermark": { "default": false, "type": "boolean" }, "watermarkFields": { "type": "object", "properties": { "identity": { "default": true, "type": "boolean" }, "time": { "default": true, "type": "boolean" }, "session": { "default": true, "type": "boolean" }, "maskContact": { "default": true, "type": "boolean" } } }, "allowlist": { "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 254 } }, "allowlistOnly": { "default": false, "type": "boolean" }, "allowedEmailDomains": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 253 } }, "notifyOnView": { "default": true, "type": "boolean" }, "contactId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "ctaActions": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "call", "meeting", "question", "accept" ] } }, "ctaNote": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "followLatest": { "type": "boolean" }, "documentId": { "type": "string", "maxLength": 40 }, "versionId": { "type": "string", "maxLength": 40 }, "roomId": { "type": "string", "maxLength": 40 }, "restrictToContact": { "default": false, "type": "boolean" } }, "required": [ "name" ] }, "example": { "documentId": "uysse8ma956dknqtijp3f1iy", "name": "برای شرکت نمونه", "expiresInDays": 7, "allowDownload": false } } } } } }, "/links/{id}": { "get": { "operationId": "getLink", "tags": [ "Links" ], "summary": "One link with its settings and state", "security": [ { "apiKey": [ "sharing:read" ] } ], "x-scope": "sharing:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Link" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateLink", "tags": [ "Links" ], "summary": "Change a link’s settings", "security": [ { "apiKey": [ "sharing:write" ] } ], "x-scope": "sharing:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`, `link_revoked`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "identityMode": { "type": "string", "enum": [ "anonymous", "declared", "verified" ] }, "password": { "anyOf": [ { "type": "string", "minLength": 4, "maxLength": 128 }, { "type": "null" } ] }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "expiresAtJalali": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "expiresInDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 3650 }, { "type": "null" } ] }, "maxSessions": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 1000000 }, { "type": "null" } ] }, "allowDownload": { "type": "boolean" }, "viewerMode": { "type": "string", "enum": [ "standard", "restricted" ] }, "watermark": { "type": "boolean" }, "watermarkFields": { "type": "object", "properties": { "identity": { "default": true, "type": "boolean" }, "time": { "default": true, "type": "boolean" }, "session": { "default": true, "type": "boolean" }, "maskContact": { "default": true, "type": "boolean" } } }, "allowlist": { "maxItems": 200, "type": "array", "items": { "type": "string", "maxLength": 254 } }, "allowlistOnly": { "type": "boolean" }, "allowedEmailDomains": { "maxItems": 50, "type": "array", "items": { "type": "string", "maxLength": 253 } }, "notifyOnView": { "type": "boolean" }, "contactId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "ctaActions": { "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "call", "meeting", "question", "accept" ] } }, "ctaNote": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "followLatest": { "type": "boolean" } } } } } } } }, "/links/{id}/revoke": { "post": { "operationId": "revokeLink", "tags": [ "Links" ], "summary": "Revoke a link at once (open sessions end too)", "security": [ { "apiKey": [ "sharing:write" ] } ], "x-scope": "sharing:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/links/{id}/analytics": { "get": { "operationId": "getLinkAnalytics", "tags": [ "Links" ], "summary": "Views, verified viewers, downloads and estimated attention per page", "security": [ { "apiKey": [ "sharing:read" ] } ], "x-scope": "sharing:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkAnalytics" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/contacts": { "get": { "operationId": "listContacts", "tags": [ "CRM" ], "summary": "Contacts with engagement", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Name, e-mail or phone", "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "description": "Only this company", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size (1–100, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "`nextCursor` from the previous page", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createContact", "tags": [ "CRM" ], "summary": "Create a contact (companyName finds or creates the company)", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "note": { "type": "string", "maxLength": 2000 }, "companyId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "ownerId": { "type": "string", "maxLength": 40 } }, "required": [ "name" ] }, "example": { "name": "رضا احمدی", "email": "reza@example.com", "companyName": "شرکت نمونه" } } } } } }, "/contacts/{id}": { "get": { "operationId": "getContact", "tags": [ "CRM" ], "summary": "A contact with links, timeline and responses", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContactDetail" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateContact", "tags": [ "CRM" ], "summary": "Update a contact", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Contact" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "email": { "anyOf": [ { "type": "string", "maxLength": 254 }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string", "maxLength": 30 }, { "type": "null" } ] }, "jobTitle": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "note": { "type": "string", "maxLength": 2000 }, "companyId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "companyName": { "anyOf": [ { "type": "string", "maxLength": 120 }, { "type": "null" } ] }, "ownerId": { "type": "string", "maxLength": 40 } } } } } } }, "delete": { "operationId": "deleteContact", "tags": [ "CRM" ], "summary": "Delete a contact", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/companies": { "get": { "operationId": "listCompanies", "tags": [ "CRM" ], "summary": "Companies", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Name or domain", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createCompany", "tags": [ "CRM" ], "summary": "Create a company", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "domain": { "anyOf": [ { "type": "string", "maxLength": 253 }, { "type": "null" } ] }, "note": { "type": "string", "maxLength": 2000 } }, "required": [ "name" ] } } } } } }, "/companies/{id}": { "get": { "operationId": "getCompany", "tags": [ "CRM" ], "summary": "A company with its contacts", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDetail" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateCompany", "tags": [ "CRM" ], "summary": "Update a company", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Company" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 120 }, "domain": { "anyOf": [ { "type": "string", "maxLength": 253 }, { "type": "null" } ] }, "note": { "type": "string", "maxLength": 2000 } } } } } } }, "delete": { "operationId": "deleteCompany", "tags": [ "CRM" ], "summary": "Delete a company (its contacts stay)", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/leads": { "get": { "operationId": "listLeads", "tags": [ "CRM" ], "summary": "Hot leads: contacts ranked by recent engagement", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "scope", "in": "query", "required": false, "description": "`team` for every member’s contacts (needs the permission)", "schema": { "type": "string", "enum": [ "team" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/followups": { "get": { "operationId": "listFollowUps", "tags": [ "CRM" ], "summary": "Follow-up reminders", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "contactId", "in": "query", "required": false, "description": "Only this contact", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUpList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createFollowUp", "tags": [ "CRM" ], "summary": "Create a follow-up reminder", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUp" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contactId": { "type": "string", "maxLength": 40 }, "dueInDays": { "type": "integer", "minimum": 0, "maximum": 365 }, "dueAt": { "type": "string", "format": "date-time" }, "note": { "type": "string", "maxLength": 1000 } }, "required": [ "contactId" ] } } } } } }, "/followups/{id}": { "patch": { "operationId": "updateFollowUp", "tags": [ "CRM" ], "summary": "Mark a follow-up done or dismissed", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "done", "dismissed" ] } }, "required": [ "status" ] } } } } } }, "/notes": { "get": { "operationId": "listNotes", "tags": [ "CRM" ], "summary": "Notes of a contact, company or opportunity", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "contactId", "in": "query", "required": false, "description": "Contact", "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "description": "Company", "schema": { "type": "string" } }, { "name": "opportunityId", "in": "query", "required": false, "description": "Opportunity", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NoteList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createNote", "tags": [ "CRM" ], "summary": "Add a note", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Note" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "minLength": 1, "maxLength": 4000 }, "contactId": { "type": "string", "maxLength": 40 }, "companyId": { "type": "string", "maxLength": 40 }, "opportunityId": { "type": "string", "maxLength": 40 } }, "required": [ "body" ] } } } } } }, "/opportunities": { "get": { "operationId": "listOpportunities", "tags": [ "CRM" ], "summary": "Opportunities with totals per stage", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "contactId", "in": "query", "required": false, "description": "Contact", "schema": { "type": "string" } }, { "name": "companyId", "in": "query", "required": false, "description": "Company", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createOpportunity", "tags": [ "CRM" ], "summary": "Create an opportunity", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Opportunity" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "contactId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "companyId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "stage": { "type": "string", "enum": [ "lead", "qualified", "proposal", "negotiation", "won", "lost" ] }, "valueRial": { "type": [ "string", "number", "null" ] }, "expectedCloseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lostReason": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "ownerId": { "type": "string", "maxLength": 40 } }, "required": [ "title" ] }, "example": { "title": "قرارداد سالانه", "valueRial": "1000000000", "stage": "proposal" } } } } } }, "/opportunities/{id}": { "get": { "operationId": "getOpportunity", "tags": [ "CRM" ], "summary": "One opportunity", "security": [ { "apiKey": [ "crm:read" ] } ], "x-scope": "crm:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpportunityDetail" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateOpportunity", "tags": [ "CRM" ], "summary": "Update an opportunity (stage, value, close date…)", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Opportunity" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "contactId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "companyId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "stage": { "type": "string", "enum": [ "lead", "qualified", "proposal", "negotiation", "won", "lost" ] }, "valueRial": { "type": [ "string", "number", "null" ] }, "expectedCloseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lostReason": { "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "ownerId": { "type": "string", "maxLength": 40 } } } } } } } }, "/responses/{id}": { "patch": { "operationId": "markResponseHandled", "tags": [ "CRM" ], "summary": "Mark a viewer’s response (call request, meeting, acceptance) as handled", "security": [ { "apiKey": [ "crm:write" ] } ], "x-scope": "crm:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/catalog": { "get": { "operationId": "listCatalog", "tags": [ "Quotes" ], "summary": "Products and services", "security": [ { "apiKey": [ "quotes:read" ] } ], "x-scope": "quotes:read", "parameters": [ { "name": "q", "in": "query", "required": false, "description": "Search", "schema": { "type": "string" } }, { "name": "all", "in": "query", "required": false, "description": "`1` to include inactive items", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createCatalogItem", "tags": [ "Quotes" ], "summary": "Add a product or service", "security": [ { "apiKey": [ "quotes:write" ] } ], "x-scope": "quotes:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItem" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "unit": { "type": "string", "minLength": 1, "maxLength": 20 }, "unitPriceRial": { "type": [ "string", "number" ] }, "taxable": { "type": "boolean" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "active": { "type": "boolean" } }, "required": [ "name", "unitPriceRial" ] }, "example": { "name": "مشاوره", "unitPriceRial": "5000000" } } } } } }, "/catalog/{id}": { "patch": { "operationId": "updateCatalogItem", "tags": [ "Quotes" ], "summary": "Update a product or service", "security": [ { "apiKey": [ "quotes:write" ] } ], "x-scope": "quotes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItem" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 160 }, "sku": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "unit": { "type": "string", "minLength": 1, "maxLength": 20 }, "unitPriceRial": { "type": [ "string", "number" ] }, "taxable": { "type": "boolean" }, "description": { "anyOf": [ { "type": "string", "maxLength": 1000 }, { "type": "null" } ] }, "active": { "type": "boolean" } } } } } } } }, "/quotes": { "get": { "operationId": "listQuotes", "tags": [ "Quotes" ], "summary": "Quotes", "security": [ { "apiKey": [ "quotes:read" ] } ], "x-scope": "quotes:read", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "draft, issued, sent, accepted…", "schema": { "type": "string" } }, { "name": "contactId", "in": "query", "required": false, "description": "Contact", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteList" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createQuote", "tags": [ "Quotes" ], "summary": "Create a draft quote", "description": "Amounts are integer Rial strings; tax and totals are computed by the server.", "security": [ { "apiKey": [ "quotes:write" ] } ], "x-scope": "quotes:write", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "contactId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "companyId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "opportunityId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "draft": { "type": "object", "properties": { "lines": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "catalogItemId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "string", "minLength": 1, "maxLength": 20 }, "unit": { "default": "عدد", "type": "string", "maxLength": 20 }, "unitPriceRial": { "type": [ "string", "number" ] }, "discount": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "percent" }, "bps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "amount" }, "rial": { "type": [ "string", "number" ] } }, "required": [ "kind", "rial" ] } ] }, { "type": "null" } ] }, "taxable": { "default": true, "type": "boolean" } }, "required": [ "description", "quantity", "unitPriceRial" ] } }, "docDiscount": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "percent" }, "bps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "amount" }, "rial": { "type": [ "string", "number" ] } }, "required": [ "kind", "rial" ] } ] }, { "type": "null" } ] }, "taxRules": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[a-z0-9_]{1,20}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 60 }, "rateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "code", "label", "rateBps" ] } }, { "type": "null" } ] }, "validityDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "terms": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "buyer": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 160 }, "nationalId": { "type": "string", "maxLength": 20 }, "economicCode": { "type": "string", "maxLength": 20 }, "address": { "type": "string", "maxLength": 400 }, "postalCode": { "type": "string", "maxLength": 20 }, "phone": { "type": "string", "maxLength": 30 } } }, { "type": "null" } ] } } } }, "required": [ "title" ] } } } } } }, "/quotes/{id}": { "get": { "operationId": "getQuote", "tags": [ "Quotes" ], "summary": "A quote with its versions and computed totals", "security": [ { "apiKey": [ "quotes:read" ] } ], "x-scope": "quotes:read", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteDetail" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateQuote", "tags": [ "Quotes" ], "summary": "Edit a draft", "security": [ { "apiKey": [ "quotes:write" ] } ], "x-scope": "quotes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Quote" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`, `quote_final`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 160 }, "contactId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "companyId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "draft": { "type": "object", "properties": { "lines": { "maxItems": 200, "type": "array", "items": { "type": "object", "properties": { "catalogItemId": { "anyOf": [ { "type": "string", "maxLength": 40 }, { "type": "null" } ] }, "description": { "type": "string", "minLength": 1, "maxLength": 500 }, "quantity": { "type": "string", "minLength": 1, "maxLength": 20 }, "unit": { "default": "عدد", "type": "string", "maxLength": 20 }, "unitPriceRial": { "type": [ "string", "number" ] }, "discount": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "percent" }, "bps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "amount" }, "rial": { "type": [ "string", "number" ] } }, "required": [ "kind", "rial" ] } ] }, { "type": "null" } ] }, "taxable": { "default": true, "type": "boolean" } }, "required": [ "description", "quantity", "unitPriceRial" ] } }, "docDiscount": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "const": "percent" }, "bps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "kind", "bps" ] }, { "type": "object", "properties": { "kind": { "type": "string", "const": "amount" }, "rial": { "type": [ "string", "number" ] } }, "required": [ "kind", "rial" ] } ] }, { "type": "null" } ] }, "taxRules": { "anyOf": [ { "maxItems": 5, "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "pattern": "^[a-z0-9_]{1,20}$" }, "label": { "type": "string", "minLength": 1, "maxLength": 60 }, "rateBps": { "type": "integer", "minimum": 0, "maximum": 10000 } }, "required": [ "code", "label", "rateBps" ] } }, { "type": "null" } ] }, "validityDays": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 365 }, { "type": "null" } ] }, "terms": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ] }, "notes": { "anyOf": [ { "type": "string", "maxLength": 2000 }, { "type": "null" } ] }, "buyer": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "maxLength": 160 }, "nationalId": { "type": "string", "maxLength": 20 }, "economicCode": { "type": "string", "maxLength": 20 }, "address": { "type": "string", "maxLength": 400 }, "postalCode": { "type": "string", "maxLength": 20 }, "phone": { "type": "string", "maxLength": 30 } } }, { "type": "null" } ] } } } } } } } } } }, "/quotes/{id}/issue": { "post": { "operationId": "issueQuote", "tags": [ "Quotes" ], "summary": "Issue a version: freezes the numbers and renders the PDF into Files", "security": [ { "apiKey": [ "quotes:write" ] } ], "x-scope": "quotes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteIssued" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `not_found`, `quote_final`, `company_profile_required`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/quotes/{id}/send": { "post": { "operationId": "sendQuote", "tags": [ "Quotes" ], "summary": "Create the smart link for the issued quote (URL returned once)", "description": "The PDF renders in the background after issue; until it is ready this returns 409 quote_pdf_not_ready: retry after a few seconds.", "security": [ { "apiKey": [ "quotes:write" ] } ], "x-scope": "quotes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "201": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteSent" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`, `quote_not_issued`, `quote_pdf_not_ready`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365 }, "restrictToContact": { "type": "boolean" } } } } } } } }, "/quotes/{id}/status": { "post": { "operationId": "setQuoteStatus", "tags": [ "Quotes" ], "summary": "Mark a quote rejected or cancelled", "security": [ { "apiKey": [ "quotes:write" ] } ], "x-scope": "quotes:write", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Ok" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`, `validation_failed`, `not_found`, `quote_final`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "rejected", "cancelled" ] } }, "required": [ "status" ] } } } } } }, "/analytics/team": { "get": { "operationId": "getTeamReport", "tags": [ "Analytics" ], "summary": "Links sent and opened, views and responses, per file and per member", "security": [ { "apiKey": [ "analytics:read" ] } ], "x-scope": "analytics:read", "parameters": [ { "name": "days", "in": "query", "required": false, "description": "7, 30 or 90", "schema": { "type": "integer", "enum": [ 7, 30, 90 ], "default": 30 } } ], "responses": { "200": { "description": "OK", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TeamReport" } } } }, "default": { "description": "Error. Codes: `api_key_invalid`, `api_key_scope`, `rate_limited`", "headers": { "X-RateLimit-Limit": { "description": "Requests allowed per window", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Seconds until the window resets", "schema": { "type": "integer" } }, "X-Request-Id": { "description": "Request id (yours if you sent a valid X-Request-Id)", "schema": { "type": "string" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "webhooks": { "view.opened": { "post": { "summary": "Event view.opened", "parameters": [ { "name": "X-Pooshe-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "view.opened" } }, { "name": "X-Pooshe-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (same as body.id)" }, { "name": "X-Pooshe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=.\")>`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Anything else (or a timeout over 10 s) is retried with backoff." } } } }, "cta.response": { "post": { "summary": "Event cta.response", "parameters": [ { "name": "X-Pooshe-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "cta.response" } }, { "name": "X-Pooshe-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (same as body.id)" }, { "name": "X-Pooshe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=.\")>`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Anything else (or a timeout over 10 s) is retried with backoff." } } } }, "lead.hot": { "post": { "summary": "Event lead.hot", "parameters": [ { "name": "X-Pooshe-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "lead.hot" } }, { "name": "X-Pooshe-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (same as body.id)" }, { "name": "X-Pooshe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=.\")>`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Anything else (or a timeout over 10 s) is retried with backoff." } } } }, "document.ready": { "post": { "summary": "Event document.ready", "parameters": [ { "name": "X-Pooshe-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "document.ready" } }, { "name": "X-Pooshe-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (same as body.id)" }, { "name": "X-Pooshe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=.\")>`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Anything else (or a timeout over 10 s) is retried with backoff." } } } }, "link.created": { "post": { "summary": "Event link.created", "parameters": [ { "name": "X-Pooshe-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "link.created" } }, { "name": "X-Pooshe-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (same as body.id)" }, { "name": "X-Pooshe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=.\")>`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Anything else (or a timeout over 10 s) is retried with backoff." } } } }, "contact.created": { "post": { "summary": "Event contact.created", "parameters": [ { "name": "X-Pooshe-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "contact.created" } }, { "name": "X-Pooshe-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (same as body.id)" }, { "name": "X-Pooshe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=.\")>`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Anything else (or a timeout over 10 s) is retried with backoff." } } } }, "ping": { "post": { "summary": "Sent by “send test” in the panel", "parameters": [ { "name": "X-Pooshe-Event", "in": "header", "required": true, "schema": { "type": "string", "const": "ping" } }, { "name": "X-Pooshe-Delivery", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Delivery id (same as body.id)" }, { "name": "X-Pooshe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "`t=,v1=.\")>`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Received. Anything else (or a timeout over 10 s) is retried with backoff." } } } } }, "components": { "schemas": { "Problem": { "type": "object", "properties": { "type": { "type": "string", "format": "uri", "examples": [ "https://pooshe.cloud/developers/errors#not_found" ] }, "title": { "type": "string", "description": "Human-readable, in the language of Accept-Language (fa default, en)" }, "status": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "code": { "type": "string", "description": "Stable machine-readable error code; branch on this", "examples": [ "not_found" ] }, "requestId": { "description": "Same as the X-Request-Id header; quote it to support", "type": "string" }, "error": { "type": "string", "description": "Same as `code` (kept for clients of the panel API)" }, "details": { "anyOf": [ {}, { "type": "null" } ], "description": "Extra data for some codes, e.g. `{fields: [...]}` for validation_failed" } }, "required": [ "type", "title", "status", "code", "error", "details" ], "additionalProperties": {} }, "Ok": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true } }, "required": [ "ok" ], "additionalProperties": {} }, "KeyInfo": { "type": "object", "properties": { "key": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" }, "prefix": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } }, "effectiveScopes": { "type": "array", "items": { "type": "string" } }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "allowedIps": { "type": "array", "items": { "type": "string" } }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "prefix", "scopes", "effectiveScopes", "expiresAt", "allowedIps", "createdAt" ], "additionalProperties": {} }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} }, "actingAs": { "type": "object", "properties": { "userId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "role": { "type": "string" } }, "required": [ "userId", "role" ], "additionalProperties": {} }, "rateLimit": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "windowSec": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "limit", "windowSec" ], "additionalProperties": {} } }, "required": [ "key", "workspace", "actingAs", "rateLimit" ], "additionalProperties": {} }, "DriveFile": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "title": { "type": "string" }, "fileName": { "type": [ "string", "null" ] }, "sizeBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "kind": { "description": "`stored` for files kept as-is; pdf/image/office kinds for trackable documents", "type": [ "string", "null" ] }, "pageCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "state": { "type": "string", "description": "ready when a version can be opened/downloaded" }, "processing": { "type": "boolean" }, "trackable": { "type": "boolean" }, "folderId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "currentVersionId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "createdById": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "fileName", "sizeBytes", "kind", "pageCount", "state", "processing", "trackable", "folderId", "currentVersionId", "createdById", "updatedAt" ], "additionalProperties": {} }, "FolderSummary": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" }, "createdById": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name" ], "additionalProperties": {} }, "Folder": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" }, "parentId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "createdById": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "trashedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "parentId", "createdById", "trashedAt", "createdAt", "updatedAt" ], "additionalProperties": {} }, "DriveListing": { "type": "object", "properties": { "folder": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] } }, "required": [ "id" ], "additionalProperties": {} }, { "type": "null" } ] }, "breadcrumb": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} }, "description": "Root first; empty at the root and on pages after the first" }, "folders": { "type": "array", "items": { "$ref": "#/components/schemas/FolderSummary" }, "description": "Subfolders (first page only)" }, "documents": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/DriveFile" }, { "type": "object", "properties": { "favorite": { "type": "boolean" } }, "required": [ "favorite" ], "additionalProperties": {} } ] } }, "nextCursor": { "description": "Pass as `cursor` to get the next page; null on the last page", "type": [ "string", "null" ] }, "totalFiles": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "folder", "breadcrumb", "folders", "documents", "nextCursor", "totalFiles" ], "additionalProperties": {} }, "FolderTree": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" }, "parentId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] } }, "required": [ "id", "name", "parentId" ], "additionalProperties": {} } } }, "required": [ "folders" ], "additionalProperties": {} }, "SearchResult": { "type": "object", "properties": { "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/DriveFile" } } }, "required": [ "folders", "documents" ], "additionalProperties": {} }, "Trash": { "type": "object", "properties": { "retentionDays": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "folders": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "title": { "type": "string" } }, "required": [ "id", "title" ], "additionalProperties": {} } } }, "required": [ "retentionDays", "folders", "documents" ], "additionalProperties": {} }, "MoveResult": { "type": "object", "properties": { "moved": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "moved" ], "additionalProperties": {} }, "FolderTrashed": { "type": "object", "properties": { "folders": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Folders moved to the trash (with subfolders)" }, "files": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "folders", "files" ], "additionalProperties": {} }, "FolderRestored": { "type": "object", "properties": { "files": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "name": { "type": "string", "description": "Final name (a suffix is added if the old one is taken)" }, "parentId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] } }, "required": [ "files", "name", "parentId" ], "additionalProperties": {} }, "UploadTicket": { "type": "object", "properties": { "documentId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "versionId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "maxBytes": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "documentId", "versionId", "maxBytes" ], "additionalProperties": {} }, "UploadReceived": { "type": "object", "properties": { "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "size" ], "additionalProperties": {} }, "UploadStatus": { "type": "object", "properties": { "status": { "type": "string", "description": "quarantined right after finalize: the virus scan and processing run in the background; poll GET /versions/{id}" } }, "required": [ "status" ], "additionalProperties": {} }, "UploadSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "versionId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "documentId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "status": { "anyOf": [ { "type": "string", "enum": [ "open", "completing", "completed", "aborted", "expired" ] }, { "type": "string" } ] }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "partSize": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991, "description": "Every part but the last is exactly this many bytes" }, "totalParts": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "receivedParts": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "description": "Part numbers already stored; resume by sending the others" }, "expiresAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "versionId", "status", "size", "partSize", "totalParts", "receivedParts", "expiresAt" ], "additionalProperties": {} }, "PartReceived": { "type": "object", "properties": { "partNumber": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "size": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "partNumber", "size" ], "additionalProperties": {} }, "UploadCompleted": { "type": "object", "properties": { "status": { "type": "string", "const": "completed" }, "versionId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] } }, "required": [ "status", "versionId" ], "additionalProperties": {} }, "Version": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "documentId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "anyOf": [ { "type": "string", "enum": [ "uploading", "quarantined", "scanning", "processing", "ready", "failed", "rejected" ] }, { "type": "string" } ] }, "errorCode": { "type": [ "string", "null" ] }, "pageCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "id", "documentId", "number", "status", "errorCode", "pageCount" ], "additionalProperties": {} }, "Document": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "title": { "type": "string" }, "status": { "type": "string" }, "trackable": { "type": "boolean" }, "folderId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "currentVersionId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "createdById": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "trashedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string" }, "sourceKind": { "type": [ "string", "null" ] }, "originalName": { "type": [ "string", "null" ] }, "sizeBytes": { "type": "string", "description": "Bytes, as a decimal string" }, "pageCount": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "errorCode": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "readyAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "sha256": { "type": [ "string", "null" ] } }, "required": [ "id", "number", "status", "sourceKind", "originalName", "sizeBytes", "pageCount", "errorCode", "createdAt", "readyAt", "sha256" ], "additionalProperties": {} } } }, "required": [ "id", "title", "status", "trackable", "folderId", "currentVersionId", "createdById", "createdAt", "updatedAt", "trashedAt", "versions" ], "additionalProperties": {} }, "DocumentList": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "title": { "type": "string" }, "currentVersionId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "updatedAt": { "type": "string", "format": "date-time" }, "versions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "number": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "status": { "type": "string" } }, "required": [ "id", "number", "status" ], "additionalProperties": {} } } }, "required": [ "id", "title", "currentVersionId", "updatedAt", "versions" ], "additionalProperties": {} } }, "nextCursor": { "description": "Pass as `cursor` to get the next page; null on the last page", "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": {} }, "DocumentPatched": { "type": "object", "properties": { "ok": { "type": "boolean", "const": true }, "keyPages": { "type": "array", "items": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } } }, "required": [ "ok" ], "additionalProperties": {} }, "Link": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": [ "string", "null" ] }, "documentId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "versionId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "roomId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "state": { "type": "string", "enum": [ "active", "revoked", "expired", "exhausted" ] }, "identityMode": { "type": "string" }, "expiresAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "maxSessions": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "sessionsUsed": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "allowDownload": { "type": "boolean" }, "watermark": { "type": "boolean" }, "hasPassword": { "type": "boolean" }, "followLatest": { "type": "boolean" }, "contactId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "createdById": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "documentId", "versionId", "roomId", "state", "identityMode", "expiresAt", "revokedAt", "maxSessions", "sessionsUsed", "allowDownload", "watermark", "hasPassword", "followLatest", "contactId", "createdById", "createdAt" ], "additionalProperties": {} }, "LinkList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Link" } }, "nextCursor": { "description": "Pass as `cursor` to get the next page; null on the last page", "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": {} }, "LinkCreated": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "url": { "type": "string", "format": "uri", "description": "Shown once; Pooshe stores only a hash of the token" } }, "required": [ "id", "url" ], "additionalProperties": {} }, "LinkAnalytics": { "type": "object", "properties": { "report": { "type": "object", "properties": { "estimated": { "type": "boolean", "const": true, "description": "Attention figures are estimates, never exact reading time" }, "sessions": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "verifiedIdentities": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "downloads": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "avgSessionMs": { "type": "number" }, "lastViewAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "pages": { "type": "array", "items": {} } }, "required": [ "estimated", "sessions", "verifiedIdentities", "downloads", "avgSessionMs", "lastViewAt", "pages" ], "additionalProperties": {} }, "daily": { "type": "array", "items": {} } }, "required": [ "report", "daily" ], "additionalProperties": {} }, "Contact": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "jobTitle": { "type": [ "string", "null" ] }, "note": { "type": "string" }, "companyId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "ownerId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "email", "phone", "jobTitle", "note", "companyId", "ownerId", "createdAt", "updatedAt" ], "additionalProperties": {} }, "ContactList": { "type": "object", "properties": { "items": { "type": "array", "items": { "allOf": [ { "$ref": "#/components/schemas/Contact" }, { "type": "object", "properties": { "company": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" } }, "required": [ "id", "name" ], "additionalProperties": {} }, { "type": "null" } ] }, "engagement": { "type": "object", "properties": { "views": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "lastViewAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "totalMs": { "type": "number" } }, "required": [ "views", "lastViewAt", "totalMs" ], "additionalProperties": {} } }, "required": [ "company", "engagement" ], "additionalProperties": {} } ] } }, "nextCursor": { "description": "Pass as `cursor` to get the next page; null on the last page", "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": {} }, "ContactDetail": { "type": "object", "properties": { "contact": { "$ref": "#/components/schemas/Contact" }, "owner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": [ "string", "null" ] } }, "required": [ "id", "name" ], "additionalProperties": {} }, { "type": "null" } ] }, "links": { "type": "array", "items": {} }, "timeline": { "type": "array", "items": {} }, "responses": { "type": "array", "items": {} }, "canEdit": { "type": "boolean" } }, "required": [ "contact", "owner", "links", "timeline", "responses", "canEdit" ], "additionalProperties": {} }, "Company": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" }, "domain": { "type": [ "string", "null" ] }, "note": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "domain", "note", "createdAt", "updatedAt" ], "additionalProperties": {} }, "CompanyList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Company" } } }, "required": [ "items" ], "additionalProperties": {} }, "FollowUp": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "contactId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "ownerId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "kind": { "type": "string" }, "status": { "type": "string", "enum": [ "open", "done", "dismissed" ] }, "dueAt": { "type": "string", "format": "date-time" }, "note": { "type": "string" }, "doneAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "contactId", "ownerId", "kind", "status", "dueAt", "note", "doneAt", "createdAt" ], "additionalProperties": {} }, "FollowUpList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/FollowUp" } } }, "required": [ "items" ], "additionalProperties": {} }, "Note": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "body": { "type": "string" }, "authorId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "contactId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "companyId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "opportunityId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "body", "authorId", "contactId", "companyId", "opportunityId", "createdAt" ], "additionalProperties": {} }, "NoteList": { "type": "object", "properties": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/Note" } } }, "required": [ "notes" ], "additionalProperties": {} }, "Opportunity": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "title": { "type": "string" }, "stage": { "type": "string" }, "valueRial": { "anyOf": [ { "type": "string", "pattern": "^-?\\d+$", "description": "Amount in Rial as a decimal string (64-bit safe)", "examples": [ "5000000" ] }, { "type": "null" } ] }, "contactId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "companyId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "ownerId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "expectedCloseAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "closedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "lostReason": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "stage", "valueRial", "contactId", "companyId", "ownerId", "expectedCloseAt", "closedAt", "lostReason", "createdAt", "updatedAt" ], "additionalProperties": {} }, "OpportunityList": { "type": "object", "properties": { "opportunities": { "type": "array", "items": { "$ref": "#/components/schemas/Opportunity" } }, "byStage": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "object", "properties": { "count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "valueRial": { "type": "string", "pattern": "^-?\\d+$", "description": "Amount in Rial as a decimal string (64-bit safe)", "examples": [ "5000000" ] } }, "required": [ "count", "valueRial" ], "additionalProperties": {} } } }, "required": [ "opportunities", "byStage" ], "additionalProperties": {} }, "LeadList": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "score": { "type": "number" } }, "additionalProperties": {} } } }, "required": [ "items" ], "additionalProperties": {} }, "CatalogItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "name": { "type": "string" }, "sku": { "type": [ "string", "null" ] }, "unit": { "type": "string" }, "unitPriceRial": { "type": "string", "pattern": "^-?\\d+$", "description": "Amount in Rial as a decimal string (64-bit safe)", "examples": [ "5000000" ] }, "taxable": { "type": "boolean" }, "description": { "type": [ "string", "null" ] }, "active": { "type": "boolean" } }, "required": [ "id", "name", "sku", "unit", "unitPriceRial", "taxable", "description", "active" ], "additionalProperties": {} }, "CatalogList": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" } } }, "required": [ "items" ], "additionalProperties": {} }, "Quote": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "number": { "type": "string", "examples": [ "Q-1405-0001" ] }, "title": { "type": "string" }, "status": { "type": "string" }, "contactId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "companyId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "opportunityId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "currentVersion": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "documentId": { "anyOf": [ { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, { "type": "null" } ] }, "sentAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "acceptedAt": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "number", "title", "status", "contactId", "companyId", "opportunityId", "currentVersion", "documentId", "sentAt", "acceptedAt", "createdAt", "updatedAt" ], "additionalProperties": {} }, "QuoteList": { "type": "object", "properties": { "quotes": { "type": "array", "items": { "$ref": "#/components/schemas/Quote" } } }, "required": [ "quotes" ], "additionalProperties": {} }, "QuoteSent": { "type": "object", "properties": { "linkId": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "url": { "type": "string" } }, "required": [ "linkId", "url" ], "additionalProperties": {} }, "TeamReport": { "type": "object", "properties": { "days": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "since": { "type": "string", "format": "date-time" }, "estimated": { "type": "boolean", "const": true }, "scope": { "type": "string" }, "totals": { "type": "object", "properties": { "linksSent": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "linksOpened": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "views": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "linksSent", "linksOpened", "views" ], "additionalProperties": {} }, "documents": { "type": "array", "items": {} }, "members": { "type": "array", "items": {} } }, "required": [ "days", "since", "estimated", "scope", "totals", "documents", "members" ], "additionalProperties": {} }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Delivery id; also in X-Pooshe-Delivery. Use it to drop duplicates", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] }, "type": { "type": "string", "enum": [ "view.opened", "cta.response", "lead.hot", "document.ready", "link.created", "contact.created", "ping" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": {} } }, "required": [ "id", "type", "createdAt", "data" ], "additionalProperties": {} }, "CompanyDetail": { "type": "object", "properties": { "company": { "$ref": "#/components/schemas/Company" } }, "required": [ "company" ], "additionalProperties": {} }, "OpportunityDetail": { "type": "object", "properties": { "opportunity": { "$ref": "#/components/schemas/Opportunity" } }, "additionalProperties": {} }, "QuoteDetail": { "type": "object", "properties": { "id": { "type": "string", "description": "Opaque id (cuid2, ≤ 40 chars)", "examples": [ "k3lssq8mdmgeh0yg06p5hutz" ] } }, "required": [ "id" ], "additionalProperties": {} }, "QuoteIssued": { "type": "object", "properties": {}, "additionalProperties": {} } }, "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "slk_<43 random characters>", "description": "Scopes: crm:read, crm:write; quotes:read, quotes:write; files:read, files:write; sharing:read, sharing:write; analytics:read, analytics:write; legacy read / write = every resource." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Any unique string (≤ 200 printable ASCII; a UUID is ideal). Retrying with the same key and body returns the first response (Idempotent-Replayed: true) instead of acting twice. Kept 24 h. Same key, different body → 422 idempotency_key_reused; while the first is still running → 409 idempotency_in_progress.", "schema": { "type": "string", "maxLength": 200 } } } } }