{ "components": { "responses": { "BadRequestResponse": { "content": { "application/problem+json": { "example": { "code": "intake.invalid_resumable_upload", "instance": "urn:uuid:0f2c9d24-6a6b-4f8b-9f5b-1a2c3d4e5f60", "requestId": "0f2c9d24-6a6b-4f8b-9f5b-1a2c3d4e5f60", "retry": "do_not_retry", "status": 400, "title": "The upload request is invalid.", "type": "https://jiandu.org/docs/references/problem-codes?code=intake.invalid-resumable-upload" }, "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The request syntax, headers, body, or validated input is malformed or invalid", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "ConflictResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The request conflicts with the current resource, revision, lease, credential, or idempotency state", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "MisdirectedRequestResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The request authority or direct peer is outside the configured Jiandu ingress boundary", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "NotFoundResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The resource is unknown or outside the authenticated household scope", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "OriginForbiddenResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The browser mutation did not originate from this application, or the authenticated member lacks the required permission", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "PayloadTooLargeResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "A configured streaming body or per-file size limit was exceeded. A transport-level rejection may omit the JSON body.", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "PreconditionFailedResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The strong revision precondition is stale", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "PreconditionRequiredResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Exactly one valid strong If-Match value is required", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "ServiceUnavailableResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "A required core dependency is unavailable; retry with bounded backoff", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "UnauthorizedResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The opaque credential is absent, ambiguous, malformed, expired, revoked, or invalid", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "UnprocessableEntityResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The supplied bytes, filename, declared field value, or supported-content validation failed", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "UnsupportedMediaTypeResponse": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The payload media type is not accepted for this operation, or the file's actual content type is unsupported", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } } }, "schemas": { "ActiveStorageIntents": { "properties": { "committed": { "format": "int64", "minimum": 0, "type": "integer" }, "prepared": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "prepared", "committed" ], "type": "object" }, "AgentCapabilitiesRequest": { "additionalProperties": false, "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/CaptureDeviceCapability" }, "type": "array" } }, "required": [ "capabilities" ], "type": "object" }, "AgentEnrollmentRequest": { "additionalProperties": false, "properties": { "code": { "description": "One-use enrollment secret created by a household administrator.", "type": "string", "writeOnly": true } }, "required": [ "code" ], "type": "object" }, "AgentEnrollmentResponse": { "properties": { "agentId": { "$ref": "#/components/schemas/CaptureAgentObjectId" }, "credential": { "description": "Narrow revocable device credential returned only at enrollment.", "readOnly": true, "type": "string" }, "leaseSeconds": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "agentId", "credential", "leaseSeconds" ], "type": "object" }, "AgentFailureReason": { "enum": [ "scan_failed", "assembly_failed", "local_storage_failed" ], "type": "string" }, "AgentFailureRequest": { "additionalProperties": false, "properties": { "leaseToken": { "type": "string", "writeOnly": true }, "reason": { "$ref": "#/components/schemas/AgentFailureReason" } }, "required": [ "leaseToken", "reason" ], "type": "object" }, "AgentHeartbeatRequest": { "additionalProperties": false, "properties": { "leaseToken": { "type": "string", "writeOnly": true }, "state": { "$ref": "#/components/schemas/AgentProgressState" } }, "required": [ "leaseToken", "state" ], "type": "object" }, "AgentJobLeaseResponse": { "properties": { "job": { "$ref": "#/components/schemas/CaptureJobResponse" }, "leaseToken": { "description": "Rotated lease capability; never stored in plaintext.", "readOnly": true, "type": "string" } }, "required": [ "job", "leaseToken" ], "type": "object" }, "AgentProgressState": { "enum": [ "scanning", "uploading" ], "type": "string" }, "AgentUploadResponse": { "properties": { "length": { "format": "int64", "minimum": 0, "type": "integer" }, "offset": { "format": "int64", "minimum": 0, "type": "integer" }, "state": { "$ref": "#/components/schemas/CaptureUploadStateResponse" }, "uploadId": { "$ref": "#/components/schemas/UploadObjectId" } }, "required": [ "uploadId", "offset", "length", "state" ], "type": "object" }, "AuthSessionObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^ses_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "AuthenticationMethod": { "description": "Mechanism that established this authenticated principal. It is metadata;\ndurable RBAC permissions are always resolved independently.", "enum": [ "local_token", "password", "personal_access_token", "passkey", "oidc", "ldap", "trusted_proxy" ], "type": "string" }, "AuthenticationMethodsResponse": { "description": "Publicly discoverable sign-in choices. It intentionally reveals no issuer,\ngroup-policy, invitation, or client details.", "properties": { "ldapProviders": { "items": { "$ref": "#/components/schemas/LdapProviderResponse" }, "type": "array" }, "localOwnerToken": { "type": "boolean" }, "localPasskey": { "type": "boolean" }, "localPassword": { "type": "boolean" }, "oidcProviders": { "items": { "$ref": "#/components/schemas/OidcProviderResponse" }, "type": "array" }, "trustedProxyProviders": { "items": { "$ref": "#/components/schemas/TrustedProxyProviderResponse" }, "type": "array" } }, "required": [ "localOwnerToken", "localPassword", "localPasskey", "oidcProviders", "ldapProviders", "trustedProxyProviders" ], "type": "object" }, "AuthorizationGroupObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^grp_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "AuthorizationGroupResponse": { "properties": { "description": { "type": "string" }, "id": { "$ref": "#/components/schemas/AuthorizationGroupObjectId" }, "name": { "type": "string" } }, "required": [ "id", "name", "description" ], "type": "object" }, "AuthorizationMemberResponse": { "properties": { "displayName": { "type": "string" }, "principalId": { "$ref": "#/components/schemas/PrincipalObjectId" }, "state": { "$ref": "#/components/schemas/AuthorizationMembershipState" } }, "required": [ "principalId", "displayName", "state" ], "type": "object" }, "AuthorizationMembershipState": { "enum": [ "active", "suspended" ], "type": "string" }, "AuthorizationMembershipStateResponse": { "properties": { "authorizationVersion": { "pattern": "^[0-9]+$", "type": "string" }, "principalId": { "$ref": "#/components/schemas/PrincipalObjectId" }, "state": { "$ref": "#/components/schemas/AuthorizationMembershipState" } }, "required": [ "principalId", "state", "authorizationVersion" ], "type": "object" }, "AuthorizationPermissionCatalogResponse": { "properties": { "permissions": { "description": "Fixed, application-owned permission vocabulary. Custom roles may only\ncompose these codes; they cannot create a permission that bypasses a\nserver-side authorization check.", "items": { "type": "string" }, "type": "array" } }, "required": [ "permissions" ], "type": "object" }, "AuthorizationRoleObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^role_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "AuthorizationRoleResponse": { "properties": { "description": { "type": "string" }, "id": { "$ref": "#/components/schemas/AuthorizationRoleObjectId" }, "isBuiltin": { "type": "boolean" }, "name": { "type": "string" }, "permissions": { "items": { "type": "string" }, "type": "array" } }, "required": [ "id", "name", "description", "isBuiltin", "permissions" ], "type": "object" }, "AuthorizationStartResponse": { "properties": { "authorizationUrl": { "description": "Provider consent URL the browser should visit.", "type": "string" } }, "required": [ "authorizationUrl" ], "type": "object" }, "BatchIntakeForm": { "description": "Documentation-only shape of the `multipart/form-data` batch body. See [`SingleIntakeForm`].", "properties": { "files": { "description": "Repeated file parts. Order and filenames participate in idempotency. Each file is\nindependently bounded by the configured upload limit.", "items": { "$ref": "#/components/schemas/FilePart" }, "maxItems": 100, "minItems": 2, "type": "array" } }, "required": [ "files" ], "type": "object" }, "BatchIntakeItemResponse": { "properties": { "documentId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentObjectId" } ] }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/BatchItemErrorResponse" } ] }, "fileName": { "maxLength": 255, "minLength": 1, "type": "string" }, "taskId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskObjectId" } ] } }, "required": [ "fileName", "documentId", "taskId", "error" ], "type": "object" }, "BatchIntakeResponse": { "properties": { "batchId": { "$ref": "#/components/schemas/IntakeBatchObjectId" }, "items": { "items": { "$ref": "#/components/schemas/BatchIntakeItemResponse" }, "maxItems": 100, "minItems": 2, "type": "array" } }, "required": [ "batchId", "items" ], "type": "object" }, "BatchItemErrorResponse": { "properties": { "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "maxLength": 1024, "minLength": 1, "type": "string" }, "retryable": { "type": "boolean" }, "suggestedAction": { "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "code", "message", "retryable", "suggestedAction" ], "type": "object" }, "BeginAgentUploadRequest": { "additionalProperties": false, "properties": { "filename": { "description": "Nonempty single-line source filename, limited to 255 encoded bytes at runtime.", "minLength": 1, "type": "string" }, "leaseToken": { "type": "string", "writeOnly": true }, "length": { "description": "Exact nonzero file length; the durable backend uses a signed 64-bit range.", "format": "int64", "minimum": 1, "type": "integer" }, "mediaType": { "description": "Nonempty single-line declared media type, limited to 127 encoded bytes at runtime.", "minLength": 1, "type": "string" }, "sha256": { "pattern": "^[0-9a-f]{64}$", "type": "string" } }, "required": [ "leaseToken", "filename", "mediaType", "length", "sha256" ], "type": "object" }, "BeginOidcLoginRequest": { "additionalProperties": false, "properties": { "invitationToken": { "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "type": [ "string", "null" ] } }, "type": "object" }, "BeginOidcLoginResponse": { "properties": { "authorizationUrl": { "type": "string" } }, "required": [ "authorizationUrl" ], "type": "object" }, "BulkDocumentTarget": { "additionalProperties": false, "properties": { "documentId": { "$ref": "#/components/schemas/DocumentObjectId" }, "revision": { "type": "string" } }, "required": [ "documentId", "revision" ], "type": "object" }, "BulkMutationRequest": { "additionalProperties": false, "properties": { "notificationIds": { "items": { "type": "string" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "notificationIds" ], "type": "object" }, "BulkOrganizationAction": { "oneOf": [ { "properties": { "kind": { "enum": [ "add_tags" ], "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "required": [ "tags", "kind" ], "type": "object" }, { "properties": { "kind": { "enum": [ "remove_tags" ], "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" } }, "required": [ "tags", "kind" ], "type": "object" }, { "properties": { "kind": { "enum": [ "set_correspondent" ], "type": "string" }, "value": { "type": [ "string", "null" ] } }, "required": [ "kind" ], "type": "object" }, { "properties": { "kind": { "enum": [ "set_document_type" ], "type": "string" }, "value": { "type": [ "string", "null" ] } }, "required": [ "kind" ], "type": "object" } ] }, "BulkOrganizeRequest": { "additionalProperties": false, "properties": { "action": { "$ref": "#/components/schemas/BulkOrganizationAction" }, "documents": { "items": { "$ref": "#/components/schemas/BulkDocumentTarget" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "documents", "action" ], "type": "object" }, "BulkOrganizeResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DocumentDetail" }, "maxItems": 100, "minItems": 1, "type": "array" } }, "required": [ "items" ], "type": "object" }, "CanonicalDocumentFields": { "properties": { "correspondent": { "type": [ "string", "null" ] }, "documentDate": { "type": [ "string", "null" ] }, "documentType": { "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "maxItems": 64, "type": "array" }, "title": { "type": [ "string", "null" ] } }, "required": [ "correspondent", "documentDate", "documentType", "tags", "title" ], "type": "object" }, "CaptureAgentListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CaptureAgentResponse" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "CaptureAgentObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^cagt_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "CaptureAgentResponse": { "properties": { "capabilities": { "items": { "$ref": "#/components/schemas/CaptureDeviceCapability" }, "type": "array" }, "displayName": { "description": "Single-line UTF-8 display name, limited to 80 encoded bytes.", "minLength": 1, "type": "string" }, "id": { "$ref": "#/components/schemas/CaptureAgentObjectId" }, "lastSeenAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "revision": { "description": "Canonical positive decimal optimistic revision from 1 through\n18446744073709551615 (`u64::MAX`).", "maxLength": 20, "minLength": 1, "pattern": "^[1-9][0-9]{0,19}$", "type": "string" }, "revoked": { "type": "boolean" } }, "required": [ "id", "displayName", "capabilities", "revoked", "revision" ], "type": "object" }, "CaptureConnectorListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CaptureConnectorResponse" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "CaptureConnectorObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^ccn_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "CaptureConnectorResponse": { "properties": { "displayName": { "description": "Single-line UTF-8 display name, limited to 80 encoded bytes.", "minLength": 1, "type": "string" }, "enabled": { "type": "boolean" }, "id": { "$ref": "#/components/schemas/CaptureConnectorObjectId" }, "lastErrorCode": { "description": "Server-defined safe capture failure code; dispatch against the public problem-code catalog.", "maxLength": 128, "pattern": "^[a-z][a-z0-9_.]{0,127}$", "type": [ "string", "null" ] }, "lastSuccessAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "revision": { "description": "Canonical positive decimal optimistic revision from 1 through\n18446744073709551615 (`u64::MAX`).", "maxLength": 20, "minLength": 1, "pattern": "^[1-9][0-9]{0,19}$", "type": "string" }, "source": { "$ref": "#/components/schemas/CaptureConnectorSource" } }, "required": [ "id", "displayName", "source", "enabled", "revision" ], "type": "object" }, "CaptureConnectorSource": { "oneOf": [ { "properties": { "kind": { "enum": [ "watch_folder" ], "type": "string" }, "relativePath": { "type": "string" }, "rootId": { "type": "string" } }, "required": [ "rootId", "relativePath", "kind" ], "type": "object" }, { "properties": { "endpointId": { "type": "string" }, "kind": { "enum": [ "escl" ], "type": "string" } }, "required": [ "endpointId", "kind" ], "type": "object" } ] }, "CaptureDeviceCapability": { "additionalProperties": false, "properties": { "colorModes": { "items": { "$ref": "#/components/schemas/ScanColorMode" }, "type": "array" }, "deviceId": { "type": "string" }, "displayName": { "type": "string" }, "duplex": { "type": "boolean" }, "formats": { "items": { "$ref": "#/components/schemas/ScanFormat" }, "type": "array" }, "resolutionsDpi": { "items": { "format": "int32", "minimum": 0, "type": "integer" }, "type": "array" }, "sources": { "items": { "$ref": "#/components/schemas/ScanSource" }, "type": "array" } }, "required": [ "deviceId", "displayName", "sources", "colorModes", "resolutionsDpi", "formats", "duplex" ], "type": "object" }, "CaptureEnrollmentObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^cenr_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "CaptureJobListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/CaptureJobResponse" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "CaptureJobObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^cjob_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "CaptureJobResponse": { "properties": { "cancelRequested": { "type": "boolean" }, "createdAtMs": { "format": "int64", "type": "integer" }, "documentId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentObjectId" } ] }, "failureCode": { "description": "Server-defined safe capture or intake failure code. Values are documented in the public\nproblem-code catalog and must not be treated as free-form human text.", "maxLength": 128, "pattern": "^[a-z][a-z0-9_.]{0,127}$", "type": [ "string", "null" ] }, "failureMessage": { "description": "Bounded, localized safe text for people; clients dispatch on failureCode instead.", "maxLength": 512, "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/CaptureJobObjectId" }, "revision": { "description": "Canonical positive decimal optimistic revision from 1 through\n18446744073709551615 (`u64::MAX`).", "maxLength": 20, "minLength": 1, "pattern": "^[1-9][0-9]{0,19}$", "type": "string" }, "settings": { "$ref": "#/components/schemas/ScanSettings" }, "state": { "$ref": "#/components/schemas/CaptureJobStateResponse" }, "target": { "$ref": "#/components/schemas/CaptureJobTargetResponse" }, "taskId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskObjectId" } ] }, "updatedAtMs": { "format": "int64", "type": "integer" }, "uploadId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UploadObjectId" } ] } }, "required": [ "id", "target", "settings", "state", "cancelRequested", "revision", "createdAtMs", "updatedAtMs" ], "type": "object" }, "CaptureJobStateResponse": { "enum": [ "queued", "leased", "scanning", "uploading", "finalizing", "accepted", "failed", "canceled" ], "type": "string" }, "CaptureJobTargetResponse": { "oneOf": [ { "properties": { "endpointId": { "type": "string" }, "kind": { "enum": [ "escl" ], "type": "string" } }, "required": [ "endpointId", "kind" ], "type": "object" }, { "properties": { "agentId": { "$ref": "#/components/schemas/CaptureAgentObjectId" }, "deviceId": { "type": "string" }, "kind": { "enum": [ "agent" ], "type": "string" } }, "required": [ "agentId", "deviceId", "kind" ], "type": "object" } ] }, "CaptureOption": { "properties": { "displayName": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "displayName" ], "type": "object" }, "CaptureOptionsResponse": { "properties": { "esclEndpoints": { "items": { "$ref": "#/components/schemas/CaptureOption" }, "type": "array" }, "watchRoots": { "items": { "$ref": "#/components/schemas/CaptureOption" }, "type": "array" } }, "required": [ "watchRoots", "esclEndpoints" ], "type": "object" }, "CaptureUploadStateResponse": { "enum": [ "open", "received", "finalizing", "accepted", "failed", "canceled", "expired" ], "type": "string" }, "ChangeFeedCapability": { "properties": { "polling": { "type": "boolean" }, "recommendedPollIntervalMs": { "format": "int32", "maximum": 60000, "minimum": 1000, "type": "integer" }, "serverSentEvents": { "type": "boolean" } }, "required": [ "polling", "serverSentEvents", "recommendedPollIntervalMs" ], "type": "object" }, "ChangeFeedResponse": { "properties": { "changes": { "items": { "$ref": "#/components/schemas/NotificationChange" }, "maxItems": 100, "type": "array" }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "resyncRequired": { "type": "boolean" } }, "required": [ "changes", "nextCursor", "hasMore", "resyncRequired" ], "type": "object" }, "ClaimInstallationSetupRequest": { "additionalProperties": false, "properties": { "setupToken": { "description": "Protected 256-bit recovery credential read from the owner-only file.", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-fA-F]{64}$", "type": "string", "writeOnly": true } }, "required": [ "setupToken" ], "type": "object" }, "ConnectedBrowserCapability": { "properties": { "backgroundDelivery": { "type": "boolean" }, "defaultEnabled": { "type": "boolean" }, "requiresBrowserPermission": { "type": "boolean" }, "supported": { "type": "boolean" } }, "required": [ "supported", "backgroundDelivery", "requiresBrowserPermission", "defaultEnabled" ], "type": "object" }, "ConnectorListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ConnectorResponse" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "ConnectorResponse": { "description": "The connector as returned by the API.\n\nThere is deliberately no credential field of any kind: the sealed refresh\ntoken is server-side state and never crosses this boundary.", "properties": { "authorizationState": { "type": "string" }, "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "id": { "$ref": "#/components/schemas/EmailConnectorObjectId" }, "lastErrorCode": { "type": [ "string", "null" ] }, "lastPolledAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "mailboxQuery": { "type": [ "string", "null" ] }, "pollIntervalSeconds": { "format": "int32", "minimum": 0, "type": "integer" }, "provider": { "type": "string" }, "revision": { "type": "string" }, "tags": { "items": { "type": "string" }, "type": "array" }, "titleTemplate": { "type": [ "string", "null" ] } }, "required": [ "id", "provider", "displayName", "tags", "pollIntervalSeconds", "enabled", "authorizationState", "revision" ], "type": "object" }, "CorrectDocumentRequest": { "additionalProperties": false, "properties": { "correspondent": { "type": [ "string", "null" ] }, "documentDate": { "type": [ "string", "null" ] }, "documentType": { "type": [ "string", "null" ] }, "tags": { "items": { "type": "string" }, "maxItems": 64, "type": "array" }, "title": { "type": [ "string", "null" ] } }, "required": [ "tags" ], "type": "object" }, "CreateAuthorizationGroupRequest": { "additionalProperties": false, "properties": { "description": { "maxLength": 512, "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateAuthorizationRoleRequest": { "additionalProperties": false, "properties": { "description": { "maxLength": 512, "type": "string" }, "name": { "maxLength": 128, "minLength": 1, "type": "string" }, "permissions": { "items": { "type": "string" }, "maxItems": 21, "minItems": 1, "type": "array" } }, "required": [ "name", "permissions" ], "type": "object" }, "CreateCaptureConnectorRequest": { "additionalProperties": false, "properties": { "displayName": { "description": "Single-line UTF-8 display name, limited to 80 encoded bytes at runtime.", "minLength": 1, "type": "string" }, "enabled": { "type": "boolean" }, "source": { "$ref": "#/components/schemas/CaptureConnectorSource" } }, "required": [ "displayName", "source" ], "type": "object" }, "CreateCaptureJobRequest": { "additionalProperties": false, "properties": { "settings": { "$ref": "#/components/schemas/ScanSettings" }, "target": { "$ref": "#/components/schemas/CreateCaptureJobTarget" } }, "required": [ "target", "settings" ], "type": "object" }, "CreateCaptureJobTarget": { "oneOf": [ { "properties": { "endpointId": { "type": "string" }, "kind": { "enum": [ "escl" ], "type": "string" } }, "required": [ "endpointId", "kind" ], "type": "object" }, { "properties": { "agentId": { "$ref": "#/components/schemas/CaptureAgentObjectId" }, "deviceId": { "type": "string" }, "kind": { "enum": [ "agent" ], "type": "string" } }, "required": [ "agentId", "deviceId", "kind" ], "type": "object" } ] }, "CreateConnectorRequest": { "additionalProperties": false, "properties": { "displayName": { "type": "string" }, "mailboxQuery": { "type": [ "string", "null" ] }, "pollIntervalSeconds": { "format": "int32", "minimum": 0, "type": "integer" }, "tags": { "items": { "type": "string" }, "type": "array" }, "titleTemplate": { "type": [ "string", "null" ] } }, "required": [ "displayName", "pollIntervalSeconds" ], "type": "object" }, "CreateDocumentAccessGrantRequest": { "additionalProperties": false, "description": "Add or replace one live direct or group grant on a restricted document.", "properties": { "expiresAtMs": { "description": "A Unix millisecond instant strictly after the request time. `null` or\nomission makes a normal manager grant non-expiring; owner-recovery\ngrants remain service-owned and cannot be made through this endpoint.", "format": "int64", "type": [ "integer", "null" ] }, "role": { "$ref": "#/components/schemas/DocumentAccessRole" }, "subjectId": { "$ref": "#/components/schemas/JianduObjectId" }, "subjectKind": { "$ref": "#/components/schemas/DocumentGrantSubjectKind" } }, "required": [ "subjectKind", "subjectId", "role", "expiresAtMs" ], "type": "object" }, "CreateEnrollmentRequest": { "additionalProperties": false, "properties": { "displayName": { "description": "Single-line UTF-8 display name, limited to 80 encoded bytes at runtime.", "minLength": 1, "type": "string" }, "lifetimeSeconds": { "description": "One-use code lifetime in seconds: one minute through 24 hours.", "format": "int32", "maximum": 86400, "minimum": 60, "type": "integer" } }, "required": [ "displayName", "lifetimeSeconds" ], "type": "object" }, "CreateLocalPasswordAccountRequest": { "additionalProperties": false, "properties": { "displayName": { "description": "Nonblank display name of at most 200 UTF-8 bytes, without control characters.", "minLength": 1, "type": "string" }, "password": { "description": "Password containing 12 through 1024 UTF-8 bytes. The byte boundary is\ndescribed instead of using JSON Schema's character-counting length\nkeywords.", "type": "string", "writeOnly": true }, "roleId": { "$ref": "#/components/schemas/AuthorizationRoleObjectId", "description": "Existing built-in or custom household role. The authorization service\nverifies delegation under the member-creation transaction." }, "username": { "maxLength": 64, "minLength": 3, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" } }, "required": [ "displayName", "username", "password", "roleId" ], "type": "object" }, "CreateMembershipInvitationRequest": { "additionalProperties": false, "properties": { "authenticationMethods": { "description": "Omit or pass an empty array to allow any supported admission method.", "items": { "$ref": "#/components/schemas/InvitationAuthenticationMethod" }, "maxItems": 4, "type": "array" }, "expiresInSeconds": { "description": "How long the one-use invitation may be redeemed. Five minutes avoids\naccidental stale invites; thirty days prevents indefinite bearers.", "format": "int32", "maximum": 2592000, "minimum": 300, "type": "integer" }, "providerIds": { "description": "Exact stable provider IDs. When non-empty, authenticationMethods must\ncontain only provider-backed methods and may not be empty.", "items": { "type": "string" }, "maxItems": 16, "type": "array" }, "roleId": { "$ref": "#/components/schemas/AuthorizationRoleObjectId", "description": "A built-in or existing household custom role. It is never inferred\nfrom an identity-provider claim." } }, "required": [ "roleId", "expiresInSeconds" ], "type": "object" }, "CreateMembershipInvitationResponse": { "properties": { "authenticationMethods": { "items": { "$ref": "#/components/schemas/InvitationAuthenticationMethod" }, "type": "array" }, "expiresAtMs": { "format": "int64", "minimum": 0, "type": "integer" }, "id": { "$ref": "#/components/schemas/MembershipInvitationObjectId" }, "providerIds": { "items": { "type": "string" }, "type": "array" }, "roleId": { "$ref": "#/components/schemas/AuthorizationRoleObjectId" }, "token": { "description": "This bearer is returned exactly once. Only its domain-separated\nverifier is retained by the server, so callers must deliver it over a\nchannel appropriate for an authentication credential.", "maxLength": 43, "minLength": 43, "pattern": "^[A-Za-z0-9_-]+$", "type": "string" } }, "required": [ "id", "roleId", "expiresAtMs", "authenticationMethods", "providerIds", "token" ], "type": "object" }, "CreatePaperlessImportRequest": { "additionalProperties": false, "properties": { "bulkOperations": { "items": { "$ref": "#/components/schemas/BulkOrganizationAction" }, "maxItems": 16, "type": "array" }, "files": { "items": { "$ref": "#/components/schemas/PaperlessImportFileRequest" }, "maxItems": 1000000, "minItems": 1, "type": "array" } }, "required": [ "files", "bulkOperations" ], "type": "object" }, "CreatePersonalAccessTokenRequest": { "additionalProperties": false, "properties": { "expiresAtMs": { "description": "Omit to use the bounded server default (currently 90 days).", "format": "int64", "type": [ "integer", "null" ] }, "label": { "description": "Nonblank integration label of at most 128 UTF-8 bytes, without control characters.", "minLength": 1, "type": "string" }, "scopes": { "items": { "$ref": "#/components/schemas/PersonalAccessScope" }, "maxItems": 4, "minItems": 1, "type": "array" } }, "required": [ "label", "scopes" ], "type": "object" }, "CreatePersonalAccessTokenResponse": { "properties": { "accessToken": { "description": "Returned exactly once. It is not persisted in plaintext and must be\ncopied by the caller before this response is discarded.", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-f]{64}$", "readOnly": true, "type": "string" }, "token": { "$ref": "#/components/schemas/PersonalAccessToken" } }, "required": [ "token", "accessToken" ], "type": "object" }, "CreateSessionRequest": { "oneOf": [ { "$ref": "#/components/schemas/LegacyLocalTokenSessionRequest", "description": "Backward-compatible Owner-token shape with an omitted method." }, { "$ref": "#/components/schemas/LocalTokenSessionRequest", "description": "Explicit Owner-token shape." }, { "$ref": "#/components/schemas/PasswordSessionRequest", "description": "Local account credential shape." } ] }, "DocumentAccessGrant": { "description": "One audit-safe grant descriptor. It contains stable local IDs and timing,\nnever document content, source paths, or identity-provider claims.", "properties": { "createdAtMs": { "format": "int64", "type": "integer" }, "expiresAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "id": { "$ref": "#/components/schemas/DocumentAccessGrantObjectId" }, "ownerRecovery": { "description": "True only for the immutable installation-owner recovery grant.", "type": "boolean" }, "revokedAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "role": { "$ref": "#/components/schemas/DocumentAccessRole" }, "subjectId": { "$ref": "#/components/schemas/JianduObjectId" }, "subjectKind": { "$ref": "#/components/schemas/DocumentGrantSubjectKind" } }, "required": [ "id", "subjectKind", "subjectId", "role", "createdAtMs", "ownerRecovery" ], "type": "object" }, "DocumentAccessGrantObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^dgr_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "DocumentAccessRole": { "description": "Direct or group grant role. Higher roles include every lower capability.", "enum": [ "viewer", "editor", "manager" ], "type": "string" }, "DocumentAccessSnapshot": { "properties": { "grants": { "items": { "$ref": "#/components/schemas/DocumentAccessGrant" }, "type": "array" }, "policyManagerPrincipalId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalObjectId" } ] }, "visibility": { "$ref": "#/components/schemas/DocumentVisibility" } }, "required": [ "visibility", "policyManagerPrincipalId", "grants" ], "type": "object" }, "DocumentDetail": { "allOf": [ { "$ref": "#/components/schemas/DocumentSummary" }, { "properties": { "history": { "items": { "$ref": "#/components/schemas/DocumentHistoryEntry" }, "maxItems": 100, "type": "array" }, "optionalEnrichment": { "$ref": "#/components/schemas/OptionalEnrichment" }, "original": { "$ref": "#/components/schemas/OriginalDescriptor" }, "preview": { "$ref": "#/components/schemas/PreviewDescriptor" }, "provenance": { "$ref": "#/components/schemas/DocumentProvenance" } }, "required": [ "history", "original", "preview", "provenance", "optionalEnrichment" ], "type": "object" } ] }, "DocumentGrantSubjectKind": { "enum": [ "principal", "group" ], "type": "string" }, "DocumentHistoryEntry": { "properties": { "actor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalObjectId" } ] }, "at": { "type": "string" }, "generation": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "id": { "$ref": "#/components/schemas/DocumentHistoryObjectId" }, "kind": { "type": "string" }, "summary": { "type": "string" } }, "required": [ "id", "kind", "at", "actor", "generation", "summary" ], "type": "object" }, "DocumentHistoryObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^hist_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "DocumentIntakeAccepted": { "properties": { "documentId": { "$ref": "#/components/schemas/DocumentObjectId" }, "duplicateOf": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentObjectId", "description": "Reserved duplicate relationship; null for the current native intake implementation." } ] }, "taskId": { "$ref": "#/components/schemas/TaskObjectId" } }, "required": [ "documentId", "taskId", "duplicateOf" ], "type": "object" }, "DocumentLifecycle": { "enum": [ "active", "archived", "trashed" ], "type": "string" }, "DocumentList": { "properties": { "items": { "items": { "$ref": "#/components/schemas/DocumentSummary" }, "maxItems": 100, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] }, "warnings": { "items": { "$ref": "#/components/schemas/DocumentListWarning" }, "maxItems": 2, "type": "array" } }, "required": [ "items", "nextCursor", "warnings" ], "type": "object" }, "DocumentListWarning": { "properties": { "code": { "$ref": "#/components/schemas/DocumentListWarningCode" }, "count": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "code", "count" ], "type": "object" }, "DocumentListWarningCode": { "enum": [ "search_coverage_indexing", "search_coverage_failed", "search_fuzzy_fallback" ], "type": "string" }, "DocumentObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^doc_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "DocumentProvenance": { "properties": { "correspondent": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldProvenance" } ] }, "documentDate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldProvenance" } ] }, "documentType": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldProvenance" } ] }, "tags": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldProvenance" } ] }, "title": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/FieldProvenance" } ] } }, "required": [ "title", "documentDate", "correspondent", "documentType", "tags" ], "type": "object" }, "DocumentSnippetSegment": { "description": "One run of a search-result excerpt: either ordinary text or a run the\nquery matched. Structured rather than markup, matching the deployment\nprofile's ban on inline styles/`innerHTML` — the caller builds real\nelements from these, the same contract the client's own (now-legacy,\nnon-search) snippet extraction already used.", "properties": { "matched": { "type": "boolean" }, "text": { "type": "string" } }, "required": [ "text", "matched" ], "type": "object" }, "DocumentSort": { "enum": [ "relevance", "updated_desc", "updated_asc", "document_date_desc", "title_asc" ], "type": "string" }, "DocumentState": { "enum": [ "accepted", "processing", "failed", "canceled", "indexing", "index_failed", "needs_review", "ready", "ready_with_warnings" ], "type": "string" }, "DocumentSummary": { "allOf": [ { "$ref": "#/components/schemas/CanonicalDocumentFields" }, { "properties": { "id": { "$ref": "#/components/schemas/DocumentObjectId" }, "lifecycle": { "$ref": "#/components/schemas/DocumentLifecycle" }, "reviewStatus": { "$ref": "#/components/schemas/ReviewStatus" }, "revision": { "type": "string" }, "snippet": { "description": "Present only when this page was produced by a search query and the\nmatch has context to show — never populated when merely browsing.", "items": { "$ref": "#/components/schemas/DocumentSnippetSegment" }, "type": [ "array", "null" ] }, "state": { "$ref": "#/components/schemas/DocumentState" }, "updatedAt": { "type": [ "string", "null" ] } }, "required": [ "id", "revision", "state", "reviewStatus", "lifecycle", "updatedAt", "snippet" ], "type": "object" } ] }, "DocumentVersionObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^dver_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "DocumentVisibility": { "description": "Explicit policy for one document. Absence of a row is equivalent to\n`Shared`, which preserves compatibility with existing household libraries.", "enum": [ "shared", "restricted" ], "type": "string" }, "EmailConnectorObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^emc_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "EmptyLearningCommand": { "additionalProperties": false, "type": "object" }, "EnrollmentResponse": { "properties": { "code": { "description": "Returned once; Jiandu stores only its digest.", "readOnly": true, "type": "string" }, "enrollmentId": { "$ref": "#/components/schemas/CaptureEnrollmentObjectId" }, "expiresAtMs": { "format": "int64", "type": "integer" } }, "required": [ "enrollmentId", "code", "expiresAtMs" ], "type": "object" }, "EventObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^evt_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "ExternalIdentityListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/ExternalIdentityMetadata" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "ExternalIdentityMetadata": { "properties": { "authenticationMethod": { "$ref": "#/components/schemas/AuthenticationMethod" }, "createdAtMs": { "format": "int64", "type": "integer" }, "providerId": { "type": "string" } }, "required": [ "providerId", "authenticationMethod", "createdAtMs" ], "type": "object" }, "FieldProvenance": { "properties": { "confidence": { "format": "double", "type": [ "number", "null" ] }, "observedAt": { "type": [ "string", "null" ] }, "producer": { "type": [ "string", "null" ] }, "producerVersion": { "type": [ "string", "null" ] }, "source": { "type": "string" } }, "required": [ "source", "producer", "producerVersion", "confidence", "observedAt" ], "type": "object" }, "FilePart": { "description": "One bounded PDF, PNG, JPEG, or UTF-8 text original. The configured per-file limit is enforced\nwhile streaming.", "format": "binary", "type": "string" }, "FinishAdmissionPasskeyRegistrationRequest": { "additionalProperties": false, "properties": { "ceremonyId": { "$ref": "#/components/schemas/PasskeyCeremonyObjectId" }, "credential": {} }, "required": [ "ceremonyId", "credential" ], "type": "object" }, "FinishMemberPasskeyRegistrationRequest": { "additionalProperties": false, "properties": { "ceremonyId": { "$ref": "#/components/schemas/PasskeyCeremonyObjectId" }, "credential": {} }, "required": [ "ceremonyId", "credential" ], "type": "object" }, "FinishPasskeyAuthenticationRequest": { "additionalProperties": false, "properties": { "ceremonyId": { "$ref": "#/components/schemas/PasskeyCeremonyObjectId" }, "credential": {} }, "required": [ "ceremonyId", "credential" ], "type": "object" }, "FrontendLogBatch": { "additionalProperties": false, "properties": { "records": { "description": "Ordered browser events without timestamps or arbitrary context.", "items": { "$ref": "#/components/schemas/FrontendLogRecord" }, "maxItems": 64, "minItems": 1, "type": "array" }, "schemaVersion": { "description": "Fixed schema revision for browser diagnostic records.", "format": "int32", "maximum": 1, "minimum": 1, "type": "integer" } }, "required": [ "schemaVersion", "records" ], "type": "object" }, "FrontendLogComponent": { "enum": [ "api", "app", "runtime", "uploads" ], "type": "string" }, "FrontendLogEvent": { "enum": [ "jiandu.web.api.request.cancelled", "jiandu.web.api.request.completed", "jiandu.web.api.request.failed", "jiandu.web.api.response.invalid", "jiandu.web.api.transport.failed", "jiandu.web.api.upload.cancelled", "jiandu.web.api.upload.completed", "jiandu.web.api.upload.failed", "jiandu.web.api.upload.started", "jiandu.web.app.boot.failed", "jiandu.web.app.boot.started", "jiandu.web.app.readiness.unavailable", "jiandu.web.app.ready", "jiandu.web.app.session.restore_failed", "jiandu.web.app.session.restored", "jiandu.web.app.session.signed_out", "jiandu.web.app.sign_in.completed", "jiandu.web.app.sign_in.failed", "jiandu.web.app.version.unavailable", "jiandu.web.runtime.unhandled_error", "jiandu.web.runtime.unhandled_rejection", "jiandu.web.uploads.file.rejected", "jiandu.web.uploads.processing.cancelled", "jiandu.web.uploads.processing.completed", "jiandu.web.uploads.processing.completed_degraded", "jiandu.web.uploads.processing.failed", "jiandu.web.uploads.processing.poll_exhausted", "jiandu.web.uploads.transfer.accepted", "jiandu.web.uploads.transfer.cancelled", "jiandu.web.uploads.transfer.failed", "jiandu.web.uploads.transfer.retrying", "jiandu.web.uploads.transfer.started" ], "type": "string" }, "FrontendLogLevel": { "enum": [ "debug", "info", "warn", "error" ], "type": "string" }, "FrontendLogOutcome": { "enum": [ "accepted", "cancelled", "completed", "degraded", "failed", "offline", "rejected", "retryable", "retrying", "signed_in", "signed_out", "started", "unauthenticated" ], "type": "string" }, "FrontendLogRecord": { "additionalProperties": false, "properties": { "attempt": { "description": "A retry ordinal generated by the UI, never an arbitrary counter.", "format": "int32", "maximum": 3, "minimum": 1, "type": [ "integer", "null" ] }, "component": { "$ref": "#/components/schemas/FrontendLogComponent" }, "event": { "$ref": "#/components/schemas/FrontendLogEvent" }, "level": { "$ref": "#/components/schemas/FrontendLogLevel" }, "outcome": { "$ref": "#/components/schemas/FrontendLogOutcome" }, "traceparent": { "description": "Optional, best-effort W3C context hint for the original UI operation.\nValues are only used when they are canonical and bounded; malformed\nhints are discarded and the record remains under the request trace.", "maxLength": 55, "minLength": 55, "pattern": "^00-[0-9a-f]{32}-[0-9a-f]{16}-(00|01)$", "type": [ "string", "null" ] } }, "required": [ "level", "event", "component", "outcome" ], "type": "object" }, "HouseholdObjectId": { "maxLength": 30, "minLength": 30, "pattern": "^hh_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "InboxCapability": { "properties": { "mandatory": { "type": "boolean" }, "supported": { "type": "boolean" } }, "required": [ "supported", "mandatory" ], "type": "object" }, "InstallationSetupResponse": { "properties": { "claimAvailable": { "type": "boolean" }, "state": { "$ref": "#/components/schemas/InstallationSetupStateResponse" } }, "required": [ "state", "claimAvailable" ], "type": "object" }, "InstallationSetupStateResponse": { "enum": [ "unclaimed", "claimed" ], "type": "string" }, "IntakeBatchObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^bat_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "IntakeItemObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^item_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "IntegrityCheckStatus": { "enum": [ "ok", "unhealthy" ], "type": "string" }, "IntegrityChecks": { "properties": { "blobStorage": { "$ref": "#/components/schemas/IntegrityCheckStatus" }, "databaseStructure": { "$ref": "#/components/schemas/IntegrityCheckStatus" }, "foreignKeys": { "$ref": "#/components/schemas/IntegrityCheckStatus" } }, "required": [ "databaseStructure", "foreignKeys", "blobStorage" ], "type": "object" }, "IntegrityReport": { "description": "Fixed-shape operator result containing only aggregate status and bounded counts; paths,\nlocators, identifiers, row contents, and raw database errors are never exposed.", "properties": { "checkedAtMs": { "format": "int64", "minimum": 0, "type": "integer" }, "checks": { "$ref": "#/components/schemas/IntegrityChecks" }, "maintenance": { "$ref": "#/components/schemas/MaintenanceIntegrity" }, "status": { "$ref": "#/components/schemas/ReadinessStatus" } }, "required": [ "status", "checkedAtMs", "checks", "maintenance" ], "type": "object" }, "InvitationAuthenticationMethod": { "enum": [ "passkey", "oidc", "ldap", "trusted_proxy" ], "type": "string" }, "JianduObjectId": { "maxLength": 91, "minLength": 29, "pattern": "^(?:hh|prn|rcp|ses|minv|role|grp|dgr|pkc|pcer|pat|doc|dver|blob|art|fact|edit|hist|proj|run|step|task|bat|item|upl|evt|aud|del|ntf|nchg|rbl|sug|rule|rapp|obs|laud|emc|pub|mig|tmb|ccn|cjob|cagt|cenr|pns|pwrk|pinv|pcmt|pcmd)_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "LdapLinkRequest": { "additionalProperties": false, "properties": { "password": { "description": "Nonempty LDAP password of at most 4096 UTF-8 bytes, without NUL characters.", "type": "string", "writeOnly": true }, "username": { "description": "Nonempty LDAP username of at most 512 UTF-8 bytes, without control characters.", "type": "string" } }, "required": [ "username", "password" ], "type": "object" }, "LdapProviderResponse": { "properties": { "displayName": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "displayName" ], "type": "object" }, "LdapSignInRequest": { "additionalProperties": false, "properties": { "invitationToken": { "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "type": [ "string", "null" ], "writeOnly": true }, "password": { "description": "Nonempty LDAP password of at most 4096 UTF-8 bytes, without NUL characters.", "type": "string", "writeOnly": true }, "username": { "description": "Nonempty LDAP username of at most 512 UTF-8 bytes, without control characters.", "type": "string" } }, "required": [ "username", "password" ], "type": "object" }, "LearningAction": { "enum": [ "replace_value", "set_value", "add_tag" ], "type": "string" }, "LearningAuditAction": { "enum": [ "settings_updated", "suggestion_created", "suggestion_accepted", "suggestion_rejected", "suggestion_restored", "rule_enabled", "rule_disabled", "rule_undone", "rule_applied", "learning_reset" ], "type": "string" }, "LearningAuditEntry": { "properties": { "action": { "$ref": "#/components/schemas/LearningAuditAction" }, "createdAtMs": { "format": "int64", "type": "integer" }, "field": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LearningField" } ] }, "id": { "$ref": "#/components/schemas/LearningAuditObjectId" }, "relatedRuleId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LearningRuleObjectId", "description": "Rule owning an ACL-visible application audit entry. Document IDs are\nintentionally omitted from the learning audit projection." } ] }, "subject": { "$ref": "#/components/schemas/LearningAuditSubject" }, "subjectId": { "type": "string" } }, "required": [ "id", "action", "subject", "subjectId", "field", "relatedRuleId", "createdAtMs" ], "type": "object" }, "LearningAuditObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^laud_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "LearningAuditSubject": { "enum": [ "settings", "suggestion", "rule", "application", "reset" ], "type": "string" }, "LearningExport": { "description": "A privacy-scoped export. Only records backed by a document the requesting\nprincipal can currently read are included; audit rows never carry values\nor document identifiers.", "properties": { "applications": { "items": { "$ref": "#/components/schemas/LearningExportApplication" }, "type": "array" }, "audit": { "items": { "$ref": "#/components/schemas/LearningAuditEntry" }, "type": "array" }, "exportedAtMs": { "format": "int64", "type": "integer" }, "observations": { "items": { "$ref": "#/components/schemas/LearningExportObservation" }, "type": "array" }, "rules": { "items": { "$ref": "#/components/schemas/LearningRule" }, "type": "array" }, "schemaVersion": { "format": "int32", "minimum": 0, "type": "integer" }, "settings": { "$ref": "#/components/schemas/LearningSettings" }, "suggestions": { "items": { "$ref": "#/components/schemas/LearningSuggestion" }, "type": "array" }, "truncated": { "type": "boolean" } }, "required": [ "schemaVersion", "exportedAtMs", "settings", "suggestions", "rules", "observations", "applications", "audit", "truncated" ], "type": "object" }, "LearningExportApplication": { "properties": { "action": { "$ref": "#/components/schemas/LearningAction" }, "appliedAtMs": { "format": "int64", "type": "integer" }, "appliedValue": { "type": "string" }, "ruleId": { "$ref": "#/components/schemas/LearningRuleObjectId" }, "sourceValue": { "type": [ "string", "null" ] }, "targetField": { "$ref": "#/components/schemas/LearningField" } }, "required": [ "ruleId", "action", "targetField", "sourceValue", "appliedValue", "appliedAtMs" ], "type": "object" }, "LearningExportObservation": { "properties": { "action": { "$ref": "#/components/schemas/LearningAction" }, "conditionField": { "$ref": "#/components/schemas/LearningField" }, "conditionValue": { "type": "string" }, "observedAtMs": { "format": "int64", "type": "integer" }, "replacementValue": { "type": "string" }, "sourceValue": { "type": [ "string", "null" ] }, "targetField": { "$ref": "#/components/schemas/LearningField" } }, "required": [ "action", "targetField", "conditionField", "conditionValue", "sourceValue", "replacementValue", "observedAtMs" ], "type": "object" }, "LearningField": { "enum": [ "title", "correspondent", "document_date", "document_type", "tags" ], "type": "string" }, "LearningFieldSettings": { "additionalProperties": false, "properties": { "correspondent": { "type": "boolean" }, "documentDate": { "type": "boolean" }, "documentType": { "type": "boolean" }, "tags": { "type": "boolean" }, "title": { "type": "boolean" } }, "required": [ "title", "correspondent", "documentDate", "documentType", "tags" ], "type": "object" }, "LearningFieldSettingsPatch": { "additionalProperties": false, "properties": { "correspondent": { "type": [ "boolean", "null" ] }, "documentDate": { "type": [ "boolean", "null" ] }, "documentType": { "type": [ "boolean", "null" ] }, "tags": { "type": [ "boolean", "null" ] }, "title": { "type": [ "boolean", "null" ] } }, "type": "object" }, "LearningMode": { "enum": [ "conservative", "balanced", "eager" ], "type": "string" }, "LearningResetResult": { "properties": { "applicationsRemoved": { "format": "int64", "minimum": 0, "type": "integer" }, "observationsRemoved": { "format": "int64", "minimum": 0, "type": "integer" }, "rulesRemoved": { "format": "int64", "minimum": 0, "type": "integer" }, "settings": { "$ref": "#/components/schemas/LearningSettings" }, "suggestionsRemoved": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "observationsRemoved", "suggestionsRemoved", "rulesRemoved", "applicationsRemoved", "settings" ], "type": "object" }, "LearningRule": { "properties": { "action": { "$ref": "#/components/schemas/LearningAction" }, "applicationCount": { "description": "Count is recomputed in the caller's document scope and never reveals\napplications to restricted documents.", "format": "int32", "minimum": 0, "type": "integer" }, "appliedValue": { "type": "string" }, "conditionField": { "$ref": "#/components/schemas/LearningField" }, "conditionValue": { "type": "string" }, "createdAtMs": { "format": "int64", "type": "integer" }, "detailsAvailable": { "description": "False when the exact reviewed supporting representation is no longer\nbacked by shared evidence in the caller's live ACL. The rule remains\nvisible/manageable, but learned values are redacted.", "type": "boolean" }, "id": { "$ref": "#/components/schemas/LearningRuleObjectId" }, "lastAppliedAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "sourceSuggestionId": { "$ref": "#/components/schemas/LearningSuggestionObjectId" }, "sourceValue": { "type": [ "string", "null" ] }, "state": { "$ref": "#/components/schemas/LearningRuleState" }, "targetField": { "$ref": "#/components/schemas/LearningField" }, "updatedAtMs": { "format": "int64", "type": "integer" } }, "required": [ "id", "sourceSuggestionId", "action", "targetField", "conditionField", "conditionValue", "sourceValue", "appliedValue", "detailsAvailable", "state", "applicationCount", "lastAppliedAtMs", "createdAtMs", "updatedAtMs" ], "type": "object" }, "LearningRuleObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^rule_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "LearningRuleState": { "enum": [ "active", "disabled", "undone" ], "type": "string" }, "LearningSettings": { "additionalProperties": false, "properties": { "enabled": { "type": "boolean" }, "fields": { "$ref": "#/components/schemas/LearningFieldSettings" }, "mode": { "$ref": "#/components/schemas/LearningMode" }, "revision": { "description": "Opaque optimistic-concurrency fence used by settings writes.", "type": "string" }, "updatedAtMs": { "format": "int64", "type": "integer" } }, "required": [ "enabled", "mode", "fields", "revision", "updatedAtMs" ], "type": "object" }, "LearningSettingsPatch": { "additionalProperties": false, "properties": { "enabled": { "type": [ "boolean", "null" ] }, "fields": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LearningFieldSettingsPatch" } ] }, "mode": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/LearningMode" } ] } }, "type": "object" }, "LearningSnapshot": { "properties": { "audit": { "items": { "$ref": "#/components/schemas/LearningAuditEntry" }, "maxItems": 100, "type": "array" }, "rules": { "items": { "$ref": "#/components/schemas/LearningRule" }, "maxItems": 100, "type": "array" }, "settings": { "$ref": "#/components/schemas/LearningSettings" }, "suggestions": { "description": "At most 100 pending plus the 100 most recent rejected suppressions.", "items": { "$ref": "#/components/schemas/LearningSuggestion" }, "maxItems": 200, "type": "array" } }, "required": [ "settings", "suggestions", "rules", "audit" ], "type": "object" }, "LearningSuggestion": { "properties": { "action": { "$ref": "#/components/schemas/LearningAction" }, "affectedDocumentCount": { "description": "Currently-readable documents the proposed rule would change, excluding\ntargets whose current canonical value is user-authored.", "format": "int32", "minimum": 0, "type": "integer" }, "conditionField": { "$ref": "#/components/schemas/LearningField" }, "conditionValue": { "type": "string" }, "createdAtMs": { "format": "int64", "type": "integer" }, "evidenceCount": { "format": "int32", "minimum": 0, "type": "integer" }, "id": { "$ref": "#/components/schemas/LearningSuggestionObjectId" }, "previewDocuments": { "items": { "$ref": "#/components/schemas/LearningSuggestionDocumentPreview" }, "maxItems": 4, "type": "array" }, "sourceValue": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/LearningSuggestionStatus" }, "suggestedValue": { "type": "string" }, "targetField": { "$ref": "#/components/schemas/LearningField" }, "threshold": { "format": "int32", "minimum": 0, "type": "integer" }, "updatedAtMs": { "format": "int64", "type": "integer" } }, "required": [ "id", "action", "targetField", "conditionField", "conditionValue", "sourceValue", "suggestedValue", "evidenceCount", "affectedDocumentCount", "previewDocuments", "threshold", "status", "createdAtMs", "updatedAtMs" ], "type": "object" }, "LearningSuggestionDocumentPreview": { "properties": { "documentId": { "$ref": "#/components/schemas/DocumentObjectId" }, "title": { "type": [ "string", "null" ] } }, "required": [ "documentId", "title" ], "type": "object" }, "LearningSuggestionObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^sug_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "LearningSuggestionStatus": { "enum": [ "pending", "accepted", "rejected" ], "type": "string" }, "LegacyComponentHealth": { "properties": { "status": { "type": "string" } }, "required": [ "status" ], "type": "object" }, "LegacyHealth": { "properties": { "database": { "$ref": "#/components/schemas/LegacyComponentHealth" }, "status": { "type": "string" }, "storage": { "$ref": "#/components/schemas/LegacyComponentHealth" } }, "required": [ "status", "database", "storage" ], "type": "object" }, "LegacyLocalTokenSessionRequest": { "additionalProperties": false, "properties": { "accessToken": { "description": "256-bit local recovery token read from the mode-0600 first-run token file.", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-f]{64}$", "type": "string", "writeOnly": true } }, "required": [ "accessToken" ], "type": "object" }, "LivenessResponse": { "properties": { "status": { "type": "string" } }, "required": [ "status" ], "type": "object" }, "LocalPasswordAccountResponse": { "properties": { "principalId": { "$ref": "#/components/schemas/PrincipalObjectId" } }, "required": [ "principalId" ], "type": "object" }, "LocalTokenLoginMethod": { "enum": [ "local_token" ], "type": "string" }, "LocalTokenSessionRequest": { "additionalProperties": false, "properties": { "accessToken": { "description": "256-bit local recovery token read from the mode-0600 first-run token file.", "maxLength": 64, "minLength": 64, "pattern": "^[0-9a-f]{64}$", "type": "string", "writeOnly": true }, "method": { "$ref": "#/components/schemas/LocalTokenLoginMethod" } }, "required": [ "method", "accessToken" ], "type": "object" }, "MaintenanceDeadLetters": { "properties": { "blobCleanup": { "format": "int64", "minimum": 0, "type": "integer" }, "orphanPublication": { "format": "int64", "minimum": 0, "type": "integer" }, "searchReadiness": { "format": "int64", "minimum": 0, "type": "integer" }, "searchRepair": { "format": "int64", "minimum": 0, "type": "integer" }, "storageCommitted": { "format": "int64", "minimum": 0, "type": "integer" }, "storagePrepared": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "searchReadiness", "searchRepair", "blobCleanup", "orphanPublication", "storagePrepared", "storageCommitted" ], "type": "object" }, "MaintenanceIntegrity": { "properties": { "activeStorageIntents": { "$ref": "#/components/schemas/ActiveStorageIntents" }, "deadLetters": { "$ref": "#/components/schemas/MaintenanceDeadLetters" }, "status": { "$ref": "#/components/schemas/ReadinessStatus" } }, "required": [ "status", "deadLetters", "activeStorageIntents" ], "type": "object" }, "MaterialDifference": { "additionalProperties": false, "properties": { "field": { "type": "string" }, "previousValue": {}, "proposedValue": {}, "publishedValue": {}, "userValuePreserved": { "type": "boolean" } }, "required": [ "field", "previousValue", "proposedValue", "publishedValue", "userValuePreserved" ], "type": "object" }, "MembershipInvitationObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^minv_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "MutationResponse": { "properties": { "result": { "$ref": "#/components/schemas/MutationResult" } }, "required": [ "result" ], "type": "object" }, "MutationResult": { "enum": [ "updated", "unchanged" ], "type": "string" }, "Notification": { "properties": { "batchId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/IntakeBatchObjectId" } ] }, "body": { "type": "string" }, "canonicalGeneration": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "category": { "$ref": "#/components/schemas/NotificationCategory" }, "cause": { "type": "string" }, "connectedBrowserEnabled": { "type": "boolean" }, "createdAtMs": { "format": "int64", "type": "integer" }, "dismissedAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "documentVersionId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentVersionObjectId" } ] }, "expiredAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "expiresAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "id": { "$ref": "#/components/schemas/NotificationObjectId" }, "initiatingPrincipalId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalObjectId" } ] }, "kind": { "$ref": "#/components/schemas/NotificationKind" }, "linkPath": { "type": "string" }, "presentationKey": { "type": "string" }, "readAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "severity": { "$ref": "#/components/schemas/NotificationSeverity" }, "sourceEventId": { "$ref": "#/components/schemas/EventObjectId" }, "sourceEventType": { "type": "string" }, "state": { "$ref": "#/components/schemas/NotificationState" }, "subjectId": { "$ref": "#/components/schemas/JianduObjectId" }, "subjectType": { "type": "string" }, "templateKey": { "type": "string" }, "title": { "type": "string" }, "updatedAtMs": { "format": "int64", "type": "integer" } }, "required": [ "id", "sourceEventId", "sourceEventType", "kind", "category", "severity", "subjectType", "subjectId", "documentVersionId", "canonicalGeneration", "cause", "initiatingPrincipalId", "batchId", "presentationKey", "templateKey", "title", "body", "linkPath", "state", "connectedBrowserEnabled", "readAtMs", "dismissedAtMs", "expiredAtMs", "expiresAtMs", "createdAtMs", "updatedAtMs" ], "type": "object" }, "NotificationBulkResponse": { "properties": { "unchanged": { "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" }, "updated": { "format": "int32", "maximum": 100, "minimum": 0, "type": "integer" } }, "required": [ "updated", "unchanged" ], "type": "object" }, "NotificationCapabilities": { "properties": { "changeFeed": { "$ref": "#/components/schemas/ChangeFeedCapability" }, "connectedBrowser": { "$ref": "#/components/schemas/ConnectedBrowserCapability" }, "inApp": { "$ref": "#/components/schemas/InboxCapability" }, "webPush": { "$ref": "#/components/schemas/WebPushCapability" } }, "required": [ "inApp", "connectedBrowser", "webPush", "changeFeed" ], "type": "object" }, "NotificationCategory": { "enum": [ "document_completion", "document_attention", "document_failure", "batch_summary", "plugin" ], "type": "string" }, "NotificationChange": { "properties": { "category": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NotificationCategory" } ] }, "channel": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NotificationChannel" } ] }, "createdAtMs": { "format": "int64", "type": "integer" }, "kind": { "$ref": "#/components/schemas/NotificationChangeKind" }, "notificationId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NotificationObjectId" } ] }, "sequence": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "sequence", "notificationId", "kind", "category", "channel", "createdAtMs" ], "type": "object" }, "NotificationChangeKind": { "enum": [ "created", "read", "dismissed", "expired", "preference_changed" ], "type": "string" }, "NotificationChangeObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^nchg_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "NotificationChannel": { "enum": [ "connected_browser", "web_push" ], "type": "string" }, "NotificationKind": { "enum": [ "document_ready", "document_needs_review", "document_processing_failed", "document_index_failed", "intake_batch_settled", "plugin_proposal" ], "type": "string" }, "NotificationList": { "properties": { "hasMore": { "type": "boolean" }, "items": { "items": { "$ref": "#/components/schemas/Notification" }, "maxItems": 100, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "items", "nextCursor", "hasMore" ], "type": "object" }, "NotificationObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^ntf_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "NotificationPreference": { "properties": { "category": { "$ref": "#/components/schemas/NotificationCategory" }, "channel": { "$ref": "#/components/schemas/NotificationChannel" }, "enabled": { "type": "boolean" }, "revision": { "format": "int64", "minimum": 0, "type": "integer" }, "supported": { "type": "boolean" }, "updatedAtMs": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "category", "channel", "enabled", "supported", "revision", "updatedAtMs" ], "type": "object" }, "NotificationPreferenceSnapshot": { "properties": { "items": { "items": { "$ref": "#/components/schemas/NotificationPreference" }, "maxItems": 8, "minItems": 8, "type": "array" }, "revision": { "type": "string" } }, "required": [ "items", "revision" ], "type": "object" }, "NotificationPreferenceUpdate": { "additionalProperties": false, "properties": { "category": { "$ref": "#/components/schemas/NotificationCategory" }, "channel": { "$ref": "#/components/schemas/NotificationChannel" }, "enabled": { "type": "boolean" } }, "required": [ "category", "channel", "enabled" ], "type": "object" }, "NotificationSeverity": { "enum": [ "info", "warning", "error" ], "type": "string" }, "NotificationState": { "enum": [ "unread", "read", "dismissed", "expired" ], "type": "string" }, "OidcProviderResponse": { "description": "Public presentation metadata for a configured OIDC sign-in adapter.", "properties": { "displayName": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "displayName" ], "type": "object" }, "OptionalEnrichment": { "description": "A privacy-safe, bounded view of the optional core capability selected by\nthe local household profile. Provider stderr, model paths, and other\ndiagnostics remain internal; this contract carries only persisted safe\nadvice intended for the household.", "properties": { "advisories": { "items": { "$ref": "#/components/schemas/OptionalEnrichmentAdvisory" }, "maxItems": 32, "type": "array" }, "textRecognition": { "$ref": "#/components/schemas/TextRecognitionState" } }, "required": [ "textRecognition", "advisories" ], "type": "object" }, "OptionalEnrichmentAdvisory": { "properties": { "code": { "description": "Stable, non-sensitive machine classification (for example,\n`ocr.unavailable`).", "type": "string" }, "message": { "description": "Bounded household-safe guidance, never provider diagnostics.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "OriginalDescriptor": { "properties": { "filename": { "type": "string" }, "mediaType": { "type": "string" }, "sizeBytes": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "filename", "mediaType", "sizeBytes" ], "type": "object" }, "OriginalDisposition": { "description": "How the original should be presented. Defaults to a forced download; a household viewing its\nown already-refused-if-dangerous original inline (e.g. a PDF in the document sheet) asks for\n`inline` explicitly.", "enum": [ "attachment", "inline" ], "type": "string" }, "PaperlessChecksumAlgorithmResponse": { "enum": [ "md5", "sha256" ], "type": "string" }, "PaperlessImportFailureResponse": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "phase": { "type": "string" } }, "required": [ "code", "message", "phase" ], "type": "object" }, "PaperlessImportFileRequest": { "additionalProperties": false, "properties": { "relativePath": { "description": "Relative POSIX path of 1 through 4096 UTF-8 bytes and at most 32\ncomponents. Absolute paths, backslashes, NUL, and dot segments are invalid.", "minLength": 1, "type": "string" }, "sizeBytes": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "relativePath", "sizeBytes" ], "type": "object" }, "PaperlessImportProgressResponse": { "properties": { "completed": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "determinate": { "type": "boolean" }, "total": { "format": "int64", "minimum": 0, "type": [ "integer", "null" ] }, "unit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaperlessProgressUnitResponse" } ] } }, "required": [ "determinate" ], "type": "object" }, "PaperlessImportStateResponse": { "enum": [ "uploading", "preflight_queued", "preflighting", "review_ready", "import_queued", "preparing", "importing", "applying_bulk", "verifying", "completed", "completed_with_skips", "failed", "canceled" ], "type": "string" }, "PaperlessImportStatusResponse": { "properties": { "bulkOperations": { "items": { "$ref": "#/components/schemas/BulkOrganizationAction" }, "type": "array" }, "bytesReceived": { "format": "int64", "minimum": 0, "type": "integer" }, "bytesTotal": { "format": "int64", "minimum": 0, "type": "integer" }, "createdAtMs": { "format": "int64", "type": "integer" }, "failure": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PaperlessImportFailureResponse" } ] }, "filesReceived": { "format": "int64", "minimum": 0, "type": "integer" }, "filesTotal": { "format": "int64", "minimum": 0, "type": "integer" }, "importId": { "$ref": "#/components/schemas/UploadObjectId" }, "migrationId": { "type": [ "string", "null" ] }, "preflight": { "type": [ "object", "null" ] }, "progress": { "$ref": "#/components/schemas/PaperlessImportProgressResponse" }, "restartInstructions": { "type": "string" }, "restartSafe": { "type": "boolean" }, "state": { "$ref": "#/components/schemas/PaperlessImportStateResponse" }, "updatedAtMs": { "format": "int64", "type": "integer" } }, "required": [ "importId", "state", "filesReceived", "filesTotal", "bytesReceived", "bytesTotal", "bulkOperations", "progress", "restartSafe", "restartInstructions", "createdAtMs", "updatedAtMs" ], "type": "object" }, "PaperlessProfileResponse": { "properties": { "browserUpload": { "type": "boolean" }, "earliestSourceVersion": { "type": "string" }, "exclusions": { "items": { "type": "string" }, "type": "array" }, "householdReplacementClaim": { "type": "boolean" }, "id": { "type": "string" }, "preserves": { "items": { "type": "string" }, "type": "array" }, "provisional": { "type": "boolean" }, "schemaVersion": { "format": "int32", "minimum": 0, "type": "integer" }, "sourceProduct": { "type": "string" }, "sourceShape": { "type": "string" }, "sourceVersion": { "type": "string" }, "sourceVersions": { "items": { "type": "string" }, "type": "array" }, "supportedDocumentMediaTypes": { "items": { "type": "string" }, "type": "array" }, "versionSegments": { "items": { "$ref": "#/components/schemas/PaperlessVersionSegmentResponse" }, "type": "array" } }, "required": [ "schemaVersion", "id", "sourceProduct", "sourceVersion", "earliestSourceVersion", "sourceVersions", "versionSegments", "sourceShape", "supportedDocumentMediaTypes", "preserves", "exclusions", "provisional", "householdReplacementClaim", "browserUpload" ], "type": "object" }, "PaperlessProgressUnitResponse": { "enum": [ "bytes", "documents", "operations" ], "type": "string" }, "PaperlessVersionSegmentResponse": { "properties": { "checksumAlgorithm": { "$ref": "#/components/schemas/PaperlessChecksumAlgorithmResponse" }, "commentsAsNotes": { "type": "boolean" }, "customFields": { "type": "boolean" }, "documentVersions": { "type": "boolean" }, "id": { "type": "string" }, "maximumVersion": { "type": "string" }, "minimumVersion": { "type": "string" }, "shareLinks": { "type": "boolean" }, "splitManifest": { "type": "boolean" }, "storagePaths": { "type": "boolean" }, "trashEntries": { "type": "boolean" }, "versionFile": { "type": [ "string", "null" ] } }, "required": [ "id", "minimumVersion", "maximumVersion", "checksumAlgorithm", "splitManifest", "storagePaths", "commentsAsNotes", "customFields", "shareLinks", "documentVersions", "trashEntries" ], "type": "object" }, "PasskeyCeremonyObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^pcer_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "PasskeyChallenge": { "properties": { "ceremonyId": { "pattern": "^pcer_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "options": {} }, "required": [ "ceremonyId", "options" ], "type": "object" }, "PasskeyCredentialObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^pkc_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "PasskeyListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PasskeyMetadata" }, "type": "array" } }, "required": [ "items" ], "type": "object" }, "PasskeyMetadata": { "properties": { "createdAtMs": { "format": "int64", "type": "integer" }, "id": { "pattern": "^pkc_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "label": { "type": "string" }, "lastUsedAtMs": { "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "label", "createdAtMs", "lastUsedAtMs" ], "type": "object" }, "PasswordLoginMethod": { "enum": [ "password" ], "type": "string" }, "PasswordSessionRequest": { "additionalProperties": false, "properties": { "method": { "$ref": "#/components/schemas/PasswordLoginMethod" }, "password": { "description": "Password containing 12 through 1024 UTF-8 bytes. The byte boundary is\ndescribed instead of using JSON Schema's character-counting length\nkeywords.", "type": "string", "writeOnly": true }, "username": { "maxLength": 64, "minLength": 3, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" } }, "required": [ "method", "username", "password" ], "type": "object" }, "PersonalAccessScope": { "description": "Explicit capability ceiling carried only by a personal access token.\nNormal sessions retain the principal's current RBAC permissions.", "enum": [ "read", "write", "share", "members" ], "type": "string" }, "PersonalAccessToken": { "description": "Safe metadata for an issued personal access token. Its bearer value is\nreturned separately only once from creation.", "properties": { "createdAtMs": { "format": "int64", "type": "integer" }, "expiresAtMs": { "format": "int64", "type": "integer" }, "id": { "pattern": "^pat_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "label": { "type": "string" }, "lastUsedAtMs": { "format": "int64", "type": [ "integer", "null" ] }, "scopes": { "items": { "$ref": "#/components/schemas/PersonalAccessScope" }, "type": "array" } }, "required": [ "id", "label", "scopes", "createdAtMs", "expiresAtMs", "lastUsedAtMs" ], "type": "object" }, "PersonalAccessTokenObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^pat_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "PluginCardFieldFormatResponse": { "enum": [ "text", "money", "date", "number", "boolean" ], "type": "string" }, "PluginCatalogItemResponse": { "properties": { "availableUpdate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PluginUpdatePreviewResponse" } ] }, "compatibility": { "$ref": "#/components/schemas/PluginCompatibilityResponse" }, "descriptorHealth": { "$ref": "#/components/schemas/PluginDescriptorHealthResponse" }, "id": { "type": "string" }, "name": { "type": "string" }, "revision": { "pattern": "^[0-9]+$", "type": "string" }, "rollbackAvailable": { "type": "boolean" }, "settingsRevision": { "pattern": "^[0-9]+$", "type": "string" }, "status": { "$ref": "#/components/schemas/PluginStatusResponse" }, "version": { "type": "string" } }, "required": [ "id", "name", "version", "status", "revision", "settingsRevision", "descriptorHealth", "compatibility", "rollbackAvailable" ], "type": "object" }, "PluginCatalogResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/PluginCatalogItemResponse" }, "maxItems": 128, "type": "array" } }, "required": [ "items" ], "type": "object" }, "PluginCommandDescriptorResponse": { "properties": { "confirmation": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "destructive": { "type": "boolean" }, "id": { "type": "string" }, "input": { "items": { "$ref": "#/components/schemas/PluginRecordFieldResponse" }, "maxItems": 32, "type": "array" }, "label": { "type": "string" }, "target": { "$ref": "#/components/schemas/PluginCommandTargetKindResponse" } }, "required": [ "id", "label", "target", "input", "destructive" ], "type": "object" }, "PluginCommandRunObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^pcmd_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "PluginCommandRunResponse": { "properties": { "commandId": { "type": "string" }, "createdAtMs": { "format": "int64", "type": "integer" }, "failureCode": { "type": [ "string", "null" ] }, "id": { "$ref": "#/components/schemas/PluginCommandRunObjectId" }, "pluginId": { "type": "string" }, "result": {}, "status": { "$ref": "#/components/schemas/PluginCommandRunStatusResponse" }, "target": { "$ref": "#/components/schemas/PluginCommandTargetResponse" }, "updatedAtMs": { "format": "int64", "type": "integer" } }, "required": [ "id", "pluginId", "commandId", "target", "status", "createdAtMs", "updatedAtMs" ], "type": "object" }, "PluginCommandRunStatusResponse": { "enum": [ "queued", "running", "completed", "failed", "canceled" ], "type": "string" }, "PluginCommandTargetKindResponse": { "enum": [ "document", "household" ], "type": "string" }, "PluginCommandTargetRequest": { "oneOf": [ { "properties": { "documentId": { "$ref": "#/components/schemas/DocumentObjectId" }, "kind": { "enum": [ "document" ], "type": "string" } }, "required": [ "documentId", "kind" ], "type": "object" }, { "properties": { "kind": { "enum": [ "household" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] }, "PluginCommandTargetResponse": { "oneOf": [ { "properties": { "documentId": { "$ref": "#/components/schemas/DocumentObjectId" }, "kind": { "enum": [ "document" ], "type": "string" } }, "required": [ "documentId", "kind" ], "type": "object" }, { "properties": { "kind": { "enum": [ "household" ], "type": "string" } }, "required": [ "kind" ], "type": "object" } ] }, "PluginCompatibilityResponse": { "properties": { "declaredContractRevision": { "type": "string" }, "hostContractRevision": { "type": "string" }, "maintenanceStatus": { "$ref": "#/components/schemas/PluginMaintenanceStatusResponse" }, "message": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/PluginCompatibilityStatusResponse" }, "testedThroughRevision": { "type": "string" } }, "required": [ "status", "maintenanceStatus", "hostContractRevision", "declaredContractRevision", "testedThroughRevision" ], "type": "object" }, "PluginCompatibilityStatusResponse": { "enum": [ "compatible", "failing", "stale", "deprecated", "unmaintained" ], "type": "string" }, "PluginContributionWarningCodeResponse": { "enum": [ "invalid_descriptor" ], "type": "string" }, "PluginContributionWarningResponse": { "properties": { "code": { "$ref": "#/components/schemas/PluginContributionWarningCodeResponse" }, "pluginId": { "type": "string" } }, "required": [ "pluginId", "code" ], "type": "object" }, "PluginDescriptorHealthResponse": { "enum": [ "ready", "invalid_descriptor" ], "type": "string" }, "PluginDescriptorResponse": { "allOf": [ { "properties": { "availableUpdate": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PluginUpdatePreviewResponse" } ] }, "compatibility": { "$ref": "#/components/schemas/PluginCompatibilityResponse" }, "descriptorHealth": { "$ref": "#/components/schemas/PluginDescriptorHealthResponse" }, "id": { "type": "string" }, "name": { "type": "string" }, "revision": { "pattern": "^[0-9]+$", "type": "string" }, "rollbackAvailable": { "type": "boolean" }, "settingsRevision": { "pattern": "^[0-9]+$", "type": "string" }, "status": { "$ref": "#/components/schemas/PluginStatusResponse" }, "version": { "type": "string" } }, "required": [ "id", "name", "version", "status", "revision", "settingsRevision", "descriptorHealth", "compatibility", "rollbackAvailable" ], "type": "object" }, { "properties": { "commands": { "items": { "$ref": "#/components/schemas/PluginCommandDescriptorResponse" }, "maxItems": 32, "type": "array" }, "settings": { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, "settingsDescriptor": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PluginSettingsDescriptorResponse" } ] } }, "required": [ "settings", "commands" ], "type": "object" } ] }, "PluginDocumentCardActionResponse": { "properties": { "commandId": { "type": "string" }, "confirmation": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "destructive": { "type": "boolean" }, "input": { "items": { "$ref": "#/components/schemas/PluginRecordFieldResponse" }, "maxItems": 32, "type": "array" }, "label": { "type": "string" } }, "required": [ "commandId", "label", "destructive", "input" ], "type": "object" }, "PluginDocumentCardFieldResponse": { "properties": { "currency": { "type": [ "string", "null" ] }, "fact": { "type": "string" }, "format": { "$ref": "#/components/schemas/PluginCardFieldFormatResponse" }, "label": { "type": "string" }, "value": {} }, "required": [ "fact", "label", "format", "value" ], "type": "object" }, "PluginDocumentCardResponse": { "properties": { "actions": { "items": { "$ref": "#/components/schemas/PluginDocumentCardActionResponse" }, "maxItems": 8, "type": "array" }, "fields": { "items": { "$ref": "#/components/schemas/PluginDocumentCardFieldResponse" }, "maxItems": 16, "type": "array" }, "id": { "type": "string" }, "pluginId": { "type": "string" }, "pluginName": { "type": "string" }, "pluginVersion": { "type": "string" }, "title": { "type": "string" } }, "required": [ "id", "pluginId", "pluginName", "pluginVersion", "title", "fields", "actions" ], "type": "object" }, "PluginDocumentContributionsResponse": { "properties": { "canonicalGeneration": { "type": "string" }, "cards": { "items": { "$ref": "#/components/schemas/PluginDocumentCardResponse" }, "maxItems": 4096, "type": "array" }, "documentId": { "$ref": "#/components/schemas/DocumentObjectId" }, "rendererRevision": { "format": "int32", "minimum": 0, "type": "integer" }, "warnings": { "items": { "$ref": "#/components/schemas/PluginContributionWarningResponse" }, "maxItems": 128, "type": "array" } }, "required": [ "rendererRevision", "documentId", "canonicalGeneration", "cards", "warnings" ], "type": "object" }, "PluginMaintenanceStatusResponse": { "enum": [ "unknown", "maintained", "unmaintained" ], "type": "string" }, "PluginNumberFormatResponse": { "enum": [ "number", "money" ], "type": "string" }, "PluginPermissionChangeKindResponse": { "enum": [ "added", "removed" ], "type": "string" }, "PluginPermissionChangeResponse": { "properties": { "capability": { "type": "string" }, "change": { "$ref": "#/components/schemas/PluginPermissionChangeKindResponse" } }, "required": [ "capability", "change" ], "type": "object" }, "PluginRecordFieldKindResponse": { "enum": [ "string", "number", "boolean", "document_id", "timestamp" ], "type": "string" }, "PluginRecordFieldResponse": { "properties": { "kind": { "$ref": "#/components/schemas/PluginRecordFieldKindResponse" }, "name": { "type": "string" }, "required": { "type": "boolean" } }, "required": [ "name", "kind", "required" ], "type": "object" }, "PluginRollbackModeResponse": { "enum": [ "package_only", "copy_on_write_state" ], "type": "string" }, "PluginSettingDescriptorResponse": { "properties": { "currency": { "type": [ "string", "null" ] }, "default": {}, "description": { "type": [ "string", "null" ] }, "format": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PluginNumberFormatResponse" } ] }, "key": { "type": "string" }, "kind": { "$ref": "#/components/schemas/PluginSettingKindResponse" }, "label": { "type": "string" }, "maxLength": { "format": "int32", "minimum": 0, "type": [ "integer", "null" ] }, "maximum": { "format": "double", "type": [ "number", "null" ] }, "minimum": { "format": "double", "type": [ "number", "null" ] }, "step": { "format": "double", "type": [ "number", "null" ] } }, "required": [ "key", "kind", "label", "default" ], "type": "object" }, "PluginSettingKindResponse": { "enum": [ "string", "number", "boolean" ], "type": "string" }, "PluginSettingsDescriptorResponse": { "properties": { "fields": { "items": { "$ref": "#/components/schemas/PluginSettingDescriptorResponse" }, "maxItems": 64, "type": "array" }, "schemaVersion": { "type": "string" } }, "required": [ "schemaVersion", "fields" ], "type": "object" }, "PluginStatusResponse": { "enum": [ "enabled", "disabled", "uninstalled", "quarantined" ], "type": "string" }, "PluginUpdatePreviewResponse": { "properties": { "automaticUpdateEligible": { "type": "boolean" }, "compatibility": { "$ref": "#/components/schemas/PluginCompatibilityResponse" }, "packageDigest": { "type": "string" }, "permissionChanges": { "items": { "$ref": "#/components/schemas/PluginPermissionChangeResponse" }, "maxItems": 11, "type": "array" }, "reasons": { "items": { "type": "string" }, "maxItems": 4, "type": "array" }, "reviewRequired": { "type": "boolean" }, "rollback": { "$ref": "#/components/schemas/PluginRollbackModeResponse" }, "stateMigrationRequired": { "type": "boolean" }, "stateSchemaAfter": { "type": [ "string", "null" ] }, "stateSchemaBefore": { "type": [ "string", "null" ] }, "version": { "type": "string" }, "versionChange": { "$ref": "#/components/schemas/PluginVersionChangeResponse" } }, "required": [ "version", "packageDigest", "versionChange", "compatibility", "permissionChanges", "stateMigrationRequired", "reviewRequired", "automaticUpdateEligible", "rollback", "reasons" ], "type": "object" }, "PluginVersionChangeResponse": { "enum": [ "patch", "minor", "major", "downgrade" ], "type": "string" }, "PreviewDescriptor": { "properties": { "available": { "type": "boolean" }, "mediaType": { "type": [ "string", "null" ] } }, "required": [ "available", "mediaType" ], "type": "object" }, "PrincipalObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^prn_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "ProblemDetails": { "description": "An RFC 9457 problem document.\n\nThe four registered members (`type`, `title`, `status`, `instance`) keep\ntheir specified names; the Jiandu extensions follow the native API's\ncamelCase convention, so `request_id` is published as `requestId`.", "properties": { "code": { "description": "Extension: the stable machine token for this problem class.", "maxLength": 64, "minLength": 1, "pattern": "^[a-z][a-z0-9_.]*$", "type": "string" }, "instance": { "description": "URI reference identifying this specific occurrence.", "example": "urn:uuid:0f2c9d24-6a6b-4f8b-9f5b-1a2c3d4e5f60", "type": "string" }, "requestId": { "description": "Extension: the identifier also returned in `X-Request-Id`.", "format": "uuid", "type": "string" }, "retry": { "$ref": "#/components/schemas/RetryGuidance", "description": "Extension: whether a retry can succeed." }, "status": { "description": "The HTTP status code, repeated for clients that only see the body.", "format": "int32", "maximum": 599, "minimum": 100, "type": "integer" }, "title": { "description": "Human-readable summary of the problem. Clients must branch on `code`,\nbecause this text may be localized.", "maxLength": 1024, "minLength": 1, "type": "string" }, "type": { "description": "URI identifying the problem type and dereferencing to the public\nproblem-code catalog. Clients still use `code` for dispatch.", "example": "https://jiandu.org/docs/references/problem-codes?code=intake.duplicate", "maxLength": 1024, "minLength": 1, "type": "string" } }, "required": [ "type", "title", "status", "instance", "code", "requestId", "retry" ], "type": "object" }, "ProcessingRunObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^run_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "ProjectionRetryReceiptResponse": { "properties": { "canonicalGeneration": { "format": "int64", "minimum": 0, "type": "integer" }, "documentId": { "$ref": "#/components/schemas/DocumentObjectId" }, "taskId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskObjectId" } ] } }, "required": [ "documentId", "canonicalGeneration", "taskId" ], "type": "object" }, "QueuePluginCommandRequest": { "additionalProperties": false, "properties": { "arguments": { "additionalProperties": true, "type": "object" }, "target": { "$ref": "#/components/schemas/PluginCommandTargetRequest" } }, "required": [ "target" ], "type": "object" }, "Readiness": { "properties": { "components": { "items": { "$ref": "#/components/schemas/ReadinessComponent" }, "maxItems": 2, "minItems": 2, "type": "array" }, "status": { "$ref": "#/components/schemas/ReadinessStatus" } }, "required": [ "status", "components" ], "type": "object" }, "ReadinessComponent": { "properties": { "name": { "$ref": "#/components/schemas/ReadinessComponentName" }, "requiredForReadiness": { "type": "boolean" }, "status": { "$ref": "#/components/schemas/ReadinessStatus" } }, "required": [ "name", "status", "requiredForReadiness" ], "type": "object" }, "ReadinessComponentName": { "enum": [ "database", "blob_storage" ], "type": "string" }, "ReadinessStatus": { "enum": [ "ok", "degraded", "unhealthy" ], "type": "string" }, "RecipientObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^rcp_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "ReprocessingDifferences": { "additionalProperties": false, "properties": { "differences": { "items": { "$ref": "#/components/schemas/MaterialDifference" }, "maxItems": 64, "type": "array" }, "documentId": { "type": "string" }, "fromGeneration": { "format": "int64", "minimum": 0, "type": "integer" }, "processingRunId": { "type": "string" }, "toGeneration": { "format": "int64", "minimum": 0, "type": "integer" }, "userFieldsPreserved": { "format": "int32", "minimum": 0, "type": "integer" } }, "required": [ "documentId", "processingRunId", "fromGeneration", "toGeneration", "userFieldsPreserved", "differences" ], "type": "object" }, "ReprocessingDisposition": { "enum": [ "created", "replayed", "coalesced" ], "type": "string" }, "ReprocessingReceipt": { "additionalProperties": false, "properties": { "canonicalGenerationRead": { "format": "int64", "minimum": 0, "type": "integer" }, "documentId": { "type": "string" }, "documentVersionId": { "type": "string" }, "processingRunId": { "type": "string" }, "taskId": { "type": "string" } }, "required": [ "documentId", "documentVersionId", "processingRunId", "taskId", "canonicalGenerationRead" ], "type": "object" }, "ReprocessingResponse": { "properties": { "disposition": { "$ref": "#/components/schemas/ReprocessingDisposition" }, "receipt": { "$ref": "#/components/schemas/ReprocessingReceipt" } }, "required": [ "disposition", "receipt" ], "type": "object" }, "RetryGuidance": { "enum": [ "do_not_retry", "retry_with_backoff" ], "type": "string" }, "ReviewStatus": { "enum": [ "not_required", "needs_review", "resolved" ], "type": "string" }, "Revision": { "description": "Canonical positive decimal optimistic-concurrency revision. The runtime accepts values from 1 through 18446744073709551615 (u64::MAX).", "maxLength": 20, "minLength": 1, "pattern": "^[1-9][0-9]{0,19}$", "type": "string" }, "ScanColorMode": { "enum": [ "color", "grayscale", "monochrome" ], "type": "string" }, "ScanFormat": { "enum": [ "pdf", "jpeg", "png" ], "type": "string" }, "ScanSettings": { "additionalProperties": false, "properties": { "colorMode": { "$ref": "#/components/schemas/ScanColorMode" }, "duplex": { "type": "boolean" }, "preferredFormat": { "$ref": "#/components/schemas/ScanFormat" }, "resolutionDpi": { "format": "int32", "minimum": 0, "type": "integer" }, "source": { "$ref": "#/components/schemas/ScanSource" } }, "required": [ "source", "colorMode", "resolutionDpi", "duplex", "preferredFormat" ], "type": "object" }, "ScanSource": { "enum": [ "platen", "adf" ], "type": "string" }, "ScannerCapabilities": { "properties": { "colorModes": { "items": { "$ref": "#/components/schemas/ScanColorMode" }, "type": "array" }, "duplex": { "type": "boolean" }, "formats": { "items": { "$ref": "#/components/schemas/ScanFormat" }, "type": "array" }, "resolutionsDpi": { "items": { "format": "int32", "minimum": 0, "type": "integer" }, "type": "array" }, "sources": { "items": { "$ref": "#/components/schemas/ScanSource" }, "type": "array" } }, "required": [ "sources", "colorModes", "resolutionsDpi", "formats", "duplex" ], "type": "object" }, "Session": { "properties": { "authenticated": { "type": "boolean" }, "authenticationMethod": { "$ref": "#/components/schemas/AuthenticationMethod" }, "expiresAtMs": { "format": "int64", "type": "integer" }, "permissions": { "items": { "type": "string" }, "type": "array" }, "principalId": { "pattern": "^prn_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "setup": { "$ref": "#/components/schemas/InstallationSetupResponse" } }, "required": [ "authenticated", "expiresAtMs", "authenticationMethod", "principalId", "permissions", "setup" ], "type": "object" }, "SetAuthorizationMembershipStateRequest": { "additionalProperties": false, "properties": { "state": { "$ref": "#/components/schemas/AuthorizationMembershipState" } }, "required": [ "state" ], "type": "object" }, "SingleIntakeForm": { "description": "Documentation-only shape of the `multipart/form-data` body: the real handler parses fields\nfrom `axum::extract::Multipart` directly rather than deserializing this type.", "properties": { "allowDuplicate": { "description": "When false, an existing identical original produces 409; when true, a distinct document\nmay reference identical bytes.", "type": "boolean" }, "file": { "$ref": "#/components/schemas/FilePart" } }, "required": [ "file", "allowDuplicate" ], "type": "object" }, "StartAdmissionPasskeyRegistrationRequest": { "additionalProperties": false, "properties": { "displayName": { "description": "Nonblank display name of at most 200 UTF-8 bytes, without control characters.", "minLength": 1, "type": "string" }, "invitationToken": { "maxLength": 256, "minLength": 1, "pattern": "^[A-Za-z0-9_-]+$", "type": "string", "writeOnly": true }, "label": { "description": "Nonblank passkey label of at most 128 UTF-8 bytes, without control characters.", "minLength": 1, "type": "string" }, "username": { "maxLength": 64, "minLength": 3, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" } }, "required": [ "invitationToken", "username", "displayName", "label" ], "type": "object" }, "StartMemberPasskeyRegistrationRequest": { "additionalProperties": false, "properties": { "label": { "description": "Nonblank passkey label of at most 128 UTF-8 bytes, without control characters.", "minLength": 1, "type": "string" }, "username": { "maxLength": 64, "minLength": 3, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" } }, "required": [ "username", "label" ], "type": "object" }, "StartPasskeyAuthenticationRequest": { "additionalProperties": false, "properties": { "username": { "maxLength": 64, "minLength": 3, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" } }, "required": [ "username" ], "type": "object" }, "Task": { "properties": { "documentId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentObjectId" } ] }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskErrorResponse" } ] }, "id": { "$ref": "#/components/schemas/TaskObjectId" }, "progress": { "format": "double", "maximum": 1, "minimum": 0, "type": "number" }, "state": { "$ref": "#/components/schemas/TaskState" } }, "required": [ "id", "state", "documentId", "progress", "error" ], "type": "object" }, "TaskErrorResponse": { "properties": { "code": { "maxLength": 64, "minLength": 1, "type": "string" }, "message": { "maxLength": 1024, "minLength": 1, "type": "string" }, "retryable": { "type": "boolean" }, "suggestedAction": { "maxLength": 512, "minLength": 1, "type": [ "string", "null" ] } }, "required": [ "code", "message", "retryable", "suggestedAction" ], "type": "object" }, "TaskObjectId": { "maxLength": 32, "minLength": 32, "pattern": "^task_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "TaskState": { "enum": [ "queued", "processing", "indexing", "needs_review", "ready", "ready_with_warnings", "failed", "canceled", "index_failed" ], "type": "string" }, "TextRecognitionState": { "enum": [ "pending", "not_needed", "complete", "needs_attention", "not_available" ], "type": "string" }, "TrustedProxyProviderResponse": { "properties": { "displayName": { "type": "string" }, "id": { "type": "string" } }, "required": [ "id", "displayName" ], "type": "object" }, "TrustedProxySignInRequest": { "additionalProperties": false, "properties": { "invitationToken": { "maxLength": 512, "pattern": "^[A-Za-z0-9_-]+$", "type": [ "string", "null" ], "writeOnly": true } }, "type": "object" }, "UnreadCountResponse": { "properties": { "count": { "format": "int64", "minimum": 0, "type": "integer" } }, "required": [ "count" ], "type": "object" }, "UpdateCaptureConnectorRequest": { "additionalProperties": false, "properties": { "displayName": { "description": "Single-line UTF-8 display name, limited to 80 encoded bytes at runtime.", "minLength": 1, "type": "string" }, "enabled": { "type": "boolean" }, "expectedRevision": { "description": "Canonical positive decimal optimistic revision returned by the prior\nread; accepted range is 1 through 18446744073709551615 (`u64::MAX`).", "maxLength": 20, "minLength": 1, "pattern": "^[1-9][0-9]{0,19}$", "type": "string" } }, "required": [ "displayName", "enabled", "expectedRevision" ], "type": "object" }, "UpdateConnectorRequest": { "additionalProperties": false, "properties": { "displayName": { "type": "string" }, "enabled": { "type": "boolean" }, "expectedRevision": { "type": "string" }, "mailboxQuery": { "type": [ "string", "null" ] }, "pollIntervalSeconds": { "format": "int32", "minimum": 0, "type": "integer" }, "tags": { "items": { "type": "string" }, "type": "array" }, "titleTemplate": { "type": [ "string", "null" ] } }, "required": [ "displayName", "pollIntervalSeconds", "enabled", "expectedRevision" ], "type": "object" }, "UpdateDocumentAccessPolicyRequest": { "additionalProperties": false, "description": "Explicitly change whether one document keeps the household's normal\nshared-library visibility or requires document-local grants.", "properties": { "policyManagerPrincipalId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrincipalObjectId", "description": "Required only when setting `visibility` to `restricted`. Omitting it\ndeliberately makes the caller the policy manager, avoiding a surprise\nhand-off to an arbitrary household member." } ] }, "visibility": { "$ref": "#/components/schemas/DocumentVisibility" } }, "required": [ "visibility", "policyManagerPrincipalId" ], "type": "object" }, "UpdateLocalPasswordRequest": { "additionalProperties": false, "properties": { "password": { "description": "Password containing 12 through 1024 UTF-8 bytes. The byte boundary is\ndescribed instead of using JSON Schema's character-counting length\nkeywords.", "type": "string", "writeOnly": true }, "username": { "maxLength": 64, "minLength": 3, "pattern": "^[A-Za-z0-9._-]+$", "type": "string" } }, "required": [ "username", "password" ], "type": "object" }, "UpdatePluginSettingsRequest": { "additionalProperties": false, "properties": { "values": { "additionalProperties": true, "type": "object" } }, "required": [ "values" ], "type": "object" }, "UpdatePreferencesRequest": { "additionalProperties": false, "properties": { "updates": { "items": { "$ref": "#/components/schemas/NotificationPreferenceUpdate" }, "maxItems": 8, "minItems": 1, "type": "array" } }, "required": [ "updates" ], "type": "object" }, "UploadFailureResponse": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean" } }, "required": [ "code", "message", "retryable" ], "type": "object" }, "UploadObjectId": { "maxLength": 31, "minLength": 31, "pattern": "^upl_0[0-7][0-9abcdefghjkmnpqrstvwxyz]{25}$", "type": "string" }, "UploadStatusResponse": { "properties": { "documentId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/DocumentObjectId" } ] }, "error": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/UploadFailureResponse" } ] }, "length": { "format": "int64", "minimum": 0, "type": "integer" }, "offset": { "format": "int64", "minimum": 0, "type": "integer" }, "state": { "type": "string" }, "taskId": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TaskObjectId" } ] }, "uploadId": { "$ref": "#/components/schemas/UploadObjectId" } }, "required": [ "uploadId", "state", "offset", "length" ], "type": "object" }, "Version": { "properties": { "apiVersion": { "type": "string" }, "applicationVersion": { "type": "string" }, "profile": { "type": "string" } }, "required": [ "applicationVersion", "apiVersion", "profile" ], "type": "object" }, "WebPushCapability": { "properties": { "reason": { "type": "string" }, "supported": { "type": "boolean" } }, "required": [ "supported", "reason" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "64 lowercase hexadecimal characters", "description": "Opaque 256-bit session credential or scoped personal access token; both are distinct from the first-run owner token.", "scheme": "bearer", "type": "http" }, "captureAgentAuth": { "description": "Narrow revocable outbound-agent credential using the `Jiandu-Capture ` scheme. It cannot authorize browser, document, member, or installation APIs.", "in": "header", "name": "Authorization", "type": "apiKey" }, "cookieAuth": { "description": "Opaque 256-bit session credential in the host-only HttpOnly SameSite=Strict cookie.", "in": "cookie", "name": "jiandu_session", "type": "apiKey" }, "sessionBearerAuth": { "bearerFormat": "64 lowercase hexadecimal characters", "description": "Opaque 256-bit ordinary session bearer. Credential-management operations accept this scheme but reject personal access tokens.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Native household document API served from the configured Jiandu origin. The safe default is loopback HTTP; supported household access uses HTTPS at a reviewed reverse proxy to a private Jiandu listener. Successful intake is asynchronous: a 202 response means the immutable original and durable work were accepted, not that extraction and indexing are complete.", "title": "Jiandu Native API", "version": "0.6.0.1" }, "openapi": "3.1.0", "paths": { "/api/v1/auth/identities": { "get": { "description": "Requires a normal authenticated session; personal access tokens are rejected. Returns provider ID, authentication method, and link time only; immutable external subjects are never disclosed.", "operationId": "listExternalIdentities", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExternalIdentityListResponse" } } }, "description": "Linked provider metadata; immutable external subjects are never disclosed", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List current-member external sign-in methods", "tags": [ "session" ] } }, "/api/v1/auth/identities/ldap/{provider_id}": { "post": { "description": "Requires a recent ordinary session and an exact same-origin proof for cookie requests. The LDAP password is verified against the configured TLS-protected directory, zeroized after use, and the verified identity is bound only to the current member.", "operationId": "linkLdapIdentity", "parameters": [ { "description": "Stable configured LDAP provider ID", "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LdapLinkRequest" } } }, "required": true }, "responses": { "204": { "description": "Directory identity linked", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "LDAP provider is disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Link a verified LDAP/AD credential to the current member", "tags": [ "session" ] } }, "/api/v1/auth/identities/oidc/{provider_id}/start": { "post": { "description": "Requires a normal authenticated session and a same-origin cookie request. The verified callback can only add a credential to that exact recently authenticated local account; it cannot admit a new account or issue a replacement session.", "operationId": "beginOidcIdentityLink", "parameters": [ { "description": "Stable configured OIDC provider ID", "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginOidcLoginResponse" } } }, "description": "Browser authorization URL and correlation cookie", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Set-Cookie": { "description": "Host-only HttpOnly OIDC correlation cookie", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "OIDC is disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "OIDC start capacity is busy; retry with backoff", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Begin an OIDC identity-linking ceremony", "tags": [ "session" ] } }, "/api/v1/auth/identities/trusted-proxy/{provider_id}": { "post": { "description": "Requires a recent ordinary session and an exact same-origin proof for cookie requests. Accepted only from a configured direct proxy peer supplying the deployment secret and bounded identity headers; the verified assertion is bound only to the current member.", "operationId": "linkTrustedProxyIdentity", "parameters": [ { "description": "Stable configured trusted-proxy provider ID", "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Proxy identity linked", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Trusted-proxy provider is disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Link the protected proxy assertion to the current member", "tags": [ "session" ] } }, "/api/v1/auth/identities/{provider_id}": { "delete": { "description": "Revokes every active session issued by the unlinked identity. The last interactive credential cannot be removed.", "operationId": "unlinkExternalIdentity", "parameters": [ { "description": "Stable configured authentication provider ID", "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Identity unlinked and its sessions revoked", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Unlink an external sign-in method after a recent sign-in", "tags": [ "session" ] } }, "/api/v1/auth/ldap/{provider_id}/session": { "post": { "description": "Requires same-origin JSON. The password is verified only against the configured TLS-protected directory and then zeroized. An unknown identity is admitted only through the provider's invitation or required-group policy before Jiandu issues its own opaque session.", "operationId": "createLdapSession", "parameters": [ { "description": "Stable configured LDAP provider ID", "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LdapSignInRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Opaque local browser session issued", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Set-Cookie": { "description": "Opaque host-only HttpOnly SameSite=Strict Jiandu session cookie", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "LDAP provider is disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Verify a TLS-protected LDAP/AD password and issue a local session", "tags": [ "session" ] } }, "/api/v1/auth/methods": { "get": { "description": "Unauthenticated discovery response. It exposes only local-method booleans and configured provider IDs and display names; issuer, client, admission-policy, group, and invitation details remain hidden.", "operationId": "getAuthenticationMethods", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthenticationMethodsResponse" } } }, "description": "Enabled browser authentication methods", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [], "summary": "Report enabled browser sign-in methods", "tags": [ "session" ] } }, "/api/v1/auth/oidc/{provider_id}/callback": { "get": { "description": "Consumes the one-use OIDC state and creates the normal opaque Jiandu session before redirecting to the application. Browser JavaScript never receives the provider token.", "operationId": "completeOidcLogin", "parameters": [ { "description": "Stable configured OIDC provider ID", "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } }, { "description": "Provider authorization code", "in": "query", "name": "code", "required": true, "schema": { "type": "string" } }, { "description": "One-use correlation state", "in": "query", "name": "state", "required": true, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Opaque Jiandu session issued and browser redirected", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Location": { "description": "Relative application or settings destination", "schema": { "type": "string" } }, "Set-Cookie": { "description": "One or more session-issuance and OIDC-state-expiration headers", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "OIDC is disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Complete the OIDC browser callback", "tags": [ "session" ] } }, "/api/v1/auth/oidc/{provider_id}/start": { "post": { "description": "Requires same-origin JSON. The result is an authorization URL and a short-lived host-only HttpOnly SameSite=Lax correlation cookie; no provider tokens are returned to browser JavaScript.", "operationId": "beginOidcLogin", "parameters": [ { "description": "Stable configured OIDC provider ID", "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginOidcLoginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginOidcLoginResponse" } } }, "description": "Browser authorization URL and correlation cookie", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Set-Cookie": { "description": "One or more host-only HttpOnly OIDC correlation-cookie headers", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "OIDC is disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The trusted connection peer or global OIDC start capacity is busy; retry with backoff", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Begin an OIDC authorization-code + PKCE browser flow", "tags": [ "session" ] } }, "/api/v1/auth/passkeys": { "get": { "description": "Requires a normal authenticated session; personal access tokens are rejected. Returns only Jiandu credential IDs, labels, and use timestamps, never public-key material or raw WebAuthn credential bytes.", "operationId": "listPasskeys", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyListResponse" } } }, "description": "Active passkeys", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Passkeys are disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List current-member passkey metadata", "tags": [ "session" ] } }, "/api/v1/auth/passkeys/authentication/finish": { "post": { "description": "Requires same-origin JSON and consumes the one-use server-side ceremony before verification. Success atomically advances the stored credential state and issues a host-only HttpOnly SameSite=Strict session cookie.", "operationId": "finishPasskeyAuthentication", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishPasskeyAuthenticationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Passkey session issued", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Set-Cookie": { "description": "Opaque host-only HttpOnly SameSite=Strict Jiandu session cookie", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Passkeys are disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Consume a passkey assertion and issue an opaque session", "tags": [ "session" ] } }, "/api/v1/auth/passkeys/authentication/start": { "post": { "description": "Requires same-origin JSON. Credential descriptors are padded and unknown usernames receive decoys; the one-use ceremony state remains server-side and expires after five minutes.", "operationId": "startPasskeyAuthentication", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartPasskeyAuthenticationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyChallenge" } } }, "description": "One-use WebAuthn request options", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Passkeys are disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Begin username-first passkey authentication", "tags": [ "session" ] } }, "/api/v1/auth/passkeys/registration/admission/finish": { "post": { "description": "Requires same-origin JSON. It consumes the one-use ceremony and atomically revalidates and consumes the invitation while creating the member, passkey, audit event, and opaque session; no raw invitation token is retained.", "operationId": "finishAdmissionPasskeyRegistration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishAdmissionPasskeyRegistrationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Passkey member admitted", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Set-Cookie": { "description": "Opaque host-only HttpOnly SameSite=Strict Jiandu session cookie", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Atomically consume an invitation, persist a passkey, and issue a session", "tags": [ "session" ] } }, "/api/v1/auth/passkeys/registration/admission/start": { "post": { "description": "Requires same-origin JSON. The invitation is validated without being consumed, then only its digest, the prospective member fields, and the one-use five-minute ceremony state are retained server-side.", "operationId": "startAdmissionPasskeyRegistration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartAdmissionPasskeyRegistrationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyChallenge" } } }, "description": "One-use WebAuthn creation options", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Begin invitation-backed passkey admission", "tags": [ "session" ] } }, "/api/v1/auth/passkeys/registration/member/finish": { "post": { "description": "Requires the same recent ordinary session and an exact same-origin proof for cookie requests. It consumes the one-use ceremony, verifies its member and session binding, and atomically persists the credential subject to username, freshness, and passkey-capacity checks.", "operationId": "finishMemberPasskeyRegistration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FinishMemberPasskeyRegistrationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyMetadata" } } }, "description": "Passkey enrolled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Verify and persist a passkey for the current member", "tags": [ "session" ] } }, "/api/v1/auth/passkeys/registration/member/start": { "post": { "description": "Requires a recent ordinary session and an exact same-origin proof for cookie requests. The five-minute one-use ceremony is bound to that member and session, normalized username, and label, and excludes already registered credentials.", "operationId": "startMemberPasskeyRegistration", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StartMemberPasskeyRegistrationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PasskeyChallenge" } } }, "description": "One-use WebAuthn creation options", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Begin passkey enrollment after a recent ordinary sign-in", "tags": [ "session" ] } }, "/api/v1/auth/passkeys/{credential_id}": { "delete": { "description": "Requires a recent ordinary session and an exact same-origin proof for cookie requests. Revocation is audited, revokes sessions issued by that credential, and cannot remove the last interactive credential; an Owner recovery path, local password, another passkey, or linked external identity must remain.", "operationId": "revokePasskey", "parameters": [ { "description": "Passkey credential ID", "in": "path", "name": "credential_id", "required": true, "schema": { "$ref": "#/components/schemas/PasskeyCredentialObjectId" } } ], "responses": { "204": { "description": "Passkey revoked", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Revoke one current-member passkey after a recent sign-in", "tags": [ "session" ] } }, "/api/v1/auth/trusted-proxy/{provider_id}/session": { "post": { "description": "Accepted only from a configured direct proxy peer supplying the deployment secret and bounded identity headers. Client-supplied identity headers alone are never authority.", "operationId": "createTrustedProxySession", "parameters": [ { "description": "Stable configured trusted-proxy provider ID", "in": "path", "name": "provider_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustedProxySignInRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Opaque local browser session issued", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Set-Cookie": { "description": "Opaque host-only HttpOnly SameSite=Strict Jiandu session cookie", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Trusted-proxy provider is disabled", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Exchange a protected reverse-proxy assertion for a local session", "tags": [ "session" ] } }, "/api/v1/authorization/groups": { "get": { "description": "Requires groups.manage. Groups grant nothing until a roles.manage actor explicitly binds a role to one.", "operationId": "listAuthorizationGroups", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AuthorizationGroupResponse" }, "type": "array" } } }, "description": "Bounded group directory", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List household authorization groups", "tags": [ "authorization" ] }, "post": { "description": "Requires groups.manage and an exact same-origin proof for cookie requests. A new group is inert until a separately authorized role binding is added.", "operationId": "createAuthorizationGroup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuthorizationGroupRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationGroupResponse" } } }, "description": "Authorization group created", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Create an unbound household authorization group", "tags": [ "authorization" ] } }, "/api/v1/authorization/groups/{group_id}/members/{principal_id}": { "delete": { "description": "Requires groups.manage and an exact same-origin proof for cookie requests. A removal may target a suspended member, allowing access cleanup after suspension.", "operationId": "removeAuthorizationGroupMember", "parameters": [ { "description": "Jiandu household group identifier.", "in": "path", "name": "group_id", "required": true, "schema": { "$ref": "#/components/schemas/AuthorizationGroupObjectId" } }, { "description": "Jiandu household principal identifier.", "in": "path", "name": "principal_id", "required": true, "schema": { "$ref": "#/components/schemas/PrincipalObjectId" } } ], "responses": { "204": { "description": "Member is absent from the group", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Remove a household member from a group", "tags": [ "authorization" ] }, "put": { "description": "Requires groups.manage and an exact same-origin proof for cookie requests. Before the add, the group's cumulative permissions must be a subset of the actor's effective permissions.", "operationId": "addAuthorizationGroupMember", "parameters": [ { "description": "Jiandu household group identifier.", "in": "path", "name": "group_id", "required": true, "schema": { "$ref": "#/components/schemas/AuthorizationGroupObjectId" } }, { "description": "Jiandu household principal identifier.", "in": "path", "name": "principal_id", "required": true, "schema": { "$ref": "#/components/schemas/PrincipalObjectId" } } ], "responses": { "204": { "description": "Member is in the group", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Add an active household member to a group", "tags": [ "authorization" ] } }, "/api/v1/authorization/groups/{group_id}/roles/{role_id}": { "delete": { "description": "Requires roles.manage and an exact same-origin proof for cookie requests.", "operationId": "unbindAuthorizationRoleFromGroup", "parameters": [ { "description": "Jiandu household group identifier.", "in": "path", "name": "group_id", "required": true, "schema": { "$ref": "#/components/schemas/AuthorizationGroupObjectId" } }, { "description": "Built-in or local custom role identifier.", "in": "path", "name": "role_id", "required": true, "schema": { "$ref": "#/components/schemas/AuthorizationRoleObjectId" } } ], "responses": { "204": { "description": "Role binding is absent", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Remove a role binding from a household group", "tags": [ "authorization" ] }, "put": { "description": "Requires roles.manage and an exact same-origin proof for cookie requests. The actor may bind only a role whose complete permission set they already possess.", "operationId": "bindAuthorizationRoleToGroup", "parameters": [ { "description": "Jiandu household group identifier.", "in": "path", "name": "group_id", "required": true, "schema": { "$ref": "#/components/schemas/AuthorizationGroupObjectId" } }, { "description": "Built-in or local custom role identifier.", "in": "path", "name": "role_id", "required": true, "schema": { "$ref": "#/components/schemas/AuthorizationRoleObjectId" } } ], "responses": { "204": { "description": "Role is bound to the group", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Bind a role to a household group", "tags": [ "authorization" ] } }, "/api/v1/authorization/members": { "get": { "description": "Requires members.read. It returns local display names, opaque principal identifiers, and access state only; external identity claims and invitation credentials are never exposed.", "operationId": "listAuthorizationMembers", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AuthorizationMemberResponse" }, "type": "array" } } }, "description": "Bounded member directory", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "List the bounded household member directory", "tags": [ "authorization" ] } }, "/api/v1/authorization/members/{principal_id}/roles/{role_id}": { "delete": { "description": "Requires roles.manage and an exact same-origin proof for cookie requests. A removal may target a suspended member, allowing access cleanup after suspension.", "operationId": "unbindAuthorizationRoleFromMember", "parameters": [ { "description": "Jiandu household principal identifier.", "in": "path", "name": "principal_id", "required": true, "schema": { "$ref": "#/components/schemas/PrincipalObjectId" } }, { "description": "Built-in or local custom role identifier.", "in": "path", "name": "role_id", "required": true, "schema": { "$ref": "#/components/schemas/AuthorizationRoleObjectId" } } ], "responses": { "204": { "description": "Role binding is absent", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Remove a direct role binding from a household member", "tags": [ "authorization" ] }, "put": { "description": "Requires roles.manage and an exact same-origin proof for cookie requests. The actor may assign only a role whose complete permission set is already a subset of the actor's effective permissions.", "operationId": "bindAuthorizationRoleToMember", "parameters": [ { "description": "Jiandu household principal identifier.", "in": "path", "name": "principal_id", "required": true, "schema": { "$ref": "#/components/schemas/PrincipalObjectId" } }, { "description": "Built-in or local custom role identifier.", "in": "path", "name": "role_id", "required": true, "schema": { "$ref": "#/components/schemas/AuthorizationRoleObjectId" } } ], "responses": { "204": { "description": "Role is bound to the member", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Bind a role directly to an active household member", "tags": [ "authorization" ] } }, "/api/v1/authorization/members/{principal_id}/state": { "put": { "description": "Requires members.manage and an exact same-origin proof for cookie requests. The installation owner is protected from state changes through this endpoint so the break-glass local owner remains active.", "operationId": "setAuthorizationMembershipState", "parameters": [ { "description": "Jiandu household principal identifier.", "in": "path", "name": "principal_id", "required": true, "schema": { "$ref": "#/components/schemas/PrincipalObjectId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetAuthorizationMembershipStateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationMembershipStateResponse" } } }, "description": "Member access state changed", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Suspend or reactivate a household member", "tags": [ "authorization" ] } }, "/api/v1/authorization/permissions": { "get": { "description": "Requires roles.manage. The returned codes are application-owned; custom roles cannot introduce a new code that has no server-side enforcement point.", "operationId": "listAuthorizationPermissions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationPermissionCatalogResponse" } } }, "description": "Explicit permission codes allowed in a custom role", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List the fixed permission vocabulary for custom roles", "tags": [ "authorization" ] } }, "/api/v1/authorization/roles": { "get": { "description": "Requires roles.manage. Built-in roles are immutable; custom-role permissions remain explicit and local to this household.", "operationId": "listAuthorizationRoles", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AuthorizationRoleResponse" }, "type": "array" } } }, "description": "Bounded role directory", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List built-in and household custom roles", "tags": [ "authorization" ] }, "post": { "description": "Requires roles.manage and an exact same-origin proof for cookie requests. Every requested permission must be one the acting member already has; built-in roles remain immutable.", "operationId": "createAuthorizationRole", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAuthorizationRoleRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationRoleResponse" } } }, "description": "Custom role created", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Create a household custom role", "tags": [ "authorization" ] } }, "/api/v1/capture-agent/capabilities": { "put": { "description": "Requires the narrow Jiandu-Capture device credential. Replaces the validated capability list, updates last-seen time, and advances the agent revision; the credential cannot access household APIs.", "operationId": "updateCaptureAgentCapabilities", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentCapabilitiesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureAgentResponse" } } }, "description": "Validated capabilities replaced and agent revision advanced", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "captureAgentAuth": [] } ], "summary": "Replace an enrolled capture agent's device capabilities", "tags": [ "capture agent" ] } }, "/api/v1/capture-agent/enroll": { "post": { "description": "Consumes an unexpired enrollment code without a prior session and returns the new agent ID, configured lease duration, and narrow device credential once. Jiandu stores only credential digests.", "operationId": "enrollCaptureAgent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEnrollmentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentEnrollmentResponse" } } }, "description": "Agent enrolled; the narrow credential is returned only once", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Enroll a capture agent with a one-use code", "tags": [ "capture agent" ] } }, "/api/v1/capture-agent/jobs/claim": { "post": { "description": "Requires the narrow device credential. Returns one matching job and a new lease token, or 204 when no work is queued; expired uncanceled leases are requeued and only the new token's digest is stored.", "operationId": "claimCaptureAgentJob", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentJobLeaseResponse" } } }, "description": "Matching job claimed with a newly issued lease token", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "204": { "description": "No matching queued work is available", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "captureAgentAuth": [] } ], "summary": "Claim the next queued job for this capture agent", "tags": [ "capture agent" ] } }, "/api/v1/capture-agent/jobs/{job_id}/failure": { "post": { "description": "Requires the narrow device credential and current lease token. Records one server-defined scan_failed, assembly_failed, or local_storage_failed reason, clears the lease, and returns the terminal job without accepting agent-supplied error text.", "operationId": "reportCaptureAgentJobFailure", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureJobObjectId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentFailureRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureJobResponse" } } }, "description": "Terminal failure recorded and lease cleared", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "captureAgentAuth": [] } ], "summary": "Fail a leased capture-agent job safely", "tags": [ "capture agent" ] } }, "/api/v1/capture-agent/jobs/{job_id}/heartbeat": { "post": { "description": "Requires the narrow device credential plus the current lease token. Extends the lease and records scanning or uploading; a stale lease conflicts and a durable cancellation request stops the job.", "operationId": "heartbeatCaptureAgentJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureJobObjectId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentHeartbeatRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureJobResponse" } } }, "description": "Lease renewed and reported progress stored", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "captureAgentAuth": [] } ], "summary": "Renew a capture-agent job lease and report progress", "tags": [ "capture agent" ] } }, "/api/v1/capture-agent/jobs/{job_id}/upload": { "post": { "description": "Requires the narrow device credential and current job lease. Validates and binds the filename, media type, nonzero length, and lowercase full-file SHA-256, then creates or recovers the job's private upload session.", "operationId": "beginCaptureAgentUpload", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureJobObjectId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BeginAgentUploadRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUploadResponse" } } }, "description": "Upload session created or recovered for the leased job", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "captureAgentAuth": [] } ], "summary": "Create or recover a resumable capture-agent upload", "tags": [ "capture agent" ] } }, "/api/v1/capture-agent/jobs/{job_id}/uploads/{upload_id}": { "get": { "description": "Requires the narrow device credential and current job lease. Renews the lease and returns the bound upload's identifier, durable offset, declared length, and lifecycle state.", "operationId": "getCaptureAgentUpload", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureJobObjectId" } }, { "in": "path", "name": "upload_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "in": "header", "name": "Capture-Lease", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentUploadResponse" } } }, "description": "Bound upload transfer and lifecycle status", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "captureAgentAuth": [] } ], "summary": "Read capture-agent upload status", "tags": [ "capture agent" ] }, "head": { "description": "Requires the narrow device credential and current job lease. Renews the lease and returns Upload-Offset and Upload-Length on 204 without a response body.", "operationId": "headCaptureAgentUpload", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureJobObjectId" } }, { "in": "path", "name": "upload_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "in": "header", "name": "Capture-Lease", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Durable upload offset and declared length", "headers": { "Upload-Length": { "description": "Declared total byte length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Upload-Offset": { "description": "Current durable byte offset", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "captureAgentAuth": [] } ], "summary": "Read a capture-agent upload's durable offset headers", "tags": [ "capture agent" ] }, "patch": { "description": "Requires the narrow device credential, current lease, application/offset+octet-stream body, exact Upload-Offset, and SHA-256 Upload-Checksum. Each accepted chunk renews the lease; a checksum mismatch returns 460, and completing the transfer attaches it to the job for durable finalization.", "operationId": "appendCaptureAgentUpload", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureJobObjectId" } }, { "in": "path", "name": "upload_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "in": "header", "name": "Capture-Lease", "required": true, "schema": { "type": "string" } }, { "in": "header", "name": "Upload-Offset", "required": true, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "in": "header", "name": "Upload-Checksum", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/offset+octet-stream": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } } }, "required": true }, "responses": { "204": { "description": "Chunk stored durably and upload offset advanced", "headers": { "Upload-Length": { "description": "Declared total byte length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Upload-Offset": { "description": "Next durable byte offset", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "415": { "$ref": "#/components/responses/UnsupportedMediaTypeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "460": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Chunk checksum mismatch", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "captureAgentAuth": [] } ], "summary": "Append a checksummed capture-agent upload chunk", "tags": [ "capture agent" ] } }, "/api/v1/capture/agent-enrollments": { "post": { "description": "Requires connectors.manage and same-origin checks for cookie requests. The requested lifetime must be 60 seconds through 24 hours; the raw code is returned only in this 201 response and Jiandu stores only its digest.", "operationId": "createCaptureAgentEnrollment", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEnrollmentRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResponse" } } }, "description": "One-use enrollment code returned once", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Create a one-use capture-agent enrollment code", "tags": [ "capture" ] } }, "/api/v1/capture/agents": { "get": { "description": "Requires connectors.manage. Returns each household agent's advertised devices, revocation state, last-seen time, and optimistic revision; narrow credentials are never returned.", "operationId": "listCaptureAgents", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureAgentListResponse" } } }, "description": "Enrolled household capture-agent directory", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List enrolled household capture agents", "tags": [ "capture" ] } }, "/api/v1/capture/agents/{agent_id}/revoke": { "post": { "description": "Requires connectors.manage, same-origin checks for cookie requests, and the current expectedRevision. Revocation invalidates the device credential and cancels every nonterminal job assigned to that agent.", "operationId": "revokeCaptureAgent", "parameters": [ { "in": "path", "name": "agent_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureAgentObjectId" } }, { "description": "Canonical decimal text returned by the prior read; accepted range is 1 through 18446744073709551615", "in": "query", "name": "expectedRevision", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureAgentResponse" } } }, "description": "Revoked agent and advanced revision", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Revoke a capture agent at an expected revision", "tags": [ "capture" ] } }, "/api/v1/capture/connectors": { "get": { "description": "Requires connectors.manage. Returns each household-scoped connector's fixed source, enabled state, revision, and most recent success time or safe error code.", "operationId": "listCaptureConnectors", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureConnectorListResponse" } } }, "description": "Household capture connector directory", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List household capture connectors", "tags": [ "capture" ] }, "post": { "description": "Requires connectors.manage and same-origin checks for cookie requests. The source must name an operator-configured eSCL endpoint or a safe existing directory within an allowlisted watch root.", "operationId": "createCaptureConnector", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCaptureConnectorRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureConnectorResponse" } } }, "description": "Capture connector created", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Create a watch-folder or eSCL capture connector", "tags": [ "capture" ] } }, "/api/v1/capture/connectors/{connector_id}": { "delete": { "description": "Requires connectors.manage, same-origin checks for cookie requests, and the current expectedRevision; stale revisions return 409.", "operationId": "deleteCaptureConnector", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureConnectorObjectId" } }, { "description": "Canonical decimal text returned by the prior read; accepted range is 1 through 18446744073709551615", "in": "query", "name": "expectedRevision", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } } ], "responses": { "204": { "description": "Connector deleted at the supplied revision", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Delete a capture connector at an expected revision", "tags": [ "capture" ] }, "put": { "description": "Requires connectors.manage, same-origin checks for cookie requests, and the current expectedRevision. The connector's source cannot be changed by this operation.", "operationId": "updateCaptureConnector", "parameters": [ { "in": "path", "name": "connector_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureConnectorObjectId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCaptureConnectorRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureConnectorResponse" } } }, "description": "Updated connector with its new revision", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Update a capture connector's name and enabled state", "tags": [ "capture" ] } }, "/api/v1/capture/escl/{endpoint_id}/capabilities": { "get": { "description": "Requires connectors.manage. Jiandu resolves only the named operator-configured endpoint, returns 404 when it is unknown, and returns 503 when the capture service or scanner probe is unavailable.", "operationId": "getEsclCapabilities", "parameters": [ { "in": "path", "name": "endpoint_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScannerCapabilities" } } }, "description": "Current capabilities reported by the configured scanner", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Probe one configured eSCL scanner's capabilities", "tags": [ "capture" ] } }, "/api/v1/capture/jobs": { "get": { "description": "Requires connectors.manage. Returns the household's bounded capture ledger, including target, state, cancellation flag, revision, durable upload/document/task identifiers, and safe terminal failure details.", "operationId": "listCaptureJobs", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureJobListResponse" } } }, "description": "Household capture-job ledger", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List household capture jobs", "tags": [ "capture" ] }, "post": { "description": "Requires connectors.manage and same-origin checks for cookie requests. Jiandu validates the configured eSCL endpoint or active agent device and its advertised capabilities, then returns the durable queued job with 202.", "operationId": "createCaptureJob", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCaptureJobRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureJobResponse" } } }, "description": "Durable capture job accepted in queued state", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Queue an eSCL or capture-agent scan job", "tags": [ "capture" ] } }, "/api/v1/capture/jobs/{job_id}/cancel": { "post": { "description": "Requires connectors.manage, same-origin checks for cookie requests, and the current expectedRevision. Queued or leased work is canceled immediately; active scanning or uploading records a cooperative cancellation request, while a terminal job at the supplied revision is returned unchanged.", "operationId": "cancelCaptureJob", "parameters": [ { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/CaptureJobObjectId" } }, { "description": "Canonical decimal text returned by the prior read; accepted range is 1 through 18446744073709551615", "in": "query", "name": "expectedRevision", "required": true, "schema": { "$ref": "#/components/schemas/Revision" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureJobResponse" } } }, "description": "Current job after applying or retaining cancellation state", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Cancel a capture job optimistically", "tags": [ "capture" ] } }, "/api/v1/capture/options": { "get": { "description": "Requires connectors.manage. Returns the identifiers and display names of operator-allowlisted watch roots and fixed eSCL endpoints; it does not probe scanner capabilities.", "operationId": "listCaptureOptions", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaptureOptionsResponse" } } }, "description": "Configured capture source identifiers and display names", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List configured capture source options", "tags": [ "capture" ] } }, "/api/v1/connectors/email": { "get": { "description": "Requires connectors.manage. Returns household-scoped configuration, polling health, authorization state, and revisions; sealed mailbox credentials never cross the API boundary.", "operationId": "listEmailConnectors", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorListResponse" } } }, "description": "Configured connectors", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List the household's email ingest connectors", "tags": [ "connectors" ] }, "post": { "description": "The connector is created disabled and unauthorized. Authorize its mailbox before it will poll.", "operationId": "createEmailConnector", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateConnectorRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResponse" } } }, "description": "Connector created", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Configure a new email ingest connector", "tags": [ "connectors" ] } }, "/api/v1/connectors/email/callback": { "get": { "description": "Exchanges the authorization code for a refresh token, seals it, and stores it against the connector. The token never appears in the response.", "operationId": "completeEmailConnectorAuthorization", "parameters": [ { "description": "Authorization code returned after provider consent.", "in": "query", "name": "code", "required": false, "schema": { "type": "string" } }, { "description": "Opaque, single-use state created when authorization began.", "in": "query", "name": "state", "required": false, "schema": { "type": "string" } }, { "description": "Provider-defined indication that consent did not complete.", "in": "query", "name": "error", "required": false, "schema": { "type": "string" } } ], "responses": { "303": { "description": "Redirect back to connector settings", "headers": { "Location": { "description": "Relative connector-settings result URL", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Provider consent callback", "tags": [ "connectors" ] } }, "/api/v1/connectors/email/{connector_id}": { "delete": { "description": "Requires connectors.manage, an exact same-origin proof for cookie requests, and the observed revision. Deletion is atomic and removes the connector together with its sealed mailbox credential; stale revisions conflict.", "operationId": "deleteEmailConnector", "parameters": [ { "description": "Connector identity", "in": "path", "name": "connector_id", "required": true, "schema": { "$ref": "#/components/schemas/EmailConnectorObjectId" } }, { "description": "Revision the caller observed", "in": "query", "name": "expected_revision", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Connector removed", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Remove an email ingest connector and its stored credential", "tags": [ "connectors" ] }, "get": { "description": "Requires connectors.manage and household scope. Unknown or foreign connector IDs return 404, and the sealed refresh token is never returned.", "operationId": "getEmailConnector", "parameters": [ { "description": "Connector identity", "in": "path", "name": "connector_id", "required": true, "schema": { "$ref": "#/components/schemas/EmailConnectorObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResponse" } } }, "description": "Connector", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Read one email ingest connector", "tags": [ "connectors" ] }, "patch": { "description": "Requires connectors.manage, an exact same-origin proof for cookie requests, and the observed expectedRevision. The complete settings update is atomic; stale revisions conflict and the sealed mailbox credential remains server-side.", "operationId": "updateEmailConnector", "parameters": [ { "description": "Connector identity", "in": "path", "name": "connector_id", "required": true, "schema": { "$ref": "#/components/schemas/EmailConnectorObjectId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateConnectorRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorResponse" } } }, "description": "Updated connector", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Change an email ingest connector's settings", "tags": [ "connectors" ] } }, "/api/v1/connectors/email/{connector_id}/authorize": { "post": { "description": "Returns the provider consent URL. Requires a configured connector OAuth client and a public HTTPS origin.", "operationId": "beginEmailConnectorAuthorization", "parameters": [ { "description": "Connector identity", "in": "path", "name": "connector_id", "required": true, "schema": { "$ref": "#/components/schemas/EmailConnectorObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizationStartResponse" } } }, "description": "Consent URL", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Start the provider consent flow for a connector's mailbox", "tags": [ "connectors" ] } }, "/api/v1/diagnostics/frontend-logs": { "post": { "description": "Operator-only same-origin endpoint. It accepts at most 64 closed-vocabulary browser records and re-emits them into the existing local JSON log stream; it does not retain an additional browser-log database or artifact. Records may carry only a canonical W3C traceparent to preserve their originating UI-operation trace. Browser timestamps, messages, errors, URLs, identifiers, and arbitrary attributes are rejected.", "operationId": "ingestFrontendDiagnosticLogs", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FrontendLogBatch" } } }, "required": true }, "responses": { "204": { "description": "All records were validated and emitted into the bounded local log pipeline", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The bounded diagnostics log pipeline is busy; retry with backoff", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Add privacy-bounded browser records to the local structured diagnostic log stream", "tags": [ "diagnostics" ] } }, "/api/v1/documents": { "get": { "description": "Filters and the opaque keyset cursor are bound together. Full-text search uses the current canonical search projection; direct detail and original access remain available when an index warning is reported.", "operationId": "listDocuments", "parameters": [ { "description": "Optional search text of at most 256 UTF-8 bytes; control characters\nother than tab and line breaks are rejected.", "in": "query", "name": "query", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "state", "required": false, "schema": { "$ref": "#/components/schemas/DocumentState" } }, { "in": "query", "name": "review", "required": false, "schema": { "$ref": "#/components/schemas/ReviewStatus" } }, { "in": "query", "name": "lifecycle", "required": false, "schema": { "$ref": "#/components/schemas/DocumentLifecycle" } }, { "in": "query", "name": "needs_details", "required": false, "schema": { "type": "boolean" } }, { "description": "Repeat for up to 64 unique, nonempty tags. Each tag is at most 256\nUTF-8 bytes and contains no control characters.", "in": "query", "name": "tag", "required": false, "schema": { "items": { "type": "string" }, "maxItems": 64, "type": "array" } }, { "description": "Exact correspondent facet, nonempty and at most 1024 UTF-8 bytes\nwithout control characters.", "in": "query", "name": "correspondent", "required": false, "schema": { "type": "string" } }, { "description": "Exact document-type facet, nonempty and at most 1024 UTF-8 bytes\nwithout control characters.", "in": "query", "name": "document_type", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "document_year", "required": false, "schema": { "format": "int32", "maximum": 9999, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "sort", "required": false, "schema": { "$ref": "#/components/schemas/DocumentSort" } }, { "description": "Opaque nonempty page cursor of at most 512 UTF-8 bytes without control characters.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentList" } } }, "description": "A household-scoped keyset page", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Search and browse household documents", "tags": [ "documents" ] }, "post": { "description": "The Idempotency-Key is scoped to the authenticated household member. Repeating the same key and semantic request returns the original documentId and taskId; reusing it for different content returns 409. By default, an already-ingested checksum returns 409 unless allowDuplicate is true. A 202 response means durable acceptance only; poll the returned taskId.", "operationId": "createDocument", "parameters": [ { "description": "Caller-generated command identity. It may be safely retried only with the same semantic request and authenticated scope.", "example": "01k3q8r6m7-document-0001", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/SingleIntakeForm" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "documentId": "doc_010000000000000000000000000", "duplicateOf": null, "taskId": "task_010000000000000000000000000" }, "schema": { "$ref": "#/components/schemas/DocumentIntakeAccepted" } } }, "description": "Original and processing task durably accepted, or an identical idempotent request replayed", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "415": { "$ref": "#/components/responses/UnsupportedMediaTypeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Validate an immutable original and enqueue its core processing", "tags": [ "intake" ] } }, "/api/v1/documents/bulk/organize": { "post": { "description": "One to one hundred unique document/revision pairs are preflighted in the authenticated household before any new canonical generation is written. A stale or invalid target rolls back the entire request.", "operationId": "bulkOrganizeDocuments", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOrganizeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkOrganizeResponse" } } }, "description": "Updated document details in request order", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Apply one organization action atomically", "tags": [ "documents" ] } }, "/api/v1/documents/{document_id}": { "delete": { "description": "Shared blobs and externally referenced derived data are protected. Physical blob candidates remain subject to a reference recheck.", "operationId": "permanentlyDeleteDocument", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "description": "Exactly one strong decimal ETag returned by document detail. Wildcards and weak validators are rejected.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "The scoped trashed document graph was deleted", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Permanently delete one explicitly trashed document", "tags": [ "documents" ] }, "get": { "description": "Requires documents.read and the current document ACL. Unknown and unauthorized identifiers are indistinguishable; the response includes canonical detail and history with a strong revision ETag.", "operationId": "getDocument", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } } }, "description": "Canonical detail, provenance, history, and safe use descriptors", "headers": { "ETag": { "description": "Strong decimal revision required by document mutations", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read authorized document detail", "tags": [ "documents" ] }, "patch": { "description": "Requires documents.update, document-local edit access, an exact same-origin proof for cookie requests, and the current strong ETag. A successful patch publishes a new canonical generation; immutable original bytes are never rewritten.", "operationId": "correctDocument", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "description": "Exactly one strong decimal ETag returned by document detail. Wildcards and weak validators are rejected.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CorrectDocumentRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } } }, "description": "Corrected canonical generation", "headers": { "ETag": { "description": "Strong decimal revision of the corrected generation", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Publish authoritative household corrections", "tags": [ "documents" ] } }, "/api/v1/documents/{document_id}/access": { "get": { "description": "Requires documents.share, PAT share when applicable, and a current document-local manager grant for restricted documents. The installation owner retains a non-removable recovery manager path.", "operationId": "getDocumentAccess", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAccessSnapshot" } } }, "description": "Policy and audit-safe grant metadata", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Inspect a document's explicit access policy and grants", "tags": [ "document access" ] }, "put": { "description": "Requires documents.share, a current document-local manager grant, a browser same-origin proof for cookie requests, and PAT share when applicable. Restricting creates a durable owner-recovery manager grant and a designated active policy manager grant atomically.", "operationId": "updateDocumentAccessPolicy", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } } ], "requestBody": { "content": { "application/json": { "example": { "policyManagerPrincipalId": "prn_010000000000000000000000000", "visibility": "restricted" }, "schema": { "$ref": "#/components/schemas/UpdateDocumentAccessPolicyRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAccessSnapshot" } } }, "description": "Updated policy and grant snapshot", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Restrict a document or return it to shared-library visibility", "tags": [ "document access" ] } }, "/api/v1/documents/{document_id}/access/grants": { "post": { "description": "Requires documents.share, a current document-local manager grant, a restricted policy, active direct recipients or a group with an active member, and PAT share when applicable. Grant changes are durably audited.", "operationId": "createDocumentAccessGrant", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } } ], "requestBody": { "content": { "application/json": { "example": { "expiresAtMs": null, "role": "viewer", "subjectId": "prn_010000000000000000000000000", "subjectKind": "principal" }, "schema": { "$ref": "#/components/schemas/CreateDocumentAccessGrantRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAccessSnapshot" } } }, "description": "Updated policy and grant snapshot", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Grant document-local viewer, editor, or manager access", "tags": [ "document access" ] } }, "/api/v1/documents/{document_id}/access/grants/{grant_id}": { "delete": { "description": "Requires documents.share, a current document-local manager grant, a same-origin browser proof for cookie requests, and PAT share when applicable. The immutable installation-owner recovery grant is deliberately not revocable.", "operationId": "revokeDocumentAccessGrant", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "description": "Document-local principal or group grant identifier.", "in": "path", "name": "grant_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentAccessGrantObjectId" } }, { "in": "query", "name": "subjectKind", "required": true, "schema": { "$ref": "#/components/schemas/DocumentGrantSubjectKind" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAccessSnapshot" } } }, "description": "Updated policy and grant snapshot", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Revoke one document-local direct or group grant", "tags": [ "document access" ] } }, "/api/v1/documents/{document_id}/archive": { "post": { "description": "Requires documents.archive, document-local edit access, an exact same-origin proof for cookie requests, and the current strong ETag. Only an active document can transition to archived.", "operationId": "archiveDocument", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "description": "Exactly one strong decimal ETag returned by document detail. Wildcards and weak validators are rejected.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } } }, "description": "Updated lifecycle state", "headers": { "ETag": { "description": "Strong decimal revision after the transition", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Archive a document", "tags": [ "documents" ] } }, "/api/v1/documents/{document_id}/original": { "get": { "description": "Defaults to a forced download. Passing `disposition=inline` asks the browser to render the same authenticated, already-refused-if-dangerous bytes in place instead, for a household previewing its own document.", "operationId": "downloadDocumentOriginal", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "in": "query", "name": "disposition", "required": false, "schema": { "$ref": "#/components/schemas/OriginalDisposition" } } ], "responses": { "200": { "content": { "application/pdf": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } }, "image/jpeg": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } }, "image/png": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } }, "text/plain": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } } }, "description": "Body with verified length and SHA-256, as an attachment or inline per `disposition`", "headers": { "Content-Disposition": { "description": "Safe attachment or inline filename disposition", "schema": { "type": "string" } }, "Content-Length": { "description": "Verified original length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Content-Type": { "description": "Verified admitted media type", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read an integrity-checked immutable original", "tags": [ "documents" ] } }, "/api/v1/documents/{document_id}/plugin-contributions": { "get": { "description": "Requires documents.read and the normal document ACL. A malformed or disabled plugin cannot make core document detail unavailable.", "operationId": "getDocumentPluginContributions", "parameters": [ { "description": "Household-scoped document identifier", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginDocumentContributionsResponse" } } }, "description": "Client-neutral current-generation plugin cards", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Resolve portable plugin cards for one authorized document", "tags": [ "plugins" ] } }, "/api/v1/documents/{document_id}/preview": { "get": { "description": "Only UTF-8 plain text or an explicitly registered integrity-checked AVIF/JPEG/PNG/WebP artifact is returned. Active PDF, HTML, and SVG are never embedded.", "operationId": "getDocumentPreview", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } } ], "responses": { "200": { "content": { "image/avif": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } }, "image/jpeg": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } }, "image/png": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } }, "image/webp": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } }, "text/plain": { "schema": { "type": "string" } } }, "description": "Safe text or raster preview (text/plain, image/avif, image/jpeg, image/png, or image/webp)", "headers": { "Content-Length": { "description": "Preview byte length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Content-Type": { "description": "Safe preview media type", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "204": { "description": "No supported safe preview is available", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read a bounded safe derived preview", "tags": [ "documents" ] } }, "/api/v1/documents/{document_id}/reprocess": { "post": { "description": "The current canonical generation remains authoritative until the new run publishes N+1. Repeating the same scoped Idempotency-Key returns the same receipt; a compatible active run may be coalesced.", "operationId": "reprocessDocument", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "description": "Exactly one strong decimal ETag returned by document detail. Wildcards and weak validators are rejected.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } }, { "description": "Caller-generated command identity. It may be safely retried only with the same semantic request and authenticated scope.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReprocessingResponse" } } }, "description": "Created, replayed, or coalesced durable run", "headers": { "Location": { "description": "Relative URL of the durable task", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum polling delay in seconds", "schema": { "format": "int32", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Queue a new durable core processing run", "tags": [ "documents" ] } }, "/api/v1/documents/{document_id}/restore": { "post": { "description": "Requires document-local edit access, an exact same-origin proof for cookie requests, and the current strong ETag. Restoring an archived document requires documents.archive; restoring a trashed document requires documents.trash and returns it to its saved active or archived state.", "operationId": "restoreDocument", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "description": "Exactly one strong decimal ETag returned by document detail. Wildcards and weak validators are rejected.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } } }, "description": "Updated lifecycle state", "headers": { "ETag": { "description": "Strong decimal revision after the transition", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Restore a trashed or archived document", "tags": [ "documents" ] } }, "/api/v1/documents/{document_id}/search/retry": { "post": { "description": "The authorized, same-origin recovery command is fenced by the current strong document revision. It keeps the canonical generation and original directly available while a durable projection job retries.", "operationId": "retryDocumentSearch", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "description": "Exactly one strong decimal ETag returned by document detail. Wildcards and weak validators are rejected.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectionRetryReceiptResponse" } } }, "description": "The durable search retry was queued", "headers": { "Location": { "description": "Relative URL of the queued task, or the document when no task was needed", "schema": { "type": "string" } }, "Retry-After": { "description": "Minimum polling delay in seconds", "schema": { "format": "int32", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Retry the latest terminally failed search projection", "tags": [ "documents" ] } }, "/api/v1/documents/{document_id}/trash": { "post": { "description": "Requires documents.trash, document-local edit access, an exact same-origin proof for cookie requests, and the current strong ETag. Active and archived documents may enter trash, and their prior lifecycle is retained for restoration.", "operationId": "trashDocument", "parameters": [ { "description": "Household-scoped document identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "document_id", "required": true, "schema": { "$ref": "#/components/schemas/DocumentObjectId" } }, { "description": "Exactly one strong decimal ETag returned by document detail. Wildcards and weak validators are rejected.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentDetail" } } }, "description": "Updated lifecycle state", "headers": { "ETag": { "description": "Strong decimal revision after the transition", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Move a document to recoverable trash", "tags": [ "documents" ] } }, "/api/v1/health": { "get": { "description": "Compatibility probe using the same bounded database and fixed blob-storage directory checks as /api/v1/health/ready. Optional subsystems and archive integrity are not consulted; failures use the legacy generic unavailable envelope.", "operationId": "getHealth", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyHealth" } } }, "description": "Core dependencies are ready", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Report core readiness and component health", "tags": [ "system" ] } }, "/api/v1/health/integrity": { "post": { "description": "Operator-only, single-flight diagnostic. It is never a liveness or readiness probe and must not be called automatically. A completed diagnostic returns 200 even when its findings are degraded or unhealthy.", "operationId": "runIntegrityDiagnostic", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrityReport" } } }, "description": "The diagnostic completed; inspect the fixed-shape status and bounded counts", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Another integrity diagnostic is already running; retry later", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Run an explicit expensive archive integrity diagnostic", "tags": [ "system" ] } }, "/api/v1/health/live": { "get": { "description": "This constant-cost probe does not access the database, filesystem, queues, workers, or clock.", "operationId": "getLiveness", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LivenessResponse" } } }, "description": "The process can serve HTTP requests", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [], "summary": "Report process liveness without consulting dependencies", "tags": [ "system" ] } }, "/api/v1/health/ready": { "get": { "description": "Checks only the database connection and fixed blob-storage directory identities. Optional recovery and projection work does not make the whole archive unavailable.", "operationId": "getReadiness", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } }, "description": "Required dependencies are ready", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } }, "description": "One or more required dependencies are unavailable", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } } }, "security": [], "summary": "Report bounded required-dependency readiness", "tags": [ "system" ] } }, "/api/v1/intake-batches": { "post": { "description": "Files are processed and returned in request order. The batch envelope and item identities are durable, so repeating an identical ordered request with the same Idempotency-Key resumes or replays it. A changed filename, order, or content under that key returns 409. An intake rejection has null documentId/taskId plus a bounded error. A durable acceptance always preserves non-null documentId/taskId; while processing is active its error is null, and if processing later exhausts retries the replay preserves both IDs alongside the bounded error so clients recover the existing document rather than uploading it again.", "operationId": "createIntakeBatch", "parameters": [ { "description": "Caller-generated command identity. It may be safely retried only with the same semantic request and authenticated scope.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/BatchIntakeForm" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchIntakeResponse" } } }, "description": "Every batch item has an accepted or rejected intake result", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Validate two to one hundred originals as a durable intake batch", "tags": [ "intake" ] } }, "/api/v1/learning": { "get": { "description": "Requires documents.read. Suggestions, previews, rule counts, and audit activity are filtered through the caller's current document visibility; inaccessible and foreign-household records are never distinguishable.", "operationId": "getLearningSnapshot", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSnapshot" } } }, "description": "Bounded household learning snapshot with the strong aggregate revision ETag required by mutations", "headers": { "ETag": { "description": "Strong aggregate learning revision", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read learning settings, suggestions, rules, and recent audit activity", "tags": [ "learning" ] } }, "/api/v1/learning/export": { "get": { "description": "Requires metadata.manage. The bounded JSON export includes only observations and applications backed by documents the caller can currently read; audit entries contain no document identifiers or learned values.", "operationId": "exportLearningData", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningExport" } } }, "description": "Privacy-scoped JSON learning export", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Export the caller-visible household learning data", "tags": [ "learning" ] } }, "/api/v1/learning/reset": { "post": { "description": "Requires metadata.manage and an exact same-origin proof for cookie requests. The operation removes observations, suggestions, rules, and application history, then restores default balanced settings. Existing document metadata is not rewritten.", "operationId": "resetLearningData", "parameters": [ { "description": "Exactly one strong aggregate learning revision returned by the latest snapshot or mutation.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyLearningCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningResetResult" } } }, "description": "Reset counts and restored default settings", "headers": { "ETag": { "description": "Strong aggregate learning revision after reset", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Reset household learning data and preferences", "tags": [ "learning" ] } }, "/api/v1/learning/rules/{rule_id}/disable": { "post": { "description": "Requires metadata.manage and an exact same-origin proof for cookie requests. Disabling preserves the rule and its application history.", "operationId": "disableLearningRule", "parameters": [ { "description": "Household-scoped rule identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "rule_id", "required": true, "schema": { "$ref": "#/components/schemas/LearningRuleObjectId" } }, { "description": "Exactly one strong aggregate learning revision returned by the latest snapshot or mutation.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyLearningCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSnapshot" } } }, "description": "Coherent learning snapshot after disabling the rule", "headers": { "ETag": { "description": "Strong aggregate learning revision after the mutation", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Disable an active learning rule", "tags": [ "learning" ] } }, "/api/v1/learning/rules/{rule_id}/enable": { "post": { "description": "Requires metadata.manage and an exact same-origin proof for cookie requests. Enabling an active rule is idempotent; an undone rule is terminal.", "operationId": "enableLearningRule", "parameters": [ { "description": "Household-scoped rule identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "rule_id", "required": true, "schema": { "$ref": "#/components/schemas/LearningRuleObjectId" } }, { "description": "Exactly one strong aggregate learning revision returned by the latest snapshot or mutation.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyLearningCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSnapshot" } } }, "description": "Coherent learning snapshot after enabling the rule", "headers": { "ETag": { "description": "Strong aggregate learning revision after the mutation", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Enable a disabled learning rule", "tags": [ "learning" ] } }, "/api/v1/learning/rules/{rule_id}/undo": { "post": { "description": "Requires metadata.manage and an exact same-origin proof for cookie requests. Undo prevents future applications but does not rewrite document metadata already filed by the rule.", "operationId": "undoLearningRule", "parameters": [ { "description": "Household-scoped rule identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "rule_id", "required": true, "schema": { "$ref": "#/components/schemas/LearningRuleObjectId" } }, { "description": "Exactly one strong aggregate learning revision returned by the latest snapshot or mutation.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyLearningCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSnapshot" } } }, "description": "Coherent learning snapshot after undoing the rule", "headers": { "ETag": { "description": "Strong aggregate learning revision after the mutation", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Permanently undo a learning rule", "tags": [ "learning" ] } }, "/api/v1/learning/settings": { "patch": { "description": "Requires metadata.manage and an exact same-origin proof for cookie requests. Omitted fields remain unchanged; an empty patch is rejected.", "operationId": "updateLearningSettings", "parameters": [ { "description": "Exactly one strong decimal ETag returned by the learning snapshot or the previous settings update.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSettingsPatch" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSettings" } } }, "description": "Updated learning settings with a new strong ETag", "headers": { "ETag": { "description": "Strong aggregate learning revision after the update", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Update learning settings optimistically", "tags": [ "learning" ] } }, "/api/v1/learning/suggestions/{suggestion_id}/accept": { "post": { "description": "Requires metadata.manage and an exact same-origin proof for cookie requests. Acceptance creates one active rule atomically and is idempotent for an already accepted suggestion.", "operationId": "acceptLearningSuggestion", "parameters": [ { "description": "Household-scoped suggestion identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "suggestion_id", "required": true, "schema": { "$ref": "#/components/schemas/LearningSuggestionObjectId" } }, { "description": "Exactly one strong aggregate learning revision returned by the latest snapshot or mutation.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyLearningCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSnapshot" } } }, "description": "Coherent learning snapshot after acceptance", "headers": { "ETag": { "description": "Strong aggregate learning revision after the mutation", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Accept a pending learning suggestion", "tags": [ "learning" ] } }, "/api/v1/learning/suggestions/{suggestion_id}/reject": { "post": { "description": "Requires metadata.manage and an exact same-origin proof for cookie requests. Rejection is idempotent and prevents new evidence from silently restoring the suggestion.", "operationId": "rejectLearningSuggestion", "parameters": [ { "description": "Household-scoped suggestion identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "suggestion_id", "required": true, "schema": { "$ref": "#/components/schemas/LearningSuggestionObjectId" } }, { "description": "Exactly one strong aggregate learning revision returned by the latest snapshot or mutation.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyLearningCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSnapshot" } } }, "description": "Coherent learning snapshot after rejection", "headers": { "ETag": { "description": "Strong aggregate learning revision after the mutation", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Reject a pending learning suggestion", "tags": [ "learning" ] } }, "/api/v1/learning/suggestions/{suggestion_id}/restore": { "post": { "description": "Requires metadata.manage and an exact same-origin proof for cookie requests. Accepted suggestions remain fenced by their rules and cannot be restored.", "operationId": "restoreLearningSuggestion", "parameters": [ { "description": "Household-scoped suggestion identifier. Unknown and out-of-scope identifiers are indistinguishable.", "in": "path", "name": "suggestion_id", "required": true, "schema": { "$ref": "#/components/schemas/LearningSuggestionObjectId" } }, { "description": "Exactly one strong aggregate learning revision returned by the latest snapshot or mutation.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmptyLearningCommand" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LearningSnapshot" } } }, "description": "Coherent learning snapshot after restoration", "headers": { "ETag": { "description": "Strong aggregate learning revision after the mutation", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Restore a rejected learning suggestion", "tags": [ "learning" ] } }, "/api/v1/members/invitations": { "post": { "description": "Requires members.manage and an exact same-origin proof for cookie requests. The raw invitation token is returned only in this 201 response; Jiandu stores only a domain-separated verifier. The requested role must be an existing household role and may not grant any permission the creator lacks.", "operationId": "createMembershipInvitation", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMembershipInvitationRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMembershipInvitationResponse" } } }, "description": "One-use invitation created; copy its raw token now", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Create a one-use household membership invitation", "tags": [ "members" ] } }, "/api/v1/members/invitations/{invitation_id}": { "delete": { "description": "Requires members.manage and an exact same-origin ordinary browser session. Revocation is idempotent and permanently prevents future redemption.", "operationId": "revokeMembershipInvitation", "parameters": [ { "in": "path", "name": "invitation_id", "required": true, "schema": { "$ref": "#/components/schemas/MembershipInvitationObjectId" } } ], "responses": { "204": { "description": "Invitation revoked or already revoked", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Invitation not found", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "409": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Invitation was already consumed", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Revoke an unconsumed household membership invitation", "tags": [ "members" ] } }, "/api/v1/members/local-accounts": { "post": { "description": "Requires members.manage, same-origin proof for cookie requests, and a normal session rather than a personal access token. The new principal is always kind USER; the selected existing household role is assigned by the authorization service.", "operationId": "createLocalPasswordAccount", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateLocalPasswordAccountRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LocalPasswordAccountResponse" } } }, "description": "Local account created", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Create a local username/password household account", "tags": [ "members" ] } }, "/api/v1/members/{principal_id}/local-password": { "put": { "description": "A member may update an existing local credential. Only the installation Owner may recover another local USER credential or establish the first local password for an OIDC-only member. Password changes revoke that principal's sessions and personal access tokens. Personal access tokens cannot call this route.", "operationId": "updateLocalPassword", "parameters": [ { "description": "Jiandu household principal identifier.", "in": "path", "name": "principal_id", "required": true, "schema": { "$ref": "#/components/schemas/PrincipalObjectId" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateLocalPasswordRequest" } } }, "required": true }, "responses": { "204": { "description": "Credential changed and prior credentials invalidated", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Set a local account username and password", "tags": [ "members" ] } }, "/api/v1/notification-capabilities": { "get": { "description": "Requires notifications.read. In-app inbox delivery is mandatory; connected-browser foreground delivery plus polling and SSE are supported, while background delivery and Web Push are explicitly unavailable.", "operationId": "getNotificationCapabilities", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationCapabilities" } } }, "description": "Selected profile capabilities; same-origin SSE and polling are available while Web Push is explicitly unsupported", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Describe inbox and browser-delivery support", "tags": [ "notifications" ] } }, "/api/v1/notification-preferences": { "get": { "description": "Requires notifications.read. Returns the complete recipient category and channel matrix, including support flags, plus its deterministic revision in both the body and a strong ETag.", "operationId": "getNotificationPreferences", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferenceSnapshot" } } }, "description": "Preference snapshot", "headers": { "ETag": { "description": "Strong preference-matrix revision", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read the complete category/channel preference matrix", "tags": [ "notifications" ] }, "patch": { "description": "Requires notifications.manage, an exact same-origin proof for cookie requests, and the current strong ETag. One to eight unique category and channel updates apply atomically; omitted pairs remain unchanged and Web Push cannot be enabled.", "operationId": "updateNotificationPreferences", "parameters": [ { "description": "Exactly one strong SHA-256 ETag returned with the complete preference snapshot.", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePreferencesRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationPreferenceSnapshot" } } }, "description": "Updated preference snapshot", "headers": { "ETag": { "description": "Strong preference-matrix revision after the update", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Update category/channel preferences optimistically", "tags": [ "notifications" ] } }, "/api/v1/notifications": { "get": { "description": "Requires notifications.read. Results are scoped to the current recipient and current subject access; opaque keyset cursors are bound to that recipient and every active filter.", "operationId": "listNotifications", "parameters": [ { "in": "query", "name": "state", "required": false, "schema": { "$ref": "#/components/schemas/NotificationState" } }, { "in": "query", "name": "kind", "required": false, "schema": { "$ref": "#/components/schemas/NotificationKind" } }, { "in": "query", "name": "severity", "required": false, "schema": { "$ref": "#/components/schemas/NotificationSeverity" } }, { "in": "query", "name": "createdAfterMs", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "in": "query", "name": "createdBeforeMs", "required": false, "schema": { "format": "int64", "type": "integer" } }, { "description": "Opaque nonempty page cursor of at most 512 UTF-8 bytes without control characters.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationList" } } }, "description": "Recipient-scoped keyset page", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "List the recipient's durable notification inbox", "tags": [ "notifications" ] } }, "/api/v1/notifications/bulk/dismiss": { "post": { "description": "Requires notifications.manage and an exact same-origin proof for cookie requests. One to one hundred unique recipient-scoped identifiers are handled atomically and idempotently; any unknown or inaccessible identifier rolls back the complete request.", "operationId": "bulkDismissNotifications", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkMutationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationBulkResponse" } } }, "description": "Atomic idempotent mutation counts", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Dismiss selected notifications", "tags": [ "notifications" ] } }, "/api/v1/notifications/bulk/read": { "post": { "description": "Requires notifications.manage and an exact same-origin proof for cookie requests. One to one hundred unique recipient-scoped identifiers are handled atomically and idempotently; any unknown or inaccessible identifier rolls back the complete request.", "operationId": "bulkReadNotifications", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkMutationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotificationBulkResponse" } } }, "description": "Atomic idempotent mutation counts", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Mark selected notifications read", "tags": [ "notifications" ] } }, "/api/v1/notifications/changes": { "get": { "description": "Use tail=true without cursor/limit on first connection to suppress historical presentation. Expired cursors return resyncRequired=true.", "operationId": "getNotificationChanges", "parameters": [ { "description": "Opaque nonempty change cursor of at most 512 UTF-8 bytes without control characters.", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "format": "int32", "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "tail", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangeFeedResponse" } } }, "description": "Ordered durable changes or an explicit resynchronization instruction", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Poll a resumable recipient-scoped notification change feed", "tags": [ "notifications" ] } }, "/api/v1/notifications/stream": { "get": { "description": "Authenticate with the same-origin HttpOnly cookie or an ordinary Authorization bearer session on fetch; credentials never belong in the URL. Personal access tokens use the polling endpoints instead, because this stream continually revalidates a rotating session without retaining a raw bearer. Supply a cursor in at most one of the cursor query parameter or Last-Event-ID header. With no cursor the stream starts at the current tail and emits ready. Each notification_changes event contains at most 50 ordered changes and its id is the next durable cursor. Missing retained history emits resync_required and closes. The server sends keepalive comments, revalidates authorization, limits concurrent streams, and relies on client polling as a lossless fallback.", "operationId": "streamNotificationChanges", "parameters": [ { "description": "Opaque bounded resume cursor; mutually exclusive with Last-Event-ID", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } }, { "description": "Opaque bounded resume cursor; mutually exclusive with cursor", "in": "header", "name": "Last-Event-ID", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "content": { "text/event-stream": { "schema": { "type": "string" } } }, "description": "SSE stream using 15-second keepalive comments and a 3-second reconnect hint", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "429": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The bounded stream concurrency budget is exhausted; poll with backoff", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Stream recipient-scoped durable notification changes", "tags": [ "notifications" ] } }, "/api/v1/notifications/unread-count": { "get": { "description": "Requires notifications.read. Counts only unread notifications still visible to the current recipient under current subject access.", "operationId": "getUnreadNotificationCount", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnreadCountResponse" } } }, "description": "Unread count", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Count unread durable notifications", "tags": [ "notifications" ] } }, "/api/v1/notifications/{notification_id}": { "get": { "description": "Requires notifications.read. Lookup is restricted to the current recipient and current subject access; unknown, inaccessible, and other-recipient identifiers are indistinguishable.", "operationId": "getNotification", "parameters": [ { "description": "Recipient-scoped durable notification identifier.", "in": "path", "name": "notification_id", "required": true, "schema": { "$ref": "#/components/schemas/NotificationObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Notification" } } }, "description": "Generic host-owned notification presentation", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read one recipient-scoped notification", "tags": [ "notifications" ] } }, "/api/v1/notifications/{notification_id}/dismiss": { "post": { "description": "Requires notifications.manage and an exact same-origin proof for cookie requests. The recipient-scoped command is idempotent: only unread or read notifications change, while terminal states return unchanged.", "operationId": "dismissNotification", "parameters": [ { "description": "Recipient-scoped durable notification identifier.", "in": "path", "name": "notification_id", "required": true, "schema": { "$ref": "#/components/schemas/NotificationObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } }, "description": "Updated or unchanged", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Dismiss one notification", "tags": [ "notifications" ] } }, "/api/v1/notifications/{notification_id}/read": { "post": { "description": "Requires notifications.manage and an exact same-origin proof for cookie requests. The recipient-scoped command is idempotent: a notification not currently unread returns unchanged, while an unknown or inaccessible identifier returns 404.", "operationId": "markNotificationRead", "parameters": [ { "description": "Recipient-scoped durable notification identifier.", "in": "path", "name": "notification_id", "required": true, "schema": { "$ref": "#/components/schemas/NotificationObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MutationResponse" } } }, "description": "Updated or unchanged", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Mark one notification read", "tags": [ "notifications" ] } }, "/api/v1/openapi.json": { "get": { "description": "Unauthenticated deterministic OpenAPI 3.1 document generated from the native server annotations for this running build.", "operationId": "getNativeOpenApi", "responses": { "200": { "content": { "application/json": { "schema": {} } }, "description": "This deterministic OpenAPI 3.1 document", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [], "summary": "Return this generated native API contract", "tags": [ "system" ] } }, "/api/v1/paperless-imports": { "post": { "description": "The idempotency key is bound to the sorted relative-path/length manifest and exact ordered bulk operations. Files are uploaded separately in checksummed bounded chunks.", "operationId": "createPaperlessImport", "parameters": [ { "description": "Stable browser command identity", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaperlessImportRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperlessImportStatusResponse" } } }, "description": "Upload created or idempotently recovered", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Create or recover a restart-safe browser export upload", "tags": [ "migration" ] } }, "/api/v1/paperless-imports/current": { "get": { "description": "Requires migration.manage and household scope. Returns the most recently created browser workflow, including terminal states, or 204 when the household has no workflow.", "operationId": "getCurrentPaperlessImport", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperlessImportStatusResponse" } } }, "description": "Latest workflow", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "204": { "description": "No browser migration has been created", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Recover the household's latest browser migration workflow", "tags": [ "migration" ] } }, "/api/v1/paperless-imports/profile": { "get": { "description": "Requires migration.manage. Returns the provisional compatibility matrix for an already-extracted Paperless export, including supported version segments, checksums, preserved data, and explicit exclusions; it does not claim whole-household replacement.", "operationId": "getPaperlessImportProfile", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperlessProfileResponse" } } }, "description": "Supported source profiles", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "501": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The configured persistence backend does not implement this provisional profile", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Describe the supported Paperless export profiles and explicit losses", "tags": [ "migration" ] } }, "/api/v1/paperless-imports/{import_id}": { "get": { "description": "Requires migration.manage and exact household scope. Returns the durable workflow snapshot, including immutable bulk operations, preflight report, progress, bounded failure, and restart instructions.", "operationId": "getPaperlessImport", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperlessImportStatusResponse" } } }, "description": "Authoritative workflow status", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Read authoritative upload, preflight, import, and bulk progress", "tags": [ "migration" ] } }, "/api/v1/paperless-imports/{import_id}/cancel": { "post": { "description": "Canceling never changes the browser-selected export. A migration that already began importing documents cannot be canceled; it remains restart-safe instead.", "operationId": "cancelPaperlessImport", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperlessImportStatusResponse" } } }, "description": "Workflow canceled and staging cleanup requested", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Cancel a migration before document import and remove its staged copy", "tags": [ "migration" ] } }, "/api/v1/paperless-imports/{import_id}/files/{ordinal}": { "head": { "description": "Requires migration.manage and exact household scope. Available only while the workflow is uploading; the returned offset and length describe durable staging state, while foreign or non-uploading files return 404.", "operationId": "getPaperlessImportFileOffset", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "in": "path", "name": "ordinal", "required": true, "schema": { "minimum": 0, "type": "integer" } } ], "responses": { "204": { "description": "Upload-Offset and Upload-Length are authoritative", "headers": { "Upload-Length": { "description": "Declared file length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Upload-Metadata": { "description": "Base64-encoded relative export path", "schema": { "type": "string" } }, "Upload-Offset": { "description": "Current durable byte offset", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Recover one staged export file's durable offset", "tags": [ "migration" ] }, "patch": { "description": "Requires migration.manage and an exact same-origin proof for cookie requests. The supplied offset must equal durable state and every bounded chunk must carry a matching SHA-256 checksum; failure rolls the file back and success advances the offset only after durable sync.", "operationId": "appendPaperlessImportFile", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "in": "path", "name": "ordinal", "required": true, "schema": { "minimum": 0, "type": "integer" } }, { "in": "header", "name": "Upload-Offset", "required": true, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "sha256 plus a base64 digest", "in": "header", "name": "Upload-Checksum", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/offset+octet-stream": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } } }, "required": true }, "responses": { "204": { "description": "Chunk is durable and Upload-Offset advanced", "headers": { "Upload-Length": { "description": "Declared file length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Upload-Offset": { "description": "Next durable byte offset", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "415": { "$ref": "#/components/responses/UnsupportedMediaTypeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "460": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Chunk checksum mismatch", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Append one checksummed bounded export-file chunk", "tags": [ "migration" ] } }, "/api/v1/paperless-imports/{import_id}/finish-upload": { "post": { "description": "Requires migration.manage and an exact same-origin proof for cookie requests. Every declared file must be complete, regular, non-symlink staging data of the declared length before the workflow atomically queues read-only preflight; repeating the command after that transition is safe.", "operationId": "finishPaperlessImportUpload", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperlessImportStatusResponse" } } }, "description": "Preflight queued", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Verify the complete staged folder and queue read-only preflight", "tags": [ "migration" ] } }, "/api/v1/paperless-imports/{import_id}/retry": { "post": { "description": "Requires migration.manage, an exact same-origin proof for cookie requests, and the document permissions required by the immutable workflow. A failed preflight or import is requeued with the same staged export, bulk operations, and durable checkpoints; an already active or completed retry is safe.", "operationId": "retryPaperlessImport", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperlessImportStatusResponse" } } }, "description": "Failed phase requeued with the same immutable inputs", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Safely retry a stopped preflight or import", "tags": [ "migration" ] } }, "/api/v1/paperless-imports/{import_id}/start": { "post": { "description": "The uploaded export and ordered bulk operations are immutable. Repeating this command is safe; the worker resumes terminal document and operation checkpoints.", "operationId": "startPaperlessImport", "parameters": [ { "in": "path", "name": "import_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } } ], "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaperlessImportStatusResponse" } } }, "description": "Import queued or already running", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Start the reviewed, checkpointed migration", "tags": [ "migration" ] } }, "/api/v1/personal-access-tokens": { "get": { "description": "Only normal sessions may manage credentials. Raw bearer tokens and stored digests are never returned.", "operationId": "listPersonalAccessTokens", "responses": { "200": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/PersonalAccessToken" }, "type": "array" } } }, "description": "Current token metadata", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List the caller's current personal access token metadata", "tags": [ "members" ] }, "post": { "description": "Requires same-origin proof for cookie requests and a normal session. The raw bearer is returned only in this 201 response; personal access tokens cannot manage credentials, including other tokens.", "operationId": "createPersonalAccessToken", "requestBody": { "content": { "application/json": { "example": { "expiresAtMs": 1787836800000, "label": "document-ingest-client", "scopes": [ "read", "write" ] }, "schema": { "$ref": "#/components/schemas/CreatePersonalAccessTokenRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "example": { "accessToken": "0000000000000000000000000000000000000000000000000000000000000000", "token": { "createdAtMs": 1785158400000, "expiresAtMs": 1787836800000, "id": "pat_010000000000000000000000000", "label": "document-ingest-client", "lastUsedAtMs": null, "scopes": [ "read", "write" ] } }, "schema": { "$ref": "#/components/schemas/CreatePersonalAccessTokenResponse" } } }, "description": "Token created; copy accessToken now", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Create a scoped, expiring personal access token", "tags": [ "members" ] } }, "/api/v1/personal-access-tokens/{token_id}": { "delete": { "description": "Requires same-origin proof for cookie requests and a normal session. It is idempotent and never reveals whether a token identifier belonged to another member.", "operationId": "revokePersonalAccessToken", "parameters": [ { "description": "Jiandu personal access token record identifier.", "in": "path", "name": "token_id", "required": true, "schema": { "$ref": "#/components/schemas/PersonalAccessTokenObjectId" } } ], "responses": { "204": { "description": "Token revoked or already absent", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Revoke one of the caller's personal access tokens", "tags": [ "members" ] } }, "/api/v1/plugins": { "get": { "description": "Requires plugins.manage. Compatibility and malformed-descriptor health are reported without executing plugin code.", "operationId": "listInstalledPlugins", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginCatalogResponse" } } }, "description": "Installed plugin catalog", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "List the household plugin catalog", "tags": [ "plugins" ] } }, "/api/v1/plugins/{plugin_id}": { "get": { "description": "Requires plugins.manage. Returns the portable descriptor, compatibility and health state, declared settings, and current values without executing plugin code, together with a strong installation and settings ETag.", "operationId": "getInstalledPlugin", "parameters": [ { "description": "Namespaced plugin identifier", "in": "path", "name": "plugin_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginDescriptorResponse" } } }, "description": "Plugin descriptor with a strong installation/settings ETag", "headers": { "ETag": { "description": "Strong installation and settings revision", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Read one installed plugin descriptor and current settings", "tags": [ "plugins" ] } }, "/api/v1/plugins/{plugin_id}/command-runs/{command_run_id}": { "get": { "description": "Requires plugins.use. Only the principal that queued the run may read it, and document-targeted runs additionally require current read access to that document; cross-principal, inaccessible, and unknown identifiers return 404.", "operationId": "getPluginCommandRun", "parameters": [ { "description": "Namespaced plugin identifier", "in": "path", "name": "plugin_id", "required": true, "schema": { "type": "string" } }, { "description": "Server-generated plugin command run identifier", "in": "path", "name": "command_run_id", "required": true, "schema": { "$ref": "#/components/schemas/PluginCommandRunObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginCommandRunResponse" } } }, "description": "Current command run state", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read a durable plugin command run", "tags": [ "plugins" ] } }, "/api/v1/plugins/{plugin_id}/commands/{command_id}/runs": { "post": { "description": "Requires plugins.use, same-origin proof for cookie requests, a bounded Idempotency-Key, and edit access for a document target. Plugin execution is asynchronous.", "operationId": "queuePluginCommand", "parameters": [ { "description": "Namespaced plugin identifier", "in": "path", "name": "plugin_id", "required": true, "schema": { "type": "string" } }, { "description": "Declared namespaced command identifier", "in": "path", "name": "command_id", "required": true, "schema": { "type": "string" } }, { "description": "Caller-generated command deduplication key", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueuePluginCommandRequest" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginCommandRunResponse" } } }, "description": "Command queued or an identical run replayed", "headers": { "Location": { "description": "Relative URL of the durable command run", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Queue one declared plugin command", "tags": [ "plugins" ] } }, "/api/v1/plugins/{plugin_id}/settings": { "patch": { "description": "Requires plugins.manage, same-origin proof for cookie requests, and the exact installation/settings ETag returned by the plugin descriptor.", "operationId": "updatePluginSettings", "parameters": [ { "description": "Namespaced plugin identifier", "in": "path", "name": "plugin_id", "required": true, "schema": { "type": "string" } }, { "description": "Strong plugin ETag in the form installationRevision.settingsRevision", "in": "header", "name": "If-Match", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePluginSettingsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PluginDescriptorResponse" } } }, "description": "Updated descriptor and settings", "headers": { "ETag": { "description": "Strong installation and settings revision after the update", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "422": { "$ref": "#/components/responses/UnprocessableEntityResponse" }, "428": { "$ref": "#/components/responses/PreconditionRequiredResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Update declared plugin settings optimistically", "tags": [ "plugins" ] } }, "/api/v1/reprocessing-runs/{processing_run_id}/differences": { "get": { "description": "Requires documents.read and current read access to the run's document. Results exist only after successful publication; unknown, foreign-household, and no-longer-accessible run identifiers are indistinguishable as 404.", "operationId": "getReprocessingDifferences", "parameters": [ { "description": "Household-scoped core processing run identifier.", "in": "path", "name": "processing_run_id", "required": true, "schema": { "$ref": "#/components/schemas/ProcessingRunObjectId" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReprocessingDifferences" } } }, "description": "Material differences and preserved-user-field count", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read bounded material differences after publication", "tags": [ "documents" ] } }, "/api/v1/session": { "delete": { "description": "Logout is idempotent. A cookie, ordinary bearer session, both, or neither may be supplied; any supplied recognized session credentials are revoked. Personal access tokens cannot use this credential-management route. Browser requests are subject to same-origin checks.", "operationId": "deleteSession", "responses": { "204": { "description": "Supplied credentials are revoked or were already absent", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Set-Cookie": { "description": "Cookie-expiration header when a browser cookie was supplied", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ {}, { "cookieAuth": [] }, { "sessionBearerAuth": [] } ], "summary": "Revoke supplied session credentials and expire a supplied browser cookie", "tags": [ "session" ] }, "get": { "description": "Supply exactly one credential source: the session cookie or an opaque bearer token. Rotation preserves the response shape and may include a replacement Set-Cookie header.", "operationId": "getSession", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "The session is valid", "headers": { "Cache-Control": { "description": "Always no-store", "schema": { "type": "string" } }, "Set-Cookie": { "description": "Optional rotated opaque session cookie", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Verify the current session and rotate it when due", "tags": [ "session" ] }, "post": { "description": "The recovery token or password is accepted only in this JSON body and is never persisted by the session store. Browser requests are subject to same-origin Fetch Metadata and Origin checks. The returned credential is set as a host-only HttpOnly SameSite=Strict cookie.", "operationId": "createSession", "requestBody": { "content": { "application/json": { "examples": { "Owner recovery token": { "summary": "Break-glass local token", "value": { "accessToken": "0000000000000000000000000000000000000000000000000000000000000000", "method": "local_token" } }, "Password": { "summary": "Named local account", "value": { "method": "password", "password": "correct-horse-battery-staple", "username": "alex" } } }, "schema": { "$ref": "#/components/schemas/CreateSessionRequest" } } }, "description": "Exactly one credential shape: {accessToken}, {method: local_token, accessToken}, or {method: password, username, password}", "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "authenticated": true, "authenticationMethod": "password", "expiresAtMs": 1787836800000, "permissions": [ "documents.read", "documents.create" ], "principalId": "prn_010000000000000000000000000", "setup": { "claimAvailable": false, "state": "claimed" } }, "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Authenticated and session cookie issued", "headers": { "Cache-Control": { "description": "Always no-store for credential responses", "schema": { "type": "string" } }, "Set-Cookie": { "description": "Opaque host-only HttpOnly SameSite=Strict Jiandu session cookie", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "Malformed JSON request", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [], "summary": "Exchange a local recovery token or username/password for an opaque session", "tags": [ "session" ] } }, "/api/v1/setup/claim": { "post": { "description": "Requires an unclaimed installation, an ordinary same-origin cookie session for an active USER principal, and proof of the protected owner recovery credential. The transaction permanently closes setup claiming, binds the built-in Administrator role, and appends a safe audit event. The recovery Owner remains separate.", "operationId": "claimInstallationSetup", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimInstallationSetupRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } }, "description": "Setup claimed and current capabilities refreshed", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] } ], "summary": "Claim initial Administrator access for the current human account", "tags": [ "installation" ] } }, "/api/v1/tasks/{task_id}": { "get": { "description": "Task lookup is scoped only from the authenticated session. Unknown, malformed, and out-of-scope identifiers all return the same 404 response.", "operationId": "getTask", "parameters": [ { "description": "Canonical household-scoped task identifier returned by intake.", "in": "path", "name": "task_id", "required": true, "schema": { "$ref": "#/components/schemas/TaskObjectId" } } ], "responses": { "200": { "content": { "application/json": { "example": { "documentId": "doc_010000000000000000000000000", "error": null, "id": "task_010000000000000000000000000", "progress": 1.0, "state": "ready" }, "schema": { "$ref": "#/components/schemas/Task" } } }, "description": "Current durable task state", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read household-scoped asynchronous task status", "tags": [ "tasks" ] } }, "/api/v1/uploads": { "options": { "description": "Unauthenticated constant TUS discovery response advertising creation, termination, expiration, and SHA-1 or SHA-256 checksum support; it does not access upload storage.", "operationId": "discoverResumableUploads", "responses": { "204": { "description": "Creation, termination, checksum, and expiration extensions are available", "headers": { "Tus-Checksum-Algorithm": { "description": "Supported chunk checksum algorithms", "schema": { "type": "string" } }, "Tus-Extension": { "description": "Supported TUS extensions", "schema": { "type": "string" } }, "Tus-Resumable": { "description": "TUS protocol version 1.0.0", "schema": { "type": "string" } }, "Tus-Version": { "description": "Supported TUS versions", "schema": { "type": "string" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [], "summary": "Discover the TUS 1.0 resumable-upload capabilities", "tags": [ "intake" ] }, "post": { "description": "Implements TUS 1.0 creation. Upload-Length is a declared original length, not a Jiandu product limit. Upload-Metadata carries base64 filename, optional conventional filetype (or Jiandu contentType), and allowDuplicate fields. Retrying an identical Idempotency-Key returns the original session Location.", "operationId": "createResumableUpload", "parameters": [ { "description": "Required value: 1.0.0", "example": "1.0.0", "in": "header", "name": "Tus-Resumable", "required": true, "schema": { "type": "string" } }, { "description": "Exact original length", "example": 1048576, "in": "header", "name": "Upload-Length", "required": true, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "TUS base64 metadata", "example": "filename c2FtcGxlLnBkZg==,filetype YXBwbGljYXRpb24vcGRm", "in": "header", "name": "Upload-Metadata", "required": true, "schema": { "type": "string" } }, { "description": "Stable caller-owned command identity", "example": "01k3q8r6m7-upload-0001", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Session created or idempotently recovered; Location identifies it", "headers": { "Location": { "description": "Relative URL of the upload session", "schema": { "type": "string" } }, "Tus-Resumable": { "description": "TUS protocol version 1.0.0", "schema": { "type": "string" } }, "Upload-Expires": { "description": "HTTP-date after which the session expires", "schema": { "type": "string" } }, "Upload-Length": { "description": "Declared total byte length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Upload-Offset": { "description": "Current durable byte offset", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Create or recover a durable resumable-upload session", "tags": [ "intake" ] } }, "/api/v1/uploads/{upload_id}": { "delete": { "description": "Requires documents.create, Tus-Resumable 1.0.0, and an exact same-origin proof for cookie requests. Only an active unexpired session in the authenticated intake scope can be terminated; cancellation records private spool cleanup, while terminal and expired sessions return 404.", "operationId": "cancelResumableUpload", "parameters": [ { "description": "Jiandu upload identifier", "in": "path", "name": "upload_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "description": "Required value: 1.0.0", "in": "header", "name": "Tus-Resumable", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Transfer terminated and private spool cleanup recorded", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Terminate one independently resumable upload", "tags": [ "intake" ] }, "get": { "description": "Requires documents.create, Tus-Resumable 1.0.0, and the authenticated intake scope that owns the upload. Returns source-neutral transfer and finalization state plus any durable document, task, or bounded failure outcome.", "operationId": "getResumableUpload", "parameters": [ { "description": "Jiandu upload identifier", "in": "path", "name": "upload_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "description": "Required value: 1.0.0", "in": "header", "name": "Tus-Resumable", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadStatusResponse" } } }, "description": "Current source-neutral upload status", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Read transfer, finalization, and durable acceptance status", "tags": [ "intake" ] }, "head": { "description": "Requires documents.create, Tus-Resumable 1.0.0, and the authenticated intake scope that owns the upload. Returns durable offset, declared length, and expiry; unknown, cross-scope, canceled, and expired sessions return 404.", "operationId": "getResumableUploadOffset", "parameters": [ { "description": "Jiandu upload identifier", "in": "path", "name": "upload_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "description": "Required value: 1.0.0", "example": "1.0.0", "in": "header", "name": "Tus-Resumable", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Upload-Offset, Upload-Length, and Upload-Expires describe the session", "headers": { "Tus-Resumable": { "description": "TUS protocol version 1.0.0", "schema": { "type": "string" } }, "Upload-Expires": { "description": "HTTP-date after which the session expires", "schema": { "type": "string" } }, "Upload-Length": { "description": "Declared total byte length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Upload-Offset": { "description": "Current durable byte offset", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "404": { "$ref": "#/components/responses/NotFoundResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Recover the authoritative durable upload offset", "tags": [ "intake" ] }, "patch": { "description": "The per-request chunk budget bounds memory and retry cost; it is not a whole-document limit. A successful response advances Upload-Offset only after the chunk is durable.", "operationId": "appendResumableUpload", "parameters": [ { "description": "Jiandu upload identifier", "in": "path", "name": "upload_id", "required": true, "schema": { "$ref": "#/components/schemas/UploadObjectId" } }, { "description": "Required value: 1.0.0", "example": "1.0.0", "in": "header", "name": "Tus-Resumable", "required": true, "schema": { "type": "string" } }, { "description": "Authoritative offset recovered with HEAD", "example": 0, "in": "header", "name": "Upload-Offset", "required": true, "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, { "description": "Optional sha1 or sha256 chunk checksum", "example": "sha256 ungWv48Bz+pBQUDeXa4iI7ADYaOWF3qctBD/YfIAFa0=", "in": "header", "name": "Upload-Checksum", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/offset+octet-stream": { "schema": { "description": "Raw request bytes for offset-based transfer endpoints. This schema type is\ndocumentation-only; handlers continue to stream and bound the body.", "format": "binary", "type": "string" } } }, "required": true }, "responses": { "204": { "description": "Chunk durably appended; Upload-Offset is the next position", "headers": { "Tus-Resumable": { "description": "TUS protocol version 1.0.0", "schema": { "type": "string" } }, "Upload-Expires": { "description": "HTTP-date after which the session expires", "schema": { "type": "string" } }, "Upload-Length": { "description": "Declared total byte length", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "Upload-Offset": { "description": "Next durable byte offset", "schema": { "format": "int64", "minimum": 0, "type": "integer" } }, "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequestResponse" }, "401": { "$ref": "#/components/responses/UnauthorizedResponse" }, "403": { "$ref": "#/components/responses/OriginForbiddenResponse" }, "409": { "$ref": "#/components/responses/ConflictResponse" }, "412": { "$ref": "#/components/responses/PreconditionFailedResponse" }, "413": { "$ref": "#/components/responses/PayloadTooLargeResponse" }, "415": { "$ref": "#/components/responses/UnsupportedMediaTypeResponse" }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" }, "460": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } }, "description": "The supplied chunk checksum did not match", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "503": { "$ref": "#/components/responses/ServiceUnavailableResponse" } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "summary": "Append one checksummed bounded transfer chunk", "tags": [ "intake" ] } }, "/api/v1/version": { "get": { "description": "Unauthenticated constant response exposing the running release version, native API contract version, and deployment profile; it does not consult component health.", "operationId": "getVersion", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Version" } } }, "description": "Version information", "headers": { "X-Request-Id": { "description": "Opaque request correlation identifier. ProblemDetails.requestId carries the same value on JSON failures.", "schema": { "type": "string" } } } }, "421": { "$ref": "#/components/responses/MisdirectedRequestResponse" } }, "security": [], "summary": "Report application, API, and deployment profile versions", "tags": [ "system" ] } } }, "security": [ { "cookieAuth": [] }, { "bearerAuth": [] } ], "servers": [ { "description": "Configured same-origin Jiandu server", "url": "/" } ], "tags": [ { "description": "Local deployment metadata and readiness", "name": "system" }, { "description": "Opaque local-session lifecycle and optional browser OIDC sign-in", "name": "session" }, { "description": "Durable single-file and batch intake", "name": "intake" }, { "description": "Asynchronous processing status", "name": "tasks" }, { "description": "Household membership administration", "name": "members" }, { "description": "Advanced household roles, groups, and membership access administration", "name": "authorization" }, { "description": "Household-scoped search, correction, lifecycle, and reprocessing", "name": "documents" }, { "description": "Explicit per-document visibility policies and grants layered after household RBAC", "name": "document access" }, { "description": "Adaptive metadata suggestions, user-controlled rules, settings, audit, and privacy-scoped export", "name": "learning" }, { "description": "Email ingest connector configuration and mailbox authorization", "name": "connectors" }, { "description": "Operator-allowlisted watch folders, eSCL/AirScan, and scanner-job administration", "name": "capture" }, { "description": "Narrow outbound Linux/SANE agent enrollment, leasing, and checksummed result transfer", "name": "capture agent" }, { "description": "Installed plugin catalog, portable contributions, settings, and asynchronous commands", "name": "plugins" }, { "description": "Restart-safe import of reviewed external document exports", "name": "migration" }, { "description": "Durable recipient inbox and connected-browser preferences", "name": "notifications" }, { "description": "Permission-authorized, privacy-bounded browser diagnostic records", "name": "diagnostics" } ] }