droboticflow/docs/drosync/openapi.yaml

2029 lines
60 KiB
YAML

openapi: 3.1.0
info:
title: drosync API
version: 1.0.7
description: |
Contract source for the drosync one-way local-to-BOS synchronization service.
Every ordinary write requires Idempotency-Key. Cleanup-proof acquisition/release
deliberately bypasses the receipt cache so each deletion uses a fresh HEAD and lease.
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/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
- name: deviceId
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'
- name: action
in: query
schema:
type: string
responses:
'200':
description: Cursor page.
content:
application/json:
schema:
$ref: '#/components/schemas/ItemPage'
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
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: status
in: query
schema:
type: string
responses:
'200':
description: Newest releases first; opaque cursor.
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DataRelease'
nextCursor:
type: string
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'
- name: start
in: query
schema:
type: string
- name: end
in: query
schema:
type: string
- name: sessionId
in: query
schema:
type: string
- name: action
in: query
schema:
type: string
- name: result
in: query
schema:
type: string
responses:
'200':
description: Filtered audit page with nextCursor.
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
type: object
nextCursor:
type: string
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
- name: action
in: query
schema:
type: string
- name: result
in: query
schema:
type: string
responses:
'200':
description: Complete filtered export; server spools all pages first (two concurrent exports, five minute
limit). Content-Length and X-Content-SHA256 detect truncation.
content:
text/csv: {}
application/x-ndjson: {}
headers:
X-Content-SHA256:
schema:
type: string
X-Record-Count:
schema:
type: integer
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: registerClientRelease
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ClientRelease'
responses:
'200':
description: Register immutable v2 manifest. Signed starts at canary5; preview at preview100. Same identity
may be re-registered without resetting rollout.
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/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: Pending token, activation ID and expiry. Existing active device token remains valid until activation.
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, server limits, and explicitly supported transfer capabilities.
content:
application/json:
schema:
type: object
required:
- protocolVersion
- features
- spaces
- limits
properties:
protocolVersion:
type: string
features:
type: object
required:
- sessionHeartbeat
- previewSessions
- credentialActivation
- metadataRecovery
- missingFileSkip
- safeClean
properties:
sessionHeartbeat:
type: boolean
const: true
previewSessions:
type: boolean
const: true
credentialActivation:
type: boolean
const: true
metadataRecovery:
type: boolean
const: true
missingFileSkip:
type: boolean
const: true
safeClean:
type: boolean
const: true
spaces:
type: array
items:
type: object
limits:
type: object
serverVersion:
type: string
stateSchemaMinimum:
type: integer
stateSchemaMaximum:
type: integer
credentialId:
type: string
deviceId:
type: string
credentialActivated:
type: boolean
activationId:
type: string
scopes:
type: array
items:
$ref: '#/components/schemas/CredentialScope'
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'
get:
tags:
- transfer
operationId: discoverDeviceSessions
security:
- deviceBearer: []
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: mappingId
in: query
schema:
type: string
- name: syncSpaceId
in: query
schema:
type: string
- name: activeOnly
in: query
schema:
type: boolean
responses:
'200':
description: Only the current organization, device and credential are returned. Used for recovery after
losing local state.
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/Session'
nextCursor:
type: string
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: Cached counts and lightweight item progress; no file details. Completion independently validates authoritative item state.
content:
application/json:
schema:
$ref: "#/components/schemas/SessionProgress"
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: order
in: query
schema: { type: string, enum: [capture_time] }
description: Stable capture-time pages; use a cursor from the same Session and order.
- name: view
in: query
required: true
schema:
type: string
const: manifest
description: The single resumable original-manifest view. Dynamic status/action filters are rejected.
responses:
'200':
description: Keyset page of original manifest items; membership frozen after plan and item state immutable
after session completion. Save items and cursor atomically; keep live upload work separate from terminal
detail checkpoints.
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceItemPage'
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, heartbeat]
- $ref: "#/components/parameters/IdempotencyKey"
responses:
"200":
description: Session state after completion, abort, or a batched lease heartbeat.
default:
$ref: "#/components/responses/Error"
/api/external/object-sync/items/{itemId}/skip-missing:
post:
tags: [transfer]
operationId: skipMissingSourceItem
description: |
Record a missing local source as skipped with lastError=source_missing. Only
discovered/planned/reserved/uploading may transition; already uploaded or
committed content is preserved. Releases the item lease and attempts bounded
multipart cleanup, leaving failed cleanup to the staging TTL sweeper.
security:
- deviceBearer: []
parameters:
- $ref: "#/components/parameters/ItemID"
- $ref: "#/components/parameters/IdempotencyKey"
responses:
"200":
description: Current item (skipped or a later authoritative upload/commit state).
default:
$ref: "#/components/responses/Error"
/api/external/object-sync/items/{itemId}/cleanup-proof:
post:
tags: [transfer]
operationId: acquireFreshCleanupProof
description: |
Device-scoped, rate-limited and never idempotency-cached. Requires an owned
completed non-preview Session, a committed/unchanged item, matching current
platform head and live BOS HEAD (SHA metadata, size, ETag and version).
Acquires a short object lease. The local daemon must independently prove
the current source identity/content before deleting anything.
security:
- deviceBearer: []
parameters:
- $ref: "#/components/parameters/ItemID"
responses:
"200":
description: Fresh object proof and short-lived lease receipt.
content:
application/json:
schema:
type: object
required: [sessionId, mappingId, syncSpaceId, credentialId, deviceId, itemId, relativePath, targetKey, md5sum, sizeBytes, eTag, versionId, verifiedAt, expiresAt, leaseId, leaseOwner, fencingToken]
properties:
sessionId: { type: string }
mappingId: { type: string }
syncSpaceId: { type: string }
credentialId: { type: string }
deviceId: { type: string }
itemId: { type: string }
relativePath: { type: string }
targetKey: { type: string }
md5sum: { type: string }
sizeBytes: { type: integer, format: int64 }
eTag: { type: string }
versionId: { type: string }
verifiedAt: { type: string, format: date-time }
expiresAt: { type: string, format: date-time }
leaseId: { type: string }
leaseOwner: { type: string }
fencingToken: { type: integer, format: int64 }
default:
$ref: "#/components/responses/Error"
delete:
tags: [transfer]
operationId: releaseCleanupProof
description: Release only the exact cleanup lease/fencing receipt for this device-owned item.
security:
- deviceBearer: []
parameters:
- $ref: "#/components/parameters/ItemID"
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [leaseId, leaseOwner, fencingToken]
properties:
leaseId: { type: string }
leaseOwner: { type: string }
fencingToken: { type: integer, format: int64 }
responses:
"200":
description: Cleanup lease released.
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
- name: targetVersion
in: query
schema:
type: string
responses:
'200':
description: Only strictly newer SemVer candidates; signed v2, server compatibility and rollout are checked.
targetVersion optionally pins a newer candidate.
default:
$ref: '#/components/responses/Error'
/api/object-sync/client-releases/{id}/rollout:
put:
tags:
- release
operationId: updateClientReleaseRollout
parameters:
- $ref: '#/components/parameters/ResourceID'
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- channel
- rolloutPercent
- paused
- expectedRevision
properties:
channel:
type: string
enum:
- canary
- pilot
- stable
rolloutPercent:
type: integer
enum:
- 5
- 20
- 100
paused:
type: boolean
expectedRevision:
type: integer
minimum: 1
responses:
'200':
description: Revision-checked mutable policy; advancement is one stage after 24 active hours.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientRelease'
default:
$ref: '#/components/responses/Error'
/api/object-sync/reconciles:
get:
tags:
- management
operationId: listReconciles
parameters:
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- name: status
in: query
schema:
type: string
responses:
'200':
description: Newest tasks first; durable results and opaque cursor.
content:
application/json:
schema:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/Reconcile'
nextCursor:
type: string
default:
$ref: '#/components/responses/Error'
/api/object-sync/reconciles/{id}:
get:
tags:
- management
operationId: getReconcile
parameters:
- $ref: '#/components/parameters/ResourceID'
responses:
'200':
description: Result.
content:
application/json:
schema:
$ref: '#/components/schemas/Reconcile'
default:
$ref: '#/components/responses/Error'
/api/object-sync/reconciles/{id}/retry:
post:
tags:
- management
operationId: retryReconcile
parameters:
- $ref: '#/components/parameters/ResourceID'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
'202':
description: Re-enqueue failed task, or return already queued work.
content:
application/json:
schema:
$ref: '#/components/schemas/Reconcile'
default:
$ref: '#/components/responses/Error'
/api/object-sync/releases/{id}:
get:
tags:
- release
operationId: getDataRelease
parameters:
- $ref: '#/components/parameters/ResourceID'
responses:
'200':
description: Result.
content:
application/json:
schema:
$ref: '#/components/schemas/DataRelease'
default:
$ref: '#/components/responses/Error'
/api/object-sync/releases/{id}/retry:
post:
tags:
- release
operationId: retryDataRelease
parameters:
- $ref: '#/components/parameters/ResourceID'
- $ref: '#/components/parameters/IdempotencyKey'
responses:
'202':
description: Re-enqueue failed task, or return already queued work.
content:
application/json:
schema:
type: object
properties:
operationId:
type: string
release:
$ref: '#/components/schemas/DataRelease'
default:
$ref: '#/components/responses/Error'
/api/object-sync/releases/{id}/manifest:
get:
tags:
- release
operationId: downloadReleaseManifest
parameters:
- $ref: '#/components/parameters/ResourceID'
responses:
'200':
description: Published manifest is fully spooled and SHA256-checked before HTTP200; failures return an error,
never a partial success.
headers:
X-Content-SHA256:
schema:
type: string
X-Record-Count:
schema:
type: integer
Content-Length:
schema:
type: integer
content:
application/x-ndjson: {}
default:
$ref: '#/components/responses/Error'
/api/object-sync/items/{id}:
get:
tags:
- management
operationId: getManagementItem
parameters:
- $ref: '#/components/parameters/ResourceID'
responses:
'200':
description: Tenant/assigned-space scoped durable item result.
content:
application/json:
schema:
$ref: '#/components/schemas/Item'
default:
$ref: '#/components/responses/Error'
/api/external/object-sync/auth/capabilities:
get:
tags:
- authentication
operationId: getAuthenticationCapabilities
responses:
'200':
description: Public activation-v1 authentication negotiation.
default:
$ref: '#/components/responses/Error'
security: []
/api/external/object-sync/auth/activate:
post:
tags:
- authentication
operationId: activateDeviceCredential
security:
- deviceBearer: []
parameters:
- $ref: '#/components/parameters/IdempotencyKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- activationId
properties:
activationId:
type: string
responses:
'200':
description: After durable credential persistence, activate the pending token; retries are idempotent. Revokes
only previous tokens for this device.
default:
$ref: '#/components/responses/Error'
/api/external/object-sync/client-releases/{version}:
get:
tags:
- release
operationId: getExactSignedClientRelease
security:
- deviceBearer: []
parameters:
- name: version
in: path
schema:
type: string
required: true
responses:
'200':
description: Exact trusted v2 manifest, including paused releases, to establish a verified rollback baseline;
not an upgrade recommendation.
default:
$ref: '#/components/responses/Error'
/api/external/object-sync/items/{itemId}:
get:
tags:
- transfer
operationId: getDeviceItemState
security:
- deviceBearer: []
parameters:
- $ref: '#/components/parameters/ItemID'
responses:
'200':
description: Read current owned item without replaying a mutation, including a closed session.
content:
application/json:
schema:
$ref: '#/components/schemas/DeviceItem'
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 }
name: { type: string }
enabled: { type: boolean }
accessKeyId: { type: string }
secretPreview: { 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
- authenticationProtocol
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
authenticationProtocol:
type: string
const: activation-v1
recoverDevice:
type: boolean
default: false
description: Require an existing device; never create a new identity for a misspelled recovery ID.
AccessKeyAuthenticationResponse:
type: object
required:
- accessToken
- device
- scopes
- activationRequired
- activationId
- expiresAt
properties:
accessToken:
type: string
writeOnly: true
device:
type: object
additionalProperties: true
scopes:
type: array
items:
$ref: '#/components/schemas/CredentialScope'
activationRequired:
type: boolean
const: true
activationId:
type: string
expiresAt:
type: string
format: date-time
SessionCreate:
type: object
additionalProperties: false
required:
- syncSpaceId
- mappingId
- clientVersion
- protocolVersion
properties:
syncSpaceId:
type: string
mappingId:
type: string
clientVersion:
type: string
protocolVersion:
type: string
const: v2
preview:
type: boolean
default: false
description: Plan-only session. Reserve/upload/commit mutations are rejected; client must abort it before
reporting preview complete.
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
preview:
type: boolean
SessionProgress:
allOf:
- $ref: "#/components/schemas/Session"
- type: object
required: [progress]
properties:
progress:
type: object
required: [totalItems, terminalItems]
properties:
totalItems: { type: integer, format: int64, minimum: 0 }
terminalItems: { type: integer, format: int64, minimum: 0 }
description: Each terminal item is counted once, including failed, aborted and expired items. kept_both is not double-counted. Progress is a rebuildable page cache with a 60-second freshness bound; contention can suppress all-terminal hints. The complete operation always reconciles authoritative state.
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, md5sum]
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 }
md5sum: { type: string, pattern: "^[0-9a-fA-F]{32}$" }
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, md5sum, action, status]
properties:
id: { type: string }
sessionId: { type: string }
relativePath: { type: string }
targetKey: { type: string }
logicalTargetKey: { type: string }
sizeBytes: { type: integer, format: int64 }
md5sum: { 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
- manifestVersion
- minimumServerVersion
- minimumStateSchema
- maximumStateSchema
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: v2
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: 'Ed25519 of ordered immutable v2 payload: manifestVersion,id,version,kind,protocolVersion,minimumServerVersion,minimumStateSchema,maximumStateSchema,artifacts,sha256;
map keys lexically sorted. Rollout fields are excluded. Signed requires HTTPS exact four-platform matrix;
preview uses BOS references and empty signature.'
rolloutPercent:
type: integer
minimum: 0
maximum: 100
paused:
type: boolean
createdAt:
type: string
format: date-time
stageChangedAt:
type: string
format: date-time
readOnly: true
manifestVersion:
type: integer
const: 2
minimumStateSchema:
type: integer
minimum: 1
maximumStateSchema:
type: integer
minimum: 1
revision:
type: integer
readOnly: true
organizationId:
type: string
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 }
Reconcile:
type: object
properties:
id:
type: string
operationId:
type: string
syncSpaceId:
type: string
error:
type: string
createdAt:
type: string
updatedAt:
type: string
completedAt:
type: string
status:
type: string
enum:
- pending
- running
- completed
- failed
scanned:
type: integer
format: int64
drifted:
type: integer
format: int64
DataRelease:
type: object
properties:
id:
type: string
syncSpaceId:
type: string
name:
type: string
error:
type: string
manifestKey:
type: string
manifestSha256:
type: string
createdAt:
type: string
updatedAt:
type: string
publishedAt:
type: string
status:
type: string
enum:
- pending
- published
- failed
objectCount:
type: integer
format: int64
totalBytes:
type: integer
format: int64
DeviceItem:
type: object
description: Original device manifest item. Administrative force-overwrite items and unused multipart ledgers
are excluded from resumable metadata pages; multipart initiate/resume returns parts separately.
required:
- id
- sessionId
- clientItemId
- relativePath
- targetKey
- sizeBytes
- md5sum
- action
- status
properties:
id:
type: string
sessionId:
type: string
clientItemId:
type: string
relativePath:
type: string
targetKey:
type: string
logicalTargetKey:
type: string
sizeBytes:
type: integer
md5sum:
type: string
action:
type: string
uploadMode:
type: string
uploadId:
type: string
lastError:
type: string
status:
$ref: '#/components/schemas/ItemStatus'
DeviceItemPage:
type: object
required:
- items
properties:
items:
type: array
items:
$ref: '#/components/schemas/DeviceItem'
nextCursor:
type: string