forked from longtao.wu/droboticflow
Keep MD5 receipts, source identity, live object proofs, and lease expiry checks mandatory. Recheck quarantined content before deletion and cover mixed-session retention on macOS and Linux. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2031 lines
60 KiB
YAML
2031 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 or partial non-preview Session, a committed/unchanged item with a
|
|
complete MD5 receipt, matching current platform head and live BOS HEAD
|
|
(MD5 metadata, size, ETag and version). Other items remain ineligible;
|
|
issuing a proof never changes the Session or item status.
|
|
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
|