openapi: 3.1.0 info: title: drosync API version: 1.0.0 description: | Contract source for the drosync one-way local-to-BOS synchronization service. Every write requires Idempotency-Key. List cursors are opaque. Multipart ETags are transport validators and MUST NOT be represented as file SHA-256. External calls are protected by Mongo-backed distributed fixed-window limits and return RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. servers: - url: / tags: - name: management - name: authentication - name: transfer - name: release - name: audit paths: /api/object-sync/spaces: get: tags: [management] operationId: listSyncSpaces responses: "200": $ref: "#/components/responses/SpaceList" default: $ref: "#/components/responses/Error" post: tags: [management] operationId: createSyncSpace parameters: - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SpaceCreate" responses: "201": description: Space created in blocked/unverified state. content: application/json: schema: $ref: "#/components/schemas/Space" default: $ref: "#/components/responses/Error" /api/object-sync/spaces/{id}: put: tags: [management] operationId: updateSyncSpace parameters: - $ref: "#/components/parameters/ResourceID" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object properties: name: { type: string } description: { type: string } operatorUserIds: type: array items: { type: string } enabled: { type: boolean } exclusivePrefixConfirmed: { type: boolean } allowForceOverwrite: type: boolean description: Requires update-enabled capability and exclusive-prefix confirmation. responses: "200": description: Updated space. content: application/json: schema: $ref: "#/components/schemas/Space" default: $ref: "#/components/responses/Error" /api/object-sync/spaces/{id}/capability-probe: post: tags: [management] operationId: probeSyncSpaceCapabilities parameters: - $ref: "#/components/parameters/ResourceID" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Persisted capability probe result. content: application/json: schema: $ref: "#/components/schemas/Space" default: $ref: "#/components/responses/Error" /api/object-sync/spaces/{id}/reconcile: post: tags: [management] operationId: reconcileSyncSpace parameters: - $ref: "#/components/parameters/ResourceID" - $ref: "#/components/parameters/IdempotencyKey" responses: "202": description: Reconciliation accepted. content: application/json: schema: type: object required: [id, operationId, syncSpaceId, status] properties: id: { type: string } operationId: { type: string } syncSpaceId: { type: string } status: { type: string, enum: [pending, running, completed, failed] } scanned: { type: integer, format: int64 } drifted: { type: integer, format: int64 } default: $ref: "#/components/responses/Error" /api/object-sync/devices: get: tags: [management] operationId: listDevices responses: "200": $ref: "#/components/responses/GenericList" default: $ref: "#/components/responses/Error" /api/object-sync/device-authorizations: get: tags: [management] deprecated: true operationId: deviceAuthorizationsRemoved responses: "410": description: Short-code device approval was removed in favor of scoped access keys. default: $ref: "#/components/responses/Error" /api/object-sync/device-authorizations/by-code: get: tags: [management] deprecated: true operationId: deviceAuthorizationLookupRemoved parameters: - name: userCode in: query required: true schema: type: string minLength: 6 maxLength: 16 responses: "410": description: Short-code device approval was removed. default: $ref: "#/components/responses/Error" /api/object-sync/device-authorizations/{id}/{decision}: post: tags: [management] deprecated: true operationId: deviceAuthorizationDecisionRemoved parameters: - $ref: "#/components/parameters/ResourceID" - name: decision in: path required: true schema: type: string enum: [approve, deny] - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object required: [scopes] properties: scopes: type: array items: $ref: "#/components/schemas/CredentialScope" responses: "410": description: Short-code device approval was removed. default: $ref: "#/components/responses/Error" /api/object-sync/credentials: get: tags: [management] operationId: listDeviceCredentials responses: "200": $ref: "#/components/responses/GenericList" default: $ref: "#/components/responses/Error" post: tags: [management] operationId: createDeviceCredential parameters: - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/CredentialCreate" responses: "201": description: Scoped access key created. The secret is returned exactly once. content: application/json: schema: $ref: "#/components/schemas/CredentialIssueResponse" default: $ref: "#/components/responses/Error" /api/object-sync/credentials/{id}/{action}: post: tags: [management] operationId: mutateDeviceCredential parameters: - $ref: "#/components/parameters/ResourceID" - name: action in: path required: true schema: type: string enum: [rotate, revoke] - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Credential rotated or revoked. default: $ref: "#/components/responses/Error" /api/object-sync/sessions: get: tags: [management] operationId: listSessions parameters: - $ref: "#/components/parameters/Cursor" - $ref: "#/components/parameters/Limit" - name: start in: query schema: { type: string, format: date-time } - name: end in: query schema: { type: string, format: date-time } - name: sessionId in: query schema: { type: string } responses: "200": $ref: "#/components/responses/GenericList" default: $ref: "#/components/responses/Error" /api/object-sync/sessions/{id}: get: tags: [management] operationId: getSession parameters: - $ref: "#/components/parameters/ResourceID" responses: "200": description: Session. content: application/json: schema: $ref: "#/components/schemas/Session" default: $ref: "#/components/responses/Error" /api/object-sync/sessions/{id}/items: get: tags: [management] operationId: listSessionItems parameters: - $ref: "#/components/parameters/ResourceID" - $ref: "#/components/parameters/Cursor" - $ref: "#/components/parameters/Limit" - name: status in: query schema: $ref: "#/components/schemas/ItemStatus" responses: "200": description: Cursor page. content: application/json: schema: $ref: "#/components/schemas/ItemPage" default: $ref: "#/components/responses/Error" /api/object-sync/sessions/{id}/admin-abort: post: tags: [management] operationId: adminAbortSession parameters: - $ref: "#/components/parameters/ResourceID" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Session aborted; committed objects are retained. default: $ref: "#/components/responses/Error" /api/object-sync/leases/{id}/force-release: post: tags: [management] operationId: forceReleaseLease parameters: - $ref: "#/components/parameters/ResourceID" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Lease ownership cleared; fencing counter retained. default: $ref: "#/components/responses/Error" /api/object-sync/items/{id}/force-overwrite: post: tags: [management] operationId: forceOverwriteConflict parameters: - $ref: "#/components/parameters/ResourceID" - $ref: "#/components/parameters/IdempotencyKey" responses: "202": description: | Conditional promotion of a preserved keep-both object was accepted. The conflict object remains immutable and is not deleted. content: application/json: schema: type: object required: [operationId, item] properties: operationId: { type: string } item: $ref: "#/components/schemas/Item" default: $ref: "#/components/responses/Error" /api/object-sync/releases: get: tags: [release] operationId: listReleases responses: "200": $ref: "#/components/responses/GenericList" default: $ref: "#/components/responses/Error" post: tags: [release] operationId: createRelease parameters: - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object required: [name, sessionIds] properties: name: { type: string } description: { type: string } sessionIds: type: array minItems: 1 items: { type: string } responses: "202": $ref: "#/components/responses/Accepted" default: $ref: "#/components/responses/Error" /api/object-sync/audit-events: get: tags: [audit] operationId: listAuditEvents parameters: - $ref: "#/components/parameters/Cursor" - $ref: "#/components/parameters/Limit" responses: "200": $ref: "#/components/responses/GenericList" default: $ref: "#/components/responses/Error" /api/object-sync/audit-events/export: get: tags: [audit] operationId: exportAuditEvents parameters: - name: format in: query schema: type: string enum: [csv, ndjson] default: ndjson - name: start in: query schema: { type: string, format: date-time } - name: end in: query schema: { type: string, format: date-time } - name: sessionId in: query schema: { type: string } responses: "200": description: Streaming audit export. content: text/csv: {} application/x-ndjson: {} default: $ref: "#/components/responses/Error" /api/object-sync/audit-seals/{day}: get: tags: [audit] operationId: getAuditSeal parameters: - name: day in: path required: true schema: type: string pattern: "^\\d{4}-\\d{2}-\\d{2}$" responses: "200": description: Signed UTC-day audit-chain seal stored in the internal BOS audit prefix. content: application/json: schema: $ref: "#/components/schemas/AuditSeal" default: $ref: "#/components/responses/Error" /api/object-sync/client-releases: get: tags: [release] operationId: listClientReleases responses: "200": $ref: "#/components/responses/GenericList" default: $ref: "#/components/responses/Error" post: tags: [release] operationId: upsertClientRelease parameters: - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ClientRelease" responses: "200": description: Signed client release saved. default: $ref: "#/components/responses/Error" /api/object-sync/client-releases/{id}/artifacts/{platform}: get: tags: [release] operationId: downloadPreviewClientReleaseArtifact description: Streams a manual-download POC preview artifact. Preview artifacts are never eligible for automatic updates. parameters: - name: id in: path required: true schema: { type: string } - name: platform in: path required: true schema: { type: string, enum: [macos-arm64, windows-x86_64, linux-x86_64] } responses: "200": description: Client package stream. content: application/octet-stream: schema: { type: string, format: binary } "206": description: Partial client package stream. default: $ref: "#/components/responses/Error" /api/external/object-sync/device-authorizations: post: tags: [authentication] deprecated: true operationId: createDeviceAuthorizationRemoved security: [] parameters: - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/DeviceAuthorizationCreate" responses: "410": description: Short-code device approval was removed. default: $ref: "#/components/responses/Error" /api/external/object-sync/device-authorizations/token: post: tags: [authentication] deprecated: true operationId: pollDeviceAuthorizationRemoved security: [] parameters: - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object required: [deviceCode] properties: deviceCode: { type: string } responses: "410": description: Short-code device approval was removed. default: $ref: "#/components/responses/Error" /api/external/object-sync/auth/token: post: tags: [authentication] operationId: authenticateAccessKey security: [] parameters: - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/AccessKeyAuthentication" responses: "200": description: Bearer credential issued for a valid scoped access key and secret. content: application/json: schema: $ref: "#/components/schemas/AccessKeyAuthenticationResponse" default: $ref: "#/components/responses/Error" /api/external/object-sync/capabilities: get: tags: [transfer] operationId: getCapabilities security: - deviceBearer: [] responses: "200": description: Scoped spaces and server limits. default: $ref: "#/components/responses/Error" /api/external/object-sync/sessions: post: tags: [transfer] operationId: createSession security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/SessionCreate" responses: "201": description: Session collecting manifest. content: application/json: schema: $ref: "#/components/schemas/Session" default: $ref: "#/components/responses/Error" /api/external/object-sync/sessions/{sessionId}/manifest-pages: post: tags: [transfer] operationId: appendManifestPage security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/SessionID" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: $ref: "#/components/schemas/ManifestPage" responses: "202": description: Page accepted. default: $ref: "#/components/responses/Error" /api/external/object-sync/sessions/{sessionId}/plan: post: tags: [transfer] operationId: planSession security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/SessionID" - $ref: "#/components/parameters/IdempotencyKey" responses: "202": $ref: "#/components/responses/Accepted" default: $ref: "#/components/responses/Error" /api/external/object-sync/sessions/{sessionId}/status: get: tags: [transfer] operationId: getExternalSessionStatus security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/SessionID" responses: "200": description: Session status. content: application/json: schema: $ref: "#/components/schemas/Session" default: $ref: "#/components/responses/Error" /api/external/object-sync/sessions/{sessionId}/items: get: tags: [transfer] operationId: listExternalSessionItems security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/SessionID" - $ref: "#/components/parameters/Cursor" - $ref: "#/components/parameters/Limit" - name: status in: query schema: { type: string } responses: "200": description: Planned or terminal session items with an opaque next cursor. content: application/json: schema: $ref: "#/components/schemas/ItemPage" default: $ref: "#/components/responses/Error" /api/external/object-sync/sessions/{sessionId}/{action}: post: tags: [transfer] operationId: finishSession security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/SessionID" - name: action in: path required: true schema: type: string enum: [complete, abort] - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Final session state. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/reserve: post: tags: [transfer] operationId: reserveItem security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Lease and monotonic fencing token. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/uploads/direct: post: tags: [transfer] operationId: prepareDirectUpload security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object required: [contentMd5] properties: contentMd5: type: string description: Base64-encoded MD5 digest bound into the BOS presigned request. responses: "200": description: Short-lived staging PUT URL and required validators. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/uploads/direct/complete: post: tags: [transfer] operationId: completeDirectUpload security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Staging object verified by size and BOS metadata. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/uploads/multipart: post: tags: [transfer] operationId: initiateMultipartUpload security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" responses: "201": description: Staging multipart upload. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/uploads/multipart/part-url: post: tags: [transfer] operationId: getMultipartPartURL security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object required: [partNumber, contentMd5, sizeBytes] properties: partNumber: { type: integer, minimum: 1, maximum: 10000 } contentMd5: { type: string } sizeBytes: { type: integer, format: int64, minimum: 1 } responses: "200": description: Short-lived part URL. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/uploads/multipart/parts: post: tags: [transfer] operationId: checkpointMultipartPart security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" requestBody: required: true content: application/json: schema: type: object required: [partNumber, eTag, sizeBytes] properties: partNumber: { type: integer, minimum: 1, maximum: 10000 } eTag: { type: string, minLength: 1 } sizeBytes: { type: integer, format: int64, minimum: 1 } responses: "200": description: Part ETag checkpoint persisted for crash recovery. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/uploads/multipart/complete: post: tags: [transfer] operationId: completeStagingMultipart security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Part ETags and final staging size verified. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/heartbeat: post: tags: [transfer] operationId: heartbeatItemLease security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Lease renewed only for matching fencing token. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/abort: post: tags: [transfer] operationId: abortItem security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" responses: "200": description: Multipart aborted and lease released. default: $ref: "#/components/responses/Error" /api/external/object-sync/items/{itemId}/commit: post: tags: [transfer] operationId: commitItem security: - deviceBearer: [] parameters: - $ref: "#/components/parameters/ItemID" - $ref: "#/components/parameters/IdempotencyKey" responses: "202": $ref: "#/components/responses/Accepted" default: $ref: "#/components/responses/Error" /api/external/object-sync/client-updates: get: tags: [release] operationId: checkClientUpdate security: - deviceBearer: [] parameters: - name: currentVersion in: query required: true schema: { type: string } responses: "200": description: Deterministic rollout result and signed manifest. default: $ref: "#/components/responses/Error" components: securitySchemes: deviceBearer: type: http scheme: bearer bearerFormat: drosync-device-token parameters: IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 128 ResourceID: name: id in: path required: true schema: { type: string } SessionID: name: sessionId in: path required: true schema: { type: string } ItemID: name: itemId in: path required: true schema: { type: string } Cursor: name: cursor in: query schema: type: string description: Opaque cursor; clients MUST NOT parse it. Limit: name: limit in: query schema: type: integer minimum: 1 maximum: 1000 default: 100 responses: Error: description: Stable drosync error envelope. content: application/json: schema: $ref: "#/components/schemas/Error" Accepted: description: Asynchronous operation accepted. content: application/json: schema: type: object required: [operationId] properties: operationId: { type: string } GenericList: description: List response. content: application/json: schema: type: object required: [items] properties: items: type: array items: {} nextCursor: { type: string } SpaceList: description: Sync spaces. content: application/json: schema: type: object required: [items] properties: items: type: array items: $ref: "#/components/schemas/Space" schemas: Error: type: object additionalProperties: false required: [code, message, retryable, requestId] properties: code: { type: string } message: { type: string } retryable: { type: boolean } requestId: { type: string } details: type: object additionalProperties: true SessionStatus: type: string enum: - collecting_manifest - planning - planned - running - completed - partial - conflicted - failed - aborted - expired ItemStatus: type: string enum: - discovered - planned - reserved - uploading - uploaded - committing - committed - kept_both - unchanged - skipped - denied - failed - aborted - expired Capability: type: object required: - state - conditionalCreate - conditionalUpdate - conditionalMultipart - multipartCopy - versionId - exclusivePrefixConfirmed properties: state: type: string enum: [unverified, create_only, update_enabled, drifted, unsupported] conditionalCreate: { type: boolean } conditionalUpdate: { type: boolean } conditionalMultipart: { type: boolean } multipartCopy: { type: boolean } versionId: { type: boolean } exclusivePrefixConfirmed: { type: boolean } probedAt: { type: string, format: date-time } probeError: { type: string } SpacePolicy: type: object required: - allowedActions - maxObjectBytes - maxSessionFiles - maxSessionBytes - maxConcurrentUploads - allowDelete - allowConditionalUpdate - defaultConflictResolution properties: allowedActions: type: array items: { type: string } maxObjectBytes: { type: integer, format: int64, maximum: 1099511627776 } maxSessionFiles: { type: integer, format: int64, maximum: 1000000 } maxSessionBytes: { type: integer, format: int64, maximum: 21990232555520 } maxConcurrentUploads: { type: integer, maximum: 16 } allowDelete: { type: boolean, const: false } allowConditionalUpdate: { type: boolean } defaultConflictResolution: { type: string, const: keep_both } allowForceOverwrite: { type: boolean } SpaceCreate: type: object additionalProperties: false required: [name, connectionId, bucket] properties: name: { type: string } description: { type: string } connectionId: { type: string } bucket: { type: string } rootPrefix: { type: string } operatorUserIds: type: array items: { type: string } policy: $ref: "#/components/schemas/SpacePolicy" Space: type: object required: [id, organizationId, name, connectionId, bucket, rootPrefix, mode, enabled, policy, capability] properties: id: { type: string } organizationId: { type: string } operatorUserIds: type: array items: { type: string } name: { type: string } description: { type: string } connectionId: { type: string } bucket: { type: string } rootPrefix: { type: string } mode: { type: string, enum: [blocked, create_only, update_enabled] } enabled: { type: boolean } policy: $ref: "#/components/schemas/SpacePolicy" capability: $ref: "#/components/schemas/Capability" CredentialScope: type: object required: [syncSpaceId, allowedRelativePrefixes, actions] properties: syncSpaceId: { type: string } allowedRelativePrefixes: type: array items: { type: string } actions: type: array items: type: string enum: [plan, list_metadata, create, update, keep_both] Credential: type: object required: [id, organizationId, name, enabled, accessKeyId, scopes] properties: id: { type: string } organizationId: { type: string } deviceId: { type: string } name: { type: string } enabled: { type: boolean } accessKeyId: { type: string } secretPreview: { type: string } tokenPreview: { type: string } scopes: type: array items: $ref: "#/components/schemas/CredentialScope" lastUsedAt: { type: string, format: date-time } revokedAt: { type: string, format: date-time } CredentialCreate: type: object additionalProperties: false required: [name, scopes] properties: name: { type: string, minLength: 1 } scopes: type: array minItems: 1 maxItems: 100 items: $ref: "#/components/schemas/CredentialScope" CredentialIssueResponse: type: object required: [credential, secret] properties: credential: $ref: "#/components/schemas/Credential" secret: type: string writeOnly: true description: Returned only in this create or rotate response. AccessKeyAuthentication: type: object additionalProperties: false required: [accessKeyId, secret, deviceId, deviceName, platform, architecture, clientVersion] properties: accessKeyId: { type: string } secret: { type: string, writeOnly: true } deviceId: { type: string } deviceName: { type: string } platform: { type: string, enum: [windows, linux, macos] } architecture: { type: string, enum: [x86_64, arm64] } clientVersion: { type: string } AccessKeyAuthenticationResponse: type: object required: [accessToken, device, scopes] properties: accessToken: { type: string, writeOnly: true } device: type: object additionalProperties: true scopes: type: array items: $ref: "#/components/schemas/CredentialScope" DeviceAuthorizationCreate: type: object additionalProperties: false required: [deviceId, deviceName, platform, architecture, clientVersion] properties: deviceId: { type: string } deviceName: { type: string } platform: { type: string, enum: [windows, linux, macos] } architecture: { type: string, enum: [x86_64, aarch64] } clientVersion: { type: string } DeviceAuthorizationResponse: type: object required: [deviceCode, userCode, verificationUri, expiresIn, interval] properties: deviceCode: { type: string } userCode: { type: string } verificationUri: { type: string } expiresIn: { type: integer } interval: { type: integer } SessionCreate: type: object additionalProperties: false required: [syncSpaceId, mappingId, clientVersion, protocolVersion] properties: syncSpaceId: { type: string } mappingId: { type: string } clientVersion: { type: string } protocolVersion: { type: string, const: v1 } Session: type: object required: [id, syncSpaceId, deviceId, status, policySnapshot, counts, totalBytes] properties: id: { type: string } syncSpaceId: { type: string } credentialId: { type: string } deviceId: { type: string } mappingId: { type: string } clientVersion: { type: string } protocolVersion: { type: string } status: $ref: "#/components/schemas/SessionStatus" policySnapshot: $ref: "#/components/schemas/SpacePolicy" manifestDigest: { type: string } manifestFinalPage: { type: integer } counts: type: object additionalProperties: type: integer totalBytes: { type: integer, format: int64 } operationId: { type: string } errorSummary: { type: string } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } RemoteBase: type: object properties: exists: { type: boolean } etag: { type: string } sizeBytes: { type: integer, format: int64 } lastModified: { type: string } platformVersion: { type: integer, format: int64 } versionId: { type: string } ManifestItem: type: object additionalProperties: false required: [clientItemId, relativePath, kind, sizeBytes, modifiedAt, sha256] properties: clientItemId: { type: string } relativePath: type: string description: Slash-separated relative regular-file path; traversal is rejected. kind: { type: string, const: file } sizeBytes: { type: integer, format: int64, minimum: 0, maximum: 1099511627776 } modifiedAt: { type: string, format: date-time } sha256: { type: string, pattern: "^[0-9a-fA-F]{64}$" } contentType: { type: string } lastKnownRemote: $ref: "#/components/schemas/RemoteBase" ManifestPage: type: object additionalProperties: false required: [pageNumber, final, items] properties: pageNumber: { type: integer, minimum: 1 } final: { type: boolean } items: type: array minItems: 1 maxItems: 1000 items: $ref: "#/components/schemas/ManifestItem" Item: type: object required: [id, sessionId, relativePath, targetKey, sizeBytes, sha256, action, status] properties: id: { type: string } sessionId: { type: string } relativePath: { type: string } targetKey: { type: string } logicalTargetKey: { type: string } sizeBytes: { type: integer, format: int64 } sha256: { type: string } action: { type: string } status: $ref: "#/components/schemas/ItemStatus" stagingKey: { type: string } uploadMode: { type: string, enum: [direct, multipart] } uploadId: { type: string } leaseId: { type: string } fencingToken: { type: integer, format: int64 } operationId: { type: string } lastError: { type: string } ItemPage: type: object required: [items] properties: items: type: array items: $ref: "#/components/schemas/Item" nextCursor: type: string description: Opaque cursor. ClientRelease: type: object required: - id - version - kind - channel - protocolVersion - artifacts - sha256 - signature - rolloutPercent - paused properties: id: { type: string } version: { type: string } kind: type: string enum: [signed, preview] description: Signed releases may enter automatic rollout; preview releases are manual POC downloads only. channel: { type: string, enum: [preview, canary, pilot, stable] } protocolVersion: { type: string, const: v1 } minimumServerVersion: { type: string } artifacts: type: object additionalProperties: { type: string, format: uri } sha256: type: object additionalProperties: { type: string, pattern: "^[0-9a-fA-F]{64}$" } signature: type: string contentEncoding: base64 description: Required for kind=signed and empty for kind=preview. rolloutPercent: { type: integer, minimum: 0, maximum: 100 } paused: { type: boolean } createdAt: { type: string, format: date-time } stageChangedAt: type: string format: date-time readOnly: true AuditSeal: type: object required: [id, organizationId, dayUtc, eventCount, aggregateHash, signature, signingKeyId, objectKey, objectETag, createdAt] properties: id: { type: string } organizationId: { type: string } dayUtc: { type: string, format: date } eventCount: { type: integer, format: int64 } firstEventHash: { type: string } lastEventHash: { type: string } aggregateHash: { type: string, pattern: "^[0-9a-f]{64}$" } signature: { type: string, contentEncoding: base64 } signingKeyId: { type: string } objectKey: { type: string } objectETag: { type: string } objectVersionId: { type: string } createdAt: { type: string, format: date-time }