1327 lines
41 KiB
YAML
1327 lines
41 KiB
YAML
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 }
|