Beta
Download

nuFS Public Beta. Compatibility changes and release notes.

REST reference · 0.2.0

REST API

112 operations from the public OpenAPI contract, with request parameters, schemas and documented responses.

Request conventions

Requests use your API origin followed by /v1. Supply the credential required by each operation and replace the placeholders in endpoint examples with your resource IDs and values.

First request
curl "$NUFS_ENDPOINT/v1/drives" \
  -H "Authorization: Bearer $NUFS_TOKEN"
Download OpenAPI 3.1 contract ↗
POST /auth/refreshRotate a refresh token

Authorization

No bearer security requirement is declared for this operation.

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
refresh_tokenRequiredstring minLength: 1
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "refresh_token"
      ],
      "properties": {
        "refresh_token": {
          "type": "string",
          "minLength": 1
        }
      }
    }
  }
}

Documented responses

200 · Rotated session

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/RefreshedSession"
    }
  }
}

401 · invalid_session

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

500 · Session rotation or reuse revocation could not be committed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request POST \
  'https://api.example.test/v1/auth/refresh' \
  -H 'Content-Type: application/json' \
  --data '{"refresh_token":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
RefreshedSession
{
  "type": "object",
  "required": [
    "access_token",
    "access_expires_at",
    "refresh_token",
    "refresh_expires_at"
  ],
  "properties": {
    "access_token": {
      "type": "string",
      "minLength": 1
    },
    "access_expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "refresh_token": {
      "type": "string",
      "minLength": 1
    },
    "refresh_expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
POST /auth/logoutOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Current interactive session revoked

401 · Interactive session required; machine keys return unauthorized

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

500 · Session revocation could not be committed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request POST \
  'https://api.example.test/v1/auth/logout' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
GET /access-keysList active machine credentials

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Active access keys

401 · Interactive session required

Request template

Code
curl --request GET \
  'https://api.example.test/v1/access-keys' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /access-keysCreate a machine credential; its secret is returned exactly once

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
labelRequiredstring minLength: 1 · maxLength: 100
accessRequired"read" | "write" | "admin"
scope_typeOptional"account" | "drive"
scope_idOptionalstring | null format: "uuid"
expires_atOptionalstring | null format: "date-time"
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "label",
        "access"
      ],
      "properties": {
        "label": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "access": {
          "enum": [
            "read",
            "write",
            "admin"
          ]
        },
        "scope_type": {
          "enum": [
            "account",
            "drive"
          ],
          "default": "account"
        },
        "scope_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "expires_at": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time"
        }
      }
    }
  }
}

Documented responses

201 · Access key, one-time bearer secret, and separate S3 access-key ID/signing secret

401 · Interactive session required

Request template

Code
curl --request POST \
  'https://api.example.test/v1/access-keys' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"label":"REPLACE_WITH_VALID_VALUE","access":"read"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

DELETE /access-keys/{key}Revoke a machine credential

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
key · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Revoked

404 · Access key not found

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/access-keys/{key}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /access-keys/delegateMint a narrower child credential from an access key

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

201 · Child key and one-time secret

403 · Scope, authority, or expiry escalation

Request template

Code
curl --request POST \
  'https://api.example.test/v1/access-keys/delegate' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /drivesOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Drives visible to the current identity, filtered by key scope

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /drivesActivate an owned drive from selected storage and seats

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
nameRequiredstring minLength: 1 · maxLength: 100
storage_bytesRequiredinteger minimum: 1 · maximum: 1000000000000000
seatsRequiredinteger minimum: 1 · maximum: 100000
plan_version_idOptionalstringVersion returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription. format: "uuid"
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/DrivePlanSelection"
    }
  }
}

Documented responses

201 · Drive created

403 · Permission or entitlement limit

Request template

Code
curl --request POST \
  'https://api.example.test/v1/drives' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"name":"REPLACE_WITH_VALID_VALUE","storage_bytes":1,"seats":1}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
DrivePlanSelection
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "storage_bytes",
    "seats"
  ],
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000000000000
    },
    "seats": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "plan_version_id": {
      "type": "string",
      "format": "uuid",
      "description": "Version returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription."
    }
  },
  "description": "Storage and member allowances are validated against the published plan catalog. Retrieve /plans before selecting a plan; prices and add-on increments can change."
}
GET /drives/{drive}Operation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Drive

404 · Not found or inaccessible

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

DELETE /drives/{drive}Operation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Drive deleted

404 · Drive inaccessible

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/drives/{drive}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /drives/{drive}/mount-credentialsIssue a short-lived read or write credential for one drive

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

Required · application/json

FieldTypeMeaning and constraints
accessOptional"read" | "write"
ttl_secondsOptionalinteger minimum: 60 · maximum: 86400
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "access": {
          "type": "string",
          "enum": [
            "read",
            "write"
          ],
          "default": "write"
        },
        "ttl_seconds": {
          "type": "integer",
          "minimum": 60,
          "maximum": 86400,
          "default": 3600
        }
      }
    }
  }
}

Documented responses

201 · Temporary credential and one-time secret

403 · Authority cannot be delegated

Request template

Code
curl --request POST \
  'https://api.example.test/v1/drives/{drive}/mount-credentials' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

DELETE /drives/{drive}/mount-credentials/{credential}Revoke an owned temporary credential; scoped parents can revoke only their own direct children

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"
credential · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Revoked, including repeated delivery

403 · A mount credential cannot manage credentials

404 · Credential not found or not owned by this parent

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/drives/{drive}/mount-credentials/{credential}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /drives/{drive}/membersOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Drive members

Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "members"
      ],
      "properties": {
        "members": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/DriveMember"
          }
        }
      }
    }
  }
}

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/members' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
DriveMember
{
  "type": "object",
  "required": [
    "user_id",
    "email",
    "role",
    "created_at"
  ],
  "additionalProperties": false,
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "role": {
      "type": "string",
      "enum": [
        "owner",
        "admin",
        "editor",
        "viewer"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
PATCH /drives/{drive}/members/{member}Change a non-owner member role using interactive admin authority

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
roleRequired"viewer" | "editor" | "admin"
expected_roleRequired"viewer" | "editor" | "admin" | "owner"
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/DriveMemberChange"
    }
  }
}

Documented responses

200 · Updated member

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/DriveMember"
    }
  }
}

400 · Invalid input

401 · Interactive session required

403 · Owner is protected

404 · Drive or member inaccessible

409 · Displayed role no longer matches

Request template

Code
curl --request PATCH \
  'https://api.example.test/v1/drives/{drive}/members/{member}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"role":"viewer","expected_role":"viewer"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
DriveMemberChange
{
  "type": "object",
  "required": [
    "role",
    "expected_role"
  ],
  "additionalProperties": false,
  "properties": {
    "role": {
      "type": "string",
      "enum": [
        "viewer",
        "editor",
        "admin"
      ]
    },
    "expected_role": {
      "type": "string",
      "enum": [
        "viewer",
        "editor",
        "admin",
        "owner"
      ]
    }
  }
}
DriveMember
{
  "type": "object",
  "required": [
    "user_id",
    "email",
    "role",
    "created_at"
  ],
  "additionalProperties": false,
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "role": {
      "type": "string",
      "enum": [
        "owner",
        "admin",
        "editor",
        "viewer"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
DELETE /drives/{drive}/members/{member}Remove non-owner access and invalidate outstanding invitations

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
expected_role · query"viewer" | "editor" | "admin" | "owner"Required.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Membership removed; files remain unchanged

400 · Missing or invalid displayed role

401 · Interactive session required

403 · Owner is protected

404 · Drive or member inaccessible

409 · Displayed role no longer matches

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/drives/{drive}/members/{member}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /drives/{drive}/members/policyRead explicit drive member limit and occupied seats

Interactive owner or admin only. Null means no configured cap. The owner counts as a member. Distinct active invitation emails reserve seats until accepted or unusable.

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Member policy

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/DriveMemberPolicy"
    }
  }
}

400 · Invalid drive ID

401 · Interactive session required

404 · Administration unavailable

500 · Policy read failed

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/members/policy' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
DriveMemberPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "max_members",
    "members",
    "reserved_invitations",
    "revision"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "max_members": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1,
      "maximum": 100000
    },
    "members": {
      "type": "integer",
      "minimum": 1
    },
    "reserved_invitations": {
      "type": "integer",
      "minimum": 0
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
GET /account/audit/retentionRead account audit retention policy

Requires an interactive account owner session. Null keep_days means indefinite retention. Account legal hold blocks cleanup.

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Audit retention policy

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AccountAuditRetentionPolicy"
    }
  }
}

400 · Invalid account ID

401 · Interactive session required

404 · Account administration unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/account/audit/retention' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
AccountAuditRetentionPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "user_id",
    "keep_days",
    "legal_hold",
    "revision"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500,
      "description": "Null retains account audit history indefinitely"
    },
    "legal_hold": {
      "type": "boolean",
      "description": "Account legal hold blocks cleanup and cannot be changed by this endpoint"
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
PUT /account/audit/retentionConfigure account audit retention with a displayed revision guard

Requires an interactive account owner session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
keep_daysRequiredinteger | null minimum: 7 · maximum: 36500
expected_revisionRequiredstringDisplayed audit policy revision pattern: "^[1-9][0-9]*$"
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AuditRetentionUpdate"
    }
  }
}

Documented responses

200 · Updated audit retention policy

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AccountAuditRetentionPolicy"
    }
  }
}

400 · Invalid retention days or displayed revision

401 · Interactive session required

404 · Account administration unavailable

409 · Displayed policy revision is stale

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/account/audit/retention' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"keep_days":null,"expected_revision":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
AuditRetentionUpdate
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "keep_days",
    "expected_revision"
  ],
  "properties": {
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$",
      "description": "Displayed audit policy revision"
    }
  }
}
AccountAuditRetentionPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "user_id",
    "keep_days",
    "legal_hold",
    "revision"
  ],
  "properties": {
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500,
      "description": "Null retains account audit history indefinitely"
    },
    "legal_hold": {
      "type": "boolean",
      "description": "Account legal hold blocks cleanup and cannot be changed by this endpoint"
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
GET /account/auditRead a bounded page of account audit history

Interactive account session required on every page. The authenticated user is the account subject; no supplied account ID is accepted. Drive events and unattributed unknown login attempts are excluded. Anonymous recovery and reuse events retain null actors. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
limit · queryintegerOptional. minimum: 1 · maximum: 200
cursor · querystringOptional. maxLength: 256

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Audit page

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AuditPage"
    }
  }
}

400 · Invalid page limit or account cursor

401 · Interactive session required

404 · Account administration unavailable

500 · Audit history could not be read

Request template

Code
curl --request GET \
  'https://api.example.test/v1/account/audit' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
AuditPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "events",
    "next_cursor"
  ],
  "properties": {
    "events": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "$ref": "#/components/schemas/AuditEvent"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 256
    }
  }
}
AuditEvent
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "actor_user_id",
    "actor_key_id",
    "action",
    "target_type",
    "target_id",
    "outcome",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$",
      "description": "Decimal bigint identity preserved without numeric rounding"
    },
    "actor_user_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "actor_key_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "action": {
      "type": "string"
    },
    "target_type": {
      "type": "string"
    },
    "target_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "outcome": {
      "type": "string",
      "enum": [
        "success",
        "denied",
        "failed"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
GET /drives/{drive}/audit/retentionRead drive audit retention policy

Requires an interactive owner or admin session. Null keep_days means indefinite retention. Shared drive legal hold blocks cleanup.

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Audit retention policy

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AuditRetentionPolicy"
    }
  }
}

400 · Invalid drive ID

401 · Interactive session required

404 · Drive administration unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/audit/retention' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
AuditRetentionPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "keep_days",
    "legal_hold",
    "revision"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500,
      "description": "Null retains audit history indefinitely"
    },
    "legal_hold": {
      "type": "boolean",
      "description": "Shared drive legal hold blocks audit cleanup"
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
PUT /drives/{drive}/audit/retentionConfigure drive audit retention with a displayed revision guard

Requires an interactive owner or admin session. Setting 7–36500 days enables bounded background retirement; null disables retirement. Existing legal hold remains unchanged. Cleanup already committed cannot be undone by a later hold or policy extension.

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

Required · application/json

FieldTypeMeaning and constraints
keep_daysRequiredinteger | null minimum: 7 · maximum: 36500
expected_revisionRequiredstringDisplayed audit policy revision pattern: "^[1-9][0-9]*$"
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AuditRetentionUpdate"
    }
  }
}

Documented responses

200 · Updated audit retention policy

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AuditRetentionPolicy"
    }
  }
}

400 · Invalid retention days or displayed revision

401 · Interactive session required

404 · Drive administration unavailable

409 · Displayed policy revision is stale

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/drives/{drive}/audit/retention' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"keep_days":null,"expected_revision":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
AuditRetentionUpdate
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "keep_days",
    "expected_revision"
  ],
  "properties": {
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$",
      "description": "Displayed audit policy revision"
    }
  }
}
AuditRetentionPolicy
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "keep_days",
    "legal_hold",
    "revision"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "keep_days": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 7,
      "maximum": 36500,
      "description": "Null retains audit history indefinitely"
    },
    "legal_hold": {
      "type": "boolean",
      "description": "Shared drive legal hold blocks audit cleanup"
    },
    "revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
GET /drives/{drive}/auditRead a bounded page of drive audit history

Interactive owner or admin session required on every page. Events descend by identity rather than timestamp. Continue with next_cursor until null; refresh without a cursor for new events. This live traversal is not a database snapshot and late commits may require a refresh. Raw metadata and credential material are omitted.

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"
limit · queryintegerOptional. minimum: 1 · maximum: 200
cursor · querystringOptional. maxLength: 256

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Audit page

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AuditPage"
    }
  }
}

400 · Invalid page limit or drive cursor

401 · Interactive session required

404 · Drive administration unavailable

500 · Audit history could not be read

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/audit' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
AuditPage
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "events",
    "next_cursor"
  ],
  "properties": {
    "events": {
      "type": "array",
      "maxItems": 200,
      "items": {
        "$ref": "#/components/schemas/AuditEvent"
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 256
    }
  }
}
AuditEvent
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "id",
    "actor_user_id",
    "actor_key_id",
    "action",
    "target_type",
    "target_id",
    "outcome",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$",
      "description": "Decimal bigint identity preserved without numeric rounding"
    },
    "actor_user_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "actor_key_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "action": {
      "type": "string"
    },
    "target_type": {
      "type": "string"
    },
    "target_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "outcome": {
      "type": "string",
      "enum": [
        "success",
        "denied",
        "failed"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
GET /drives/{drive}/retentionRead the enforced version-retention policy

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Retention policy

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/retention' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

PUT /drives/{drive}/retentionReplace the enforced version-retention policy

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Updated retention policy

403 · Admin access required

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/drives/{drive}/retention' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /drives/{drive}/reclaimRun safe reachability-based retention and object reclamation

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Reclamation counts and queued physical deletions

403 · Admin access required

Request template

Code
curl --request POST \
  'https://api.example.test/v1/drives/{drive}/reclaim' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /drives/{drive}/invitationsOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

201 · Invitation created

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/InvitationResult"
    }
  }
}

409 · Configured member limit reached

500 · Invitation and audit could not be committed

Request template

Code
curl --request POST \
  'https://api.example.test/v1/drives/{drive}/invitations' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
InvitationResult
{
  "type": "object",
  "required": [
    "invitation"
  ],
  "additionalProperties": false,
  "properties": {
    "invitation": {
      "$ref": "#/components/schemas/DriveInvitation"
    },
    "token": {
      "type": "string",
      "minLength": 1,
      "description": "One-time token exposed only by configured local development delivery"
    }
  }
}
DriveInvitation
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "email",
    "role",
    "expires_at",
    "created_at"
  ],
  "additionalProperties": false,
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "role": {
      "type": "string",
      "enum": [
        "viewer",
        "editor",
        "admin"
      ]
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "accepted_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
POST /invitations/acceptOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Membership added or existing role preserved

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Drive"
    }
  }
}

404 · Invitation expired or revoked or issuer no longer has admin authority

409 · Configured member limit reached

500 · Membership and audit could not be committed

Request template

Code
curl --request POST \
  'https://api.example.test/v1/invitations/accept' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
Drive
{
  "type": "object",
  "required": [
    "id",
    "name",
    "quota_bytes",
    "used_bytes",
    "state",
    "plan",
    "role",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "quota_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64"
    },
    "state": {
      "enum": [
        "active",
        "deleting",
        "deleted"
      ]
    },
    "source_drive_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "source_sequence": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64"
    },
    "plan": {
      "enum": [
        "individual",
        "team",
        "enterprise"
      ]
    },
    "role": {
      "enum": [
        "viewer",
        "editor",
        "admin",
        "owner"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
POST /drives/{drive}/snapshotsCapture one immutable, complete drive state

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

201 · Snapshot created

404 · Drive not found

Request template

Code
curl --request POST \
  'https://api.example.test/v1/drives/{drive}/snapshots' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /drives/{drive}/snapshots/{snapshot}Retrieve a snapshot and its exact namespace references

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"
snapshot · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Snapshot and entries

404 · Snapshot not found

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/snapshots/{snapshot}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /drives/{drive}/branchesOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Branches; an empty drive returns an empty array, never null

Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "branches"
      ],
      "properties": {
        "branches": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/Branch"
          }
        }
      }
    }
  }
}

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/branches' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
Branch
{
  "type": "object",
  "required": [
    "id",
    "source_drive_id",
    "base_snapshot_id",
    "drive_id",
    "name",
    "status",
    "created_by",
    "created_at",
    "updated_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "source_drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "base_snapshot_id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid",
      "description": "Filesystem scope to mount through nufs-engine"
    },
    "name": {
      "type": "string"
    },
    "task_id": {
      "type": [
        "string",
        "null"
      ]
    },
    "status": {
      "enum": [
        "active",
        "integrated",
        "discarded"
      ]
    },
    "created_by": {
      "type": "string",
      "format": "uuid"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "integrated_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "discarded_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    }
  }
}
POST /drives/{drive}/branchesCreate an isolated branch from an explicit drive snapshot

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

Required · application/json

FieldTypeMeaning and constraints
base_snapshot_idRequiredstring format: "uuid"
nameRequiredstring
task_idOptionalstring | null
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "base_snapshot_id",
        "name"
      ],
      "properties": {
        "base_snapshot_id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string"
        },
        "task_id": {
          "type": [
            "string",
            "null"
          ]
        }
      }
    }
  }
}

Documented responses

201 · Persistent branch created

404 · Snapshot not found

Request template

Code
curl --request POST \
  'https://api.example.test/v1/drives/{drive}/branches' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"base_snapshot_id":"00000000-0000-0000-0000-000000000000","name":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /branches/{branch}Operation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
branch · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Branch metadata

404 · Branch not found

Request template

Code
curl --request GET \
  'https://api.example.test/v1/branches/{branch}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /branches/{branch}/changesOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
branch · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Added, modified, and deleted entries relative to the base snapshot

Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "changes"
      ],
      "properties": {
        "changes": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/BranchChange"
          }
        }
      }
    }
  }
}

Request template

Code
curl --request GET \
  'https://api.example.test/v1/branches/{branch}/changes' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
BranchChange
{
  "type": "object",
  "required": [
    "status",
    "branch_entry_id",
    "name",
    "path",
    "kind",
    "logical_size"
  ],
  "properties": {
    "status": {
      "enum": [
        "added",
        "modified",
        "deleted"
      ]
    },
    "base_entry_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "branch_entry_id": {
      "type": "string",
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "path": {
      "type": "string",
      "description": "Current path in the branch"
    },
    "base_path": {
      "type": [
        "string",
        "null"
      ],
      "description": "Path in the immutable base snapshot"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "base_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "actor_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Latest authenticated actor for this branch entry when available"
    }
  }
}
POST /branches/{branch}/access-keyCreate an expiring machine credential scoped to one active branch

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
branch · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

201 · Branch key and one-time secret

401 · Interactive session required

Request template

Code
curl --request POST \
  'https://api.example.test/v1/branches/{branch}/access-key' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /branches/{branch}/integrateAtomically integrate branch changes if target entries still match the base snapshot

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
branch · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Changes integrated

409 · Integration conflict with both states preserved

Request template

Code
curl --request POST \
  'https://api.example.test/v1/branches/{branch}/integrate' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /branches/{branch}/discardMark an active branch discarded without deleting shared immutable content

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
branch · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Branch discarded

409 · Branch is no longer active

Request template

Code
curl --request POST \
  'https://api.example.test/v1/branches/{branch}/discard' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /drives/{drive}/entriesOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
parent_id · querystringOptional. format: "uuid"
as_of · queryintegerOptional. Committed drive sequence to resolve under current permissions; this read does not pin history format: "int64" · minimum: 0

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Directory entries

410 · history_expired — a visible historical file version required by this listing was reclaimed

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/entries' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /drives/{drive}/entriesOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

201 · Entry created

409 · Name conflict

Request template

Code
curl --request POST \
  'https://api.example.test/v1/drives/{drive}/entries' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /entries/{entry}Operation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Entry metadata

Request template

Code
curl --request GET \
  'https://api.example.test/v1/entries/{entry}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

PATCH /entries/{entry}Operation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Renamed or moved

409 · Revision conflict

Request template

Code
curl --request PATCH \
  'https://api.example.test/v1/entries/{entry}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

DELETE /entries/{entry}Operation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
expected_revision · queryintegerRequired.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Tombstoned

409 · Revision conflict

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/entries/{entry}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /files/{file}/versions/{version}/browser-downloadIssue a file/version-scoped HttpOnly download cookie for the current session

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Native browser download path; 15-minute grant rechecks session and membership

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/BrowserDownloadGrant"
    }
  }
}

401 · Interactive session required

404 · Version inaccessible

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/versions/{version}/browser-download' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
BrowserDownloadGrant
{
  "type": "object",
  "required": [
    "download_path",
    "expires_at"
  ],
  "additionalProperties": false,
  "properties": {
    "download_path": {
      "type": "string",
      "pattern": "^/v1/files/[0-9a-f-]{36}/versions/[0-9a-f-]{36}/browser-download$"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
GET /files/{file}/versions/{version}/browser-downloadStream an immutable download using only its scoped cookie

Authorization

Use the authority permitted by this operation. The contract does not declare a per-operation security scheme.

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Exact binary bytes

206 · Exact requested byte range

401 · Grant missing or expired or session revoked

404 · Version or membership unavailable

416 · Invalid byte range

Request template

Code
curl --request GET \
  'https://api.example.test/v1/files/{file}/versions/{version}/browser-download' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /files/{file}/uploadsOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

201 · Signed PUT authorization

409 · Revision conflict

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/uploads' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /files/{file}/chunk-uploadsBegin immutable manifest upload and authorize only missing content chunks

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"

Request body

Required · application/json

FieldTypeMeaning and constraints
expected_revisionRequiredinteger format: "int64"
manifestRequiredChunkManifest
manifest_sha256Requiredstring pattern: "^[0-9a-f]{64}$"
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "expected_revision",
        "manifest",
        "manifest_sha256"
      ],
      "properties": {
        "expected_revision": {
          "type": "integer",
          "format": "int64"
        },
        "manifest": {
          "$ref": "#/components/schemas/ChunkManifest"
        },
        "manifest_sha256": {
          "type": "string",
          "pattern": "^[0-9a-f]{64}$"
        }
      }
    }
  }
}

Documented responses

201 · Upload ID and signed targets for chunks absent from this user's store

409 · Revision conflict

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/chunk-uploads' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"expected_revision":0,"manifest":{"logical_size":0,"chunks":[]},"manifest_sha256":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
ChunkManifest
{
  "type": "object",
  "required": [
    "logical_size",
    "chunks"
  ],
  "properties": {
    "logical_size": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "chunks": {
      "type": "array",
      "maxItems": 1000000,
      "items": {
        "$ref": "#/components/schemas/ChunkRef"
      }
    },
    "base_version_id": {
      "type": "string",
      "format": "uuid",
      "description": "Immutable current version selected at upload creation and pinned through completion"
    }
  }
}
ChunkRef
{
  "type": "object",
  "required": [
    "sha256",
    "size"
  ],
  "properties": {
    "sha256": {
      "type": "string",
      "pattern": "^([0-9a-f]{64})?$",
      "description": "Empty for a zero extent or immutable base reference"
    },
    "size": {
      "type": "integer",
      "format": "int64",
      "minimum": 1
    },
    "zero": {
      "type": "boolean",
      "default": false,
      "description": "True means this extent represents zero bytes without an object"
    },
    "base_offset": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "description": "Reuse this range from base_version_id; excludes zero and a content hash"
    }
  }
}
POST /uploads/{upload}/complete-chunksValidate uploaded chunks and commit immutable manifest version

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
upload · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Chunked version committed

409 · Missing chunks or revision conflict

Request template

Code
curl --request POST \
  'https://api.example.test/v1/uploads/{upload}/complete-chunks' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /uploads/{upload}/resume-chunksRenew signed targets for an uncommitted chunk upload, omitting objects already present and valid

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
upload · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Renewable upload targets

409 · Upload expired or already finalized

Request template

Code
curl --request POST \
  'https://api.example.test/v1/uploads/{upload}/resume-chunks' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /uploads/{upload}/completeOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
upload · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Immutable version committed

409 · Object or revision conflict

Request template

Code
curl --request POST \
  'https://api.example.test/v1/uploads/{upload}/complete' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /files/{file}/downloadOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Signed range-capable GET authorization

Request template

Code
curl --request GET \
  'https://api.example.test/v1/files/{file}/download' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

DELETE /files/{file}/versionsClear earlier versions of one file

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Success

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/HistoryCleanupResult"
    }
  }
}

400 · Invalid input

403 · Drive owner authority is required

404 · Drive or history not found

409 · Revision changed or selected content is protected

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/files/{file}/versions' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
HistoryCleanupResult
{
  "type": "object",
  "description": "Clears earlier versions, keeps current files, and releases allowance immediately. Protected snapshots, forks and live links are skipped. Physical reclamation is asynchronous and preserves replay and active-save pins.",
  "required": [
    "versions_cleared",
    "versions_skipped",
    "bytes_freed",
    "used_bytes"
  ],
  "properties": {
    "versions_cleared": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "versions_skipped": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "bytes_freed": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
GET /files/{file}/versionsOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Immutable version history

Request template

Code
curl --request GET \
  'https://api.example.test/v1/files/{file}/versions' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /files/{file}/bytesStream current file bytes, optionally as one HTTP byte range

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
Range · headerstringOptional.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Full content

206 · Exact requested range

416 · Unsatisfiable range

Request template

Code
curl --request GET \
  'https://api.example.test/v1/files/{file}/bytes' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

HEAD /files/{file}/bytesRead current logical size and version headers without content

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · File metadata headers

Request template

Code
curl --request HEAD \
  'https://api.example.test/v1/files/{file}/bytes' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

PUT /files/{file}/bytesAtomically replace file bytes with bounded binary ingestion

Uploads up to 100 MiB in bounded server chunks. Retry the same body and identity after interruption. A new file entry may remain empty until content commits.

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
If-Match · headerstringRequired.
Idempotency-Key · headerstringRequired. minLength: 1 · maxLength: 200
X-Content-SHA256 · headerstringRequired. pattern: "^[0-9a-f]{64}$"

Request body

Required · application/octet-stream

Code
{
  "application/octet-stream": {
    "schema": {
      "type": "string",
      "format": "binary"
    }
  }
}

Documented responses

200 · Exactly one committed version or its replay

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

400 · Invalid size or checksum or incomplete body

401 · Authentication required

403 · Credential scope or access denied

404 · File or write permission unavailable

409 · Idempotency identity conflict

412 · Base version changed

428 · Version precondition required

503 · Content storage unavailable

507 · Quota exhausted

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/files/{file}/bytes' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
GET /files/{file}/versions/{version}/bytesStream bytes from one immutable historical version

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
version · pathstringRequired. format: "uuid"
Range · headerstringOptional.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Full historical content

206 · Historical range

404 · Version does not belong to file

Request template

Code
curl --request GET \
  'https://api.example.test/v1/files/{file}/versions/{version}/bytes' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

PUT /files/{file}/contentAtomically replace a file through the canonical extent engine

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
If-Match · headerstringRequired. Base version UUID or quoted `none`
Idempotency-Key · headerstringRequired. maxLength: 200

Request body

Required · application/json

FieldTypeMeaning and constraints
dataRequiredstringExact replacement bytes; empty replaces with an empty file
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/ContentMutation"
    }
  }
}

Documented responses

200 · One committed immutable version

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

400 · Invalid input or missing idempotency key

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

409 · Idempotency key belongs to another request

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

412 · version_precondition_failed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

413 · mutation_too_large

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

428 · version_precondition_required

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/files/{file}/content' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"data":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
ContentMutation
{
  "type": "object",
  "required": [
    "data"
  ],
  "properties": {
    "data": {
      "type": "string",
      "contentEncoding": "base64",
      "description": "Exact replacement bytes; empty replaces with an empty file"
    }
  }
}
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
POST /files/{file}/write-atOverwrite bytes at a 64-bit logical offset without replacing unaffected content

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
If-Match · headerstringRequired.
Idempotency-Key · headerstringRequired. minLength: 1 · maxLength: 200

Request body

Required · application/json

FieldTypeMeaning and constraints
offsetRequiredinteger format: "int64" · minimum: 0 · maximum: 9223372036854776000
dataRequiredstring minLength: 1
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/WriteAtMutation"
    }
  }
}

Documented responses

200 · One committed immutable version

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

400 · Invalid input or missing idempotency key

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

409 · Idempotency key belongs to another request

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

412 · version_precondition_failed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

413 · mutation_too_large

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

428 · version_precondition_required

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/write-at' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"offset":0,"data":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
WriteAtMutation
{
  "type": "object",
  "required": [
    "offset",
    "data"
  ],
  "properties": {
    "offset": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "maximum": 9223372036854776000
    },
    "data": {
      "type": "string",
      "contentEncoding": "base64",
      "minLength": 1
    }
  }
}
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
POST /files/{file}/patchApply up to 10,000 non-overlapping overwrite edits as one version

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
If-Match · headerstringRequired.
Idempotency-Key · headerstringRequired. minLength: 1 · maxLength: 200

Request body

Required · application/json

FieldTypeMeaning and constraints
changesRequiredarray<WriteAtMutation>Non-overlapping overwrites; all edits are validated before publication minItems: 1 · maxItems: 10000
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PatchMutation"
    }
  }
}

Documented responses

200 · One committed immutable version

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

400 · Invalid input or missing idempotency key

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

409 · Idempotency key belongs to another request

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

412 · version_precondition_failed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

413 · mutation_too_large

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

428 · version_precondition_required

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/patch' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"changes":[]}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
PatchMutation
{
  "type": "object",
  "required": [
    "changes"
  ],
  "properties": {
    "changes": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10000,
      "items": {
        "$ref": "#/components/schemas/WriteAtMutation"
      },
      "description": "Non-overlapping overwrites; all edits are validated before publication"
    }
  }
}
WriteAtMutation
{
  "type": "object",
  "required": [
    "offset",
    "data"
  ],
  "properties": {
    "offset": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "maximum": 9223372036854776000
    },
    "data": {
      "type": "string",
      "contentEncoding": "base64",
      "minLength": 1
    }
  }
}
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
POST /files/{file}/insertInsert bytes and shift the unchanged suffix through manifest path-copying

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
If-Match · headerstringRequired.
Idempotency-Key · headerstringRequired. minLength: 1 · maxLength: 200

Request body

Required · application/json

FieldTypeMeaning and constraints
offsetRequiredinteger format: "int64" · minimum: 0 · maximum: 9223372036854776000
dataRequiredstring minLength: 1
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/InsertMutation"
    }
  }
}

Documented responses

200 · One committed immutable version

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

400 · Invalid input or missing idempotency key

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

409 · Idempotency key belongs to another request

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

412 · version_precondition_failed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

413 · mutation_too_large

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

428 · version_precondition_required

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/insert' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"offset":0,"data":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
InsertMutation
{
  "type": "object",
  "required": [
    "offset",
    "data"
  ],
  "properties": {
    "offset": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "maximum": 9223372036854776000
    },
    "data": {
      "type": "string",
      "contentEncoding": "base64",
      "minLength": 1
    }
  }
}
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
POST /files/{file}/removeRemove a logical range and close the gap without copying the suffix

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
If-Match · headerstringRequired.
Idempotency-Key · headerstringRequired. minLength: 1 · maxLength: 200

Request body

Required · application/json

FieldTypeMeaning and constraints
offsetRequiredinteger format: "int64" · minimum: 0 · maximum: 9223372036854776000
delete_lengthRequiredinteger format: "int64" · minimum: 1 · maximum: 9223372036854776000
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/RemoveMutation"
    }
  }
}

Documented responses

200 · One committed immutable version

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

400 · Invalid input or missing idempotency key

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

409 · Idempotency key belongs to another request

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

412 · version_precondition_failed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

413 · mutation_too_large

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

428 · version_precondition_required

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/remove' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"offset":0,"delete_length":1}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
RemoveMutation
{
  "type": "object",
  "required": [
    "offset",
    "delete_length"
  ],
  "properties": {
    "offset": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "maximum": 9223372036854776000
    },
    "delete_length": {
      "type": "integer",
      "format": "int64",
      "minimum": 1,
      "maximum": 9223372036854776000
    }
  }
}
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
POST /files/{file}/spliceReplace a logical range with different-length content atomically

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
If-Match · headerstringRequired.
Idempotency-Key · headerstringRequired. minLength: 1 · maxLength: 200

Request body

Required · application/json

FieldTypeMeaning and constraints
offsetRequiredinteger format: "int64" · minimum: 0 · maximum: 9223372036854776000
delete_lengthRequiredinteger format: "int64" · minimum: 0 · maximum: 9223372036854776000
dataRequiredstring
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/SpliceMutation"
    }
  }
}

Documented responses

200 · One committed immutable version

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

400 · Invalid input or missing idempotency key

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

409 · Idempotency key belongs to another request

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

412 · version_precondition_failed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

413 · mutation_too_large

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

428 · version_precondition_required

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/splice' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"offset":0,"delete_length":0,"data":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
SpliceMutation
{
  "type": "object",
  "required": [
    "offset",
    "delete_length",
    "data"
  ],
  "properties": {
    "offset": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "maximum": 9223372036854776000
    },
    "delete_length": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "maximum": 9223372036854776000
    },
    "data": {
      "type": "string",
      "contentEncoding": "base64"
    }
  },
  "anyOf": [
    {
      "properties": {
        "delete_length": {
          "minimum": 1
        }
      }
    },
    {
      "properties": {
        "data": {
          "minLength": 1
        }
      }
    }
  ]
}
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
POST /files/{file}/truncateTruncate or sparse-extend a file atomically

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
If-Match · headerstringRequired.
Idempotency-Key · headerstringRequired. minLength: 1 · maxLength: 200

Request body

Required · application/json

FieldTypeMeaning and constraints
sizeRequiredinteger format: "int64" · minimum: 0 · maximum: 9223372036854776000
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/TruncateMutation"
    }
  }
}

Documented responses

200 · One committed immutable version

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

400 · Invalid input or missing idempotency key

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

409 · Idempotency key belongs to another request

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

412 · version_precondition_failed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

413 · mutation_too_large

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

428 · version_precondition_required

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/Problem"
    }
  }
}

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/truncate' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"size":0}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
TruncateMutation
{
  "type": "object",
  "required": [
    "size"
  ],
  "properties": {
    "size": {
      "type": "integer",
      "format": "int64",
      "minimum": 0,
      "maximum": 9223372036854776000
    }
  }
}
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
Problem
{
  "type": "object",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    }
  }
}
GET /files/{file}/mutations/{key}Resolve the durable result/state of an idempotent mutation

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
key · pathstringRequired.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Mutation intent state

404 · Mutation not found

Request template

Code
curl --request GET \
  'https://api.example.test/v1/files/{file}/mutations/{key}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /files/{file}/versions/{version}/contentResolve a version to a legacy blob URL or chunk manifest

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
version · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Version content descriptor; chunked versions contain a manifest

Request template

Code
curl --request GET \
  'https://api.example.test/v1/files/{file}/versions/{version}/content' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /chunks/download-urlsAuthorize reads of chunks referenced by a specific version

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
file_idRequiredstring format: "uuid"
version_idRequiredstring format: "uuid"
sha256Requiredarray<string> maxItems: 1000
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "file_id",
        "version_id",
        "sha256"
      ],
      "properties": {
        "file_id": {
          "type": "string",
          "format": "uuid"
        },
        "version_id": {
          "type": "string",
          "format": "uuid"
        },
        "sha256": {
          "type": "array",
          "maxItems": 1000,
          "items": {
            "type": "string",
            "pattern": "^[0-9a-f]{64}$"
          }
        }
      }
    }
  }
}

Documented responses

200 · Short-lived authorized chunk URLs

404 · Chunk is not referenced by this version

Request template

Code
curl --request POST \
  'https://api.example.test/v1/chunks/download-urls' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"file_id":"00000000-0000-0000-0000-000000000000","version_id":"00000000-0000-0000-0000-000000000000","sha256":[]}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /files/{file}/versions/{version}/restoreOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
file · pathstringRequired. format: "uuid"
version · pathstringRequired. format: "uuid"

Request body

Required · application/json

FieldTypeMeaning and constraints
expected_revisionRequiredinteger format: "int64"
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "expected_revision"
      ],
      "properties": {
        "expected_revision": {
          "type": "integer",
          "format": "int64"
        }
      }
    }
  }
}

Documented responses

200 · New immutable restore version committed, with updated entry and ETag

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/MutationResult"
    }
  }
}

409 · Revision conflict

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/versions/{version}/restore' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"expected_revision":0}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
MutationResult
{
  "type": "object",
  "required": [
    "entry",
    "version"
  ],
  "properties": {
    "entry": {
      "$ref": "#/components/schemas/Entry"
    },
    "version": {
      "$ref": "#/components/schemas/Version"
    },
    "idempotent_replay": {
      "type": "boolean",
      "default": false
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
Version
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "logical_size",
    "checksum_sha256",
    "storage_format",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "storage_format": {
      "enum": [
        "blob",
        "chunked_v1",
        "extent_v2"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "operation": {
      "enum": [
        "write",
        "write_at",
        "patch",
        "insert",
        "remove",
        "splice",
        "truncate",
        "restore",
        "conflict_preserved"
      ]
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64"
    }
  }
}
GET /drives/{drive}/changesOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"
after · queryintegerOptional. format: "int64" · minimum: 0
epoch · querystringOptional. Epoch from the persisted drive checkpoint format: "uuid"
limit · queryintegerOptional. maximum: 1000

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Ordered incremental change feed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/ChangePage"
    }
  }
}

404 · Drive unavailable to this caller

409 · Cursor requires reconciliation

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/CursorReset"
    }
  }
}

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/changes' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
ChangePage
{
  "type": "object",
  "required": [
    "cursor",
    "epoch",
    "changes"
  ],
  "properties": {
    "cursor": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "epoch": {
      "type": "string",
      "format": "uuid"
    },
    "changes": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "sequence",
          "drive_id",
          "entry_id",
          "operation",
          "revision",
          "created_at"
        ],
        "properties": {
          "sequence": {
            "type": "integer",
            "format": "int64"
          },
          "drive_id": {
            "type": "string",
            "format": "uuid"
          },
          "entry_id": {
            "type": "string",
            "format": "uuid"
          },
          "operation": {
            "type": "string"
          },
          "revision": {
            "type": "integer",
            "format": "int64"
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}
CursorReset
{
  "type": "object",
  "required": [
    "error",
    "reset"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "const": "cursor_reset_required"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "reset": {
      "$ref": "#/components/schemas/CursorBoundary"
    }
  }
}
CursorBoundary
{
  "type": "object",
  "required": [
    "epoch",
    "sequence"
  ],
  "properties": {
    "epoch": {
      "type": "string",
      "format": "uuid"
    },
    "sequence": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
GET /drives/{drive}/reconcilePage a consistent flat namespace at a change-reset boundary

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"
sequence · queryintegerRequired. format: "int64" · minimum: 0
epoch · querystringRequired. format: "uuid"
after_id · querystringOptional. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Up to 500 entries from the same sequence/epoch

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/ReconcilePage"
    }
  }
}

404 · Drive unavailable to this caller

409 · Boundary retired

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/CursorReset"
    }
  }
}

410 · Historical version needed by this boundary was reclaimed

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/reconcile' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
ReconcilePage
{
  "type": "object",
  "required": [
    "boundary",
    "entries",
    "next_entry_id"
  ],
  "properties": {
    "boundary": {
      "$ref": "#/components/schemas/CursorBoundary"
    },
    "entries": {
      "type": "array",
      "maxItems": 500,
      "items": {
        "$ref": "#/components/schemas/Entry"
      }
    },
    "next_entry_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  }
}
CursorBoundary
{
  "type": "object",
  "required": [
    "epoch",
    "sequence"
  ],
  "properties": {
    "epoch": {
      "type": "string",
      "format": "uuid"
    },
    "sequence": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
Entry
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "name",
    "kind",
    "logical_size",
    "revision",
    "created_at",
    "modified_at",
    "deleted"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "name": {
      "type": "string"
    },
    "kind": {
      "enum": [
        "file",
        "folder"
      ]
    },
    "current_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64"
    },
    "checksum_sha256": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision": {
      "type": "integer",
      "format": "int64"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "modified_at": {
      "type": "string",
      "format": "date-time"
    },
    "deleted": {
      "type": "boolean"
    }
  }
}
CursorReset
{
  "type": "object",
  "required": [
    "error",
    "reset"
  ],
  "properties": {
    "error": {
      "type": "object",
      "required": [
        "code",
        "message"
      ],
      "properties": {
        "code": {
          "const": "cursor_reset_required"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "reset": {
      "$ref": "#/components/schemas/CursorBoundary"
    }
  }
}
GET /drives/{drive}/versionsOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"
limit · queryintegerOptional. maximum: 100

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Current and retained versions for drive history

Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "versions"
      ],
      "properties": {
        "versions": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/VersionSummary"
          }
        }
      }
    }
  }
}

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/versions' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
VersionSummary
{
  "type": "object",
  "description": "",
  "required": [
    "version_id",
    "file_id",
    "file_name",
    "logical_size",
    "checksum_sha256",
    "created_at",
    "current",
    "file_revision"
  ],
  "properties": {
    "version_id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "file_name": {
      "type": "string"
    },
    "logical_size": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "checksum_sha256": {
      "type": "string"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "current": {
      "type": "boolean"
    },
    "file_revision": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "storage_format": {
      "type": "string"
    },
    "manifest_sha256": {
      "type": "string"
    },
    "operation": {
      "type": "string"
    },
    "drive_sequence": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
GET /devicesOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Registered devices

Request template

Code
curl --request GET \
  'https://api.example.test/v1/devices' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /devicesOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

201 · Device registered

Request template

Code
curl --request POST \
  'https://api.example.test/v1/devices' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

PUT /devices/currentReport the current desktop installation

Operational inventory is independent of optional usage analytics. Requires an interactive session; binds that session to this account and installation.

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
installation_idRequiredstring format: "uuid"
nameRequiredstring minLength: 1 · maxLength: 100
platformRequired"linux" | "windows" | "macos"
os_versionOptionalstring maxLength: 80
architectureRequired"x86_64" | "arm64"
app_versionRequiredstring pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
release_channelRequired"beta" | "stable" | "preview" | "development"
package_formatRequired"deb" | "rpm" | "exe" | "dmg" | "development"
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "installation_id",
        "name",
        "platform",
        "architecture",
        "app_version",
        "release_channel",
        "package_format"
      ],
      "properties": {
        "installation_id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "platform": {
          "type": "string",
          "enum": [
            "linux",
            "windows",
            "macos"
          ]
        },
        "os_version": {
          "type": "string",
          "maxLength": 80
        },
        "architecture": {
          "type": "string",
          "enum": [
            "x86_64",
            "arm64"
          ]
        },
        "app_version": {
          "type": "string",
          "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$"
        },
        "release_channel": {
          "type": "string",
          "enum": [
            "beta",
            "stable",
            "preview",
            "development"
          ]
        },
        "package_format": {
          "type": "string",
          "enum": [
            "deb",
            "rpm",
            "exe",
            "dmg",
            "development"
          ]
        }
      }
    }
  }
}

Documented responses

200 · Installation registered and session bound

400 · Invalid device details

401 · Interactive sign-in required

409 · Session or device is unavailable; sign in again

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/devices/current' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"installation_id":"00000000-0000-0000-0000-000000000000","name":"REPLACE_WITH_VALID_VALUE","platform":"linux","architecture":"x86_64","app_version":"REPLACE_WITH_VALID_VALUE","release_channel":"beta","package_format":"deb"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /devices/inventoryList the signed-in account's desktop devices

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Account-scoped device inventory, including reported versions and revocation timestamps

Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "devices"
      ],
      "properties": {
        "devices": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string",
                "format": "uuid"
              },
              "name": {
                "type": "string"
              },
              "platform": {
                "type": "string"
              },
              "os_version": {
                "type": "string"
              },
              "architecture": {
                "type": "string"
              },
              "app_version": {
                "type": "string"
              },
              "release_channel": {
                "type": "string"
              },
              "package_format": {
                "type": "string"
              },
              "last_seen_at": {
                "type": "string",
                "format": "date-time"
              },
              "created_at": {
                "type": "string",
                "format": "date-time"
              },
              "version_observed_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              },
              "revoked_at": {
                "type": [
                  "string",
                  "null"
                ],
                "format": "date-time"
              }
            }
          }
        }
      }
    }
  }
}

401 · Interactive sign-in required

Request template

Code
curl --request GET \
  'https://api.example.test/v1/devices/inventory' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /devices/{device}/cursorOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
device · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Cursor acknowledged

Request template

Code
curl --request POST \
  'https://api.example.test/v1/devices/{device}/cursor' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

DELETE /devices/{device}Operation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
device · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Device revoked, including bound sessions and mount credentials

404 · Device not found

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/devices/{device}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /files/{file}/linksInteractive drive administrators select one immutable version. Required expiry is in the future and at most 90 days away. Active links pin that version against retention. The secret is returned once.

Interactive drive administrators select one immutable version. Required expiry is in the future and at most 90 days away. Active links pin that version against retention. The secret is returned once.

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
version_idRequiredstring format: "uuid"
expires_atRequiredstring format: "date-time"
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "version_id",
        "expires_at"
      ],
      "properties": {
        "version_id": {
          "type": "string",
          "format": "uuid"
        },
        "expires_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}

Documented responses

201 · Immutable link and one-time secret

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PublicFileLinkResult"
    }
  }
}

400 · Invalid version or expiry

401 · Interactive session required

404 · File or version unavailable to administrator

Request template

Code
curl --request POST \
  'https://api.example.test/v1/files/{file}/links' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"version_id":"00000000-0000-0000-0000-000000000000","expires_at":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
PublicFileLinkResult
{
  "type": "object",
  "required": [
    "file_link",
    "secret"
  ],
  "properties": {
    "file_link": {
      "$ref": "#/components/schemas/PublicFileLink"
    },
    "secret": {
      "type": "string"
    }
  }
}
PublicFileLink
{
  "type": "object",
  "required": [
    "id",
    "file_id",
    "version_id",
    "file_name",
    "expires_at",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "file_id": {
      "type": "string",
      "format": "uuid"
    },
    "version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "file_name": {
      "type": "string"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "revoked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
POST /public/file-link/downloadExchanges the public bearer for a native-browser download cookie. The cookie is HttpOnly and SameSite Strict; Secure is required except explicit loopback development. It expires in at most 30 minutes and never outlives the link. Bearer material is excluded from the returned URL.

Exchanges the public bearer for a native-browser download cookie. The cookie is HttpOnly and SameSite Strict; Secure is required except explicit loopback development. It expires in at most 30 minutes and never outlives the link. Bearer material is excluded from the returned URL.

Authorization

Use the authority permitted by this operation. publicFileLink

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · File-scoped download path and cookie

Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "download_path"
      ],
      "properties": {
        "download_path": {
          "type": "string"
        }
      }
    }
  }
}

404 · Link unavailable

Request template

Code
curl --request POST \
  'https://api.example.test/v1/public/file-link/download' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /drives/{drive}/upload-requestsInteractive administrators create a fixed-destination request with expiry and file/byte/extension limits. Bearer is returned once. At most ten attempts per allowed file and three times the total byte budget may be reserved across failed attempts.

Interactive administrators create a fixed-destination request with expiry and file/byte/extension limits. Bearer is returned once. At most ten attempts per allowed file and three times the total byte budget may be reserved across failed attempts.

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
parent_idOptionalstring | null format: "uuid"
titleRequiredstring minLength: 1 · maxLength: 100
max_filesRequiredinteger minimum: 1 · maximum: 100
max_file_bytesRequiredinteger minimum: 1 · maximum: 104857600
max_total_bytesRequiredinteger minimum: 1 · maximum: 1073741824
allowed_extensionsOptionalarray<string> maxItems: 20
expires_atRequiredstring format: "date-time"
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/UploadRequestInput"
    }
  }
}

Documented responses

201 · Request and one-time bearer

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/UploadRequestResult"
    }
  }
}

400 · Invalid limits or expiry

401 · Interactive session required

404 · Destination unavailable to administrator

Request template

Code
curl --request POST \
  'https://api.example.test/v1/drives/{drive}/upload-requests' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"title":"REPLACE_WITH_VALID_VALUE","max_files":1,"max_file_bytes":1,"max_total_bytes":1,"expires_at":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
UploadRequestInput
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "title",
    "max_files",
    "max_file_bytes",
    "max_total_bytes",
    "expires_at"
  ],
  "properties": {
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_file_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "max_total_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1073741824
    },
    "allowed_extensions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "pattern": "^\\.[a-z0-9]{1,15}$"
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
UploadRequestResult
{
  "type": "object",
  "required": [
    "upload_request",
    "secret"
  ],
  "properties": {
    "upload_request": {
      "$ref": "#/components/schemas/UploadRequest"
    },
    "secret": {
      "type": "string"
    }
  }
}
UploadRequest
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "parent_id",
    "title",
    "max_files",
    "max_file_bytes",
    "max_total_bytes",
    "allowed_extensions",
    "expires_at",
    "received_files",
    "received_bytes",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_file_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "max_total_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1073741824
    },
    "allowed_extensions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "pattern": "^\\.[a-z0-9]{1,15}$"
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "received_files": {
      "type": "integer",
      "minimum": 0
    },
    "received_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "revoked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
GET /drives/{drive}/upload-requestsOperation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
after · querystringOptional. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Secret-free metadata page

Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "upload_requests",
        "next_cursor"
      ],
      "properties": {
        "upload_requests": {
          "type": "array",
          "maxItems": 100,
          "items": {
            "$ref": "#/components/schemas/UploadRequest"
          }
        },
        "next_cursor": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        }
      }
    }
  }
}

404 · Destination unavailable to administrator

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/upload-requests' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
UploadRequest
{
  "type": "object",
  "required": [
    "id",
    "drive_id",
    "parent_id",
    "title",
    "max_files",
    "max_file_bytes",
    "max_total_bytes",
    "allowed_extensions",
    "expires_at",
    "received_files",
    "received_bytes",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "parent_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_file_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "max_total_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1073741824
    },
    "allowed_extensions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "pattern": "^\\.[a-z0-9]{1,15}$"
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "received_files": {
      "type": "integer",
      "minimum": 0
    },
    "received_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "revoked_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
DELETE /drives/{drive}/upload-requests/{request}Operation reference

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Request revoked; pending publication also denied

404 · Request unavailable to administrator

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/drives/{drive}/upload-requests/{request}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /public/upload-requestOperation reference

Authorization

Use the authority permitted by this operation. uploadRequest

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Public limits without private destination identifiers

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PublicUploadRequest"
    }
  }
}

404 · Request unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/public/upload-request' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
PublicUploadRequest
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "title",
    "max_files",
    "max_file_bytes",
    "max_total_bytes",
    "allowed_extensions",
    "expires_at"
  ],
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "max_files": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "max_file_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 104857600
    },
    "max_total_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1073741824
    },
    "allowed_extensions": {
      "type": "array",
      "maxItems": 20,
      "items": {
        "type": "string",
        "pattern": "^\\.[a-z0-9]{1,15}$"
      }
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
POST /public/upload-request/filesBinary upload to the configured destination only. A stable identity binds encoded single filename, size and SHA-256. Active ten-minute reservations count toward limits. Publication rechecks expiry/revocation/authority/quota and atomically creates one new file/version. A committed retry returns the same receipt without ingesting another body.

Binary upload to the configured destination only. A stable identity binds encoded single filename, size and SHA-256. Active ten-minute reservations count toward limits. Publication rechecks expiry/revocation/authority/quota and atomically creates one new file/version. A committed retry returns the same receipt without ingesting another body.

Authorization

Use the authority permitted by this operation. uploadRequest

Parameters

Name / locationTypeRequirement and constraints
Idempotency-Key · headerstringRequired. minLength: 1 · maxLength: 200
X-File-Name · headerstringRequired. Percent-encoded single filename
X-Content-SHA256 · headerstringRequired. pattern: "^[0-9a-f]{64}$"

Request body

Required · application/octet-stream

Code
{
  "application/octet-stream": {
    "schema": {
      "type": "string",
      "format": "binary",
      "maxLength": 104857600
    }
  }
}

Documented responses

200 · Original committed receipt

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/UploadReceipt"
    }
  }
}

201 · New file committed

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/UploadReceipt"
    }
  }
}

400 · Invalid filename/length or incomplete/incorrect content

404 · Request unavailable

409 · Identity or filename conflict

413 · Request budget exceeded

429 · Active lease or request pacing; Retry-After is one second

503 · Storage unavailable; retry same identity

507 · Destination quota exceeded

Request template

Code
curl --request POST \
  'https://api.example.test/v1/public/upload-request/files' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
UploadReceipt
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "receipt_id",
    "file_name",
    "size_bytes",
    "sha256",
    "idempotent_replay"
  ],
  "properties": {
    "receipt_id": {
      "type": "string",
      "format": "uuid"
    },
    "file_name": {
      "type": "string"
    },
    "size_bytes": {
      "type": "integer",
      "minimum": 0,
      "maximum": 104857600
    },
    "sha256": {
      "type": "string",
      "pattern": "^[0-9a-f]{64}$"
    },
    "idempotent_replay": {
      "type": "boolean"
    }
  }
}
GET /plansPublished monthly plans and add-on terms

Authorization

No bearer security requirement is declared for this operation.

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Checkout mode, USD monthly prices, included seats and per-tier addon rules

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PlanCatalog"
    }
  }
}

Request template

Code
curl --request GET \
  'https://api.example.test/v1/plans'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
PlanCatalog
{
  "type": "object",
  "required": [
    "plans",
    "currency",
    "billing_interval",
    "checkout_mode"
  ],
  "properties": {
    "revision": {
      "type": "string"
    },
    "plans": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PlanOption"
      }
    },
    "currency": {
      "type": "string",
      "const": "USD"
    },
    "billing_interval": {
      "type": "string",
      "const": "month"
    },
    "checkout_mode": {
      "type": "string",
      "enum": [
        "disabled",
        "development"
      ]
    }
  }
}
PlanOption
{
  "type": "object",
  "required": [
    "id",
    "name",
    "storage_bytes",
    "seats",
    "monthly_total_minor",
    "extra_seat_monthly_minor",
    "storage_addon_bytes",
    "storage_addon_monthly_minor",
    "max_seats"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "availability": {
      "type": "string"
    },
    "version_id": {
      "type": "string"
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "seats": {
      "type": "integer",
      "minimum": 0
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0
    },
    "storage_addon_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "storage_addon_monthly_minor": {
      "type": "integer",
      "minimum": 0
    },
    "max_seats": {
      "type": "integer",
      "minimum": 0
    },
    "max_storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "display_order": {
      "type": "integer",
      "minimum": 0
    },
    "extra_seat_monthly_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "featured": {
      "type": "boolean"
    }
  }
}
GET /drives/{drive}/subscriptionOwner-only subscription and storage/seat usage

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Drive subscription

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/DriveSubscription"
    }
  }
}

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/subscription' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
DriveSubscription
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "billing_user_id",
    "status",
    "storage_bytes",
    "seats",
    "members",
    "reserved_invitations",
    "used_bytes",
    "currency",
    "monthly_total_minor",
    "revision",
    "current_period_end",
    "current_period_start",
    "billing_anchor",
    "cycle_number",
    "access_until",
    "pending_monthly_total_minor",
    "cancel_at_period_end",
    "pending_storage_bytes",
    "pending_seats"
  ],
  "properties": {
    "drive_id": {
      "type": "string"
    },
    "billing_user_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "revision": {
      "type": "string"
    },
    "current_period_start": {
      "type": "string",
      "format": "date-time",
      "description": "Start of the current monthly cycle in UTC."
    },
    "billing_anchor": {
      "type": "string",
      "format": "date-time",
      "description": "UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity."
    },
    "cycle_number": {
      "type": "integer",
      "minimum": 1
    },
    "access_until": {
      "type": "string",
      "format": "date-time",
      "description": "Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled."
    },
    "pending_monthly_total_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "current_period_end": {
      "type": "string"
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "seats": {
      "type": "integer",
      "minimum": 0
    },
    "members": {
      "type": "integer",
      "minimum": 0
    },
    "reserved_invitations": {
      "type": "integer",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0
    },
    "cancel_at_period_end": {
      "type": "boolean"
    },
    "pending_storage_bytes": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "pending_seats": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "plan_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "pending_plan_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  }
}
PUT /drives/{drive}/subscriptionDevelopment checkout for subscription changes; production requires billing configuration

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
storage_bytesRequiredinteger minimum: 1 · maximum: 1000000000000000
seatsRequiredinteger minimum: 1 · maximum: 100000
expected_revisionRequiredstring pattern: "^[1-9][0-9]*$"
cancel_at_period_endRequiredboolean
plan_version_idOptionalstringVersion returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription. format: "uuid"
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/SubscriptionChange"
    }
  }
}

Documented responses

200 · Updated subscription; decreases take effect at renewal

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/DriveSubscription"
    }
  }
}

503 · Real billing is not configured; no charge or entitlement change

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/drives/{drive}/subscription' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"storage_bytes":1,"seats":1,"expected_revision":"REPLACE_WITH_VALID_VALUE","cancel_at_period_end":false}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
SubscriptionChange
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "storage_bytes",
    "seats",
    "expected_revision",
    "cancel_at_period_end"
  ],
  "properties": {
    "storage_bytes": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000000000000000
    },
    "seats": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    },
    "cancel_at_period_end": {
      "type": "boolean"
    },
    "plan_version_id": {
      "type": "string",
      "format": "uuid",
      "description": "Version returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription."
    }
  },
  "description": "Storage and member allowances are validated against the published plan catalog. Retrieve /plans before selecting a plan; prices and add-on increments can change."
}
DriveSubscription
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "drive_id",
    "billing_user_id",
    "status",
    "storage_bytes",
    "seats",
    "members",
    "reserved_invitations",
    "used_bytes",
    "currency",
    "monthly_total_minor",
    "revision",
    "current_period_end",
    "current_period_start",
    "billing_anchor",
    "cycle_number",
    "access_until",
    "pending_monthly_total_minor",
    "cancel_at_period_end",
    "pending_storage_bytes",
    "pending_seats"
  ],
  "properties": {
    "drive_id": {
      "type": "string"
    },
    "billing_user_id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "revision": {
      "type": "string"
    },
    "current_period_start": {
      "type": "string",
      "format": "date-time",
      "description": "Start of the current monthly cycle in UTC."
    },
    "billing_anchor": {
      "type": "string",
      "format": "date-time",
      "description": "UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity."
    },
    "cycle_number": {
      "type": "integer",
      "minimum": 1
    },
    "access_until": {
      "type": "string",
      "format": "date-time",
      "description": "Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled."
    },
    "pending_monthly_total_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "current_period_end": {
      "type": "string"
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "seats": {
      "type": "integer",
      "minimum": 0
    },
    "members": {
      "type": "integer",
      "minimum": 0
    },
    "reserved_invitations": {
      "type": "integer",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0
    },
    "cancel_at_period_end": {
      "type": "boolean"
    },
    "pending_storage_bytes": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "pending_seats": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 1
    },
    "plan_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    },
    "pending_plan_version_id": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid"
    }
  }
}
DELETE /drives/{drive}/membershipLeave a shared drive; the owner cannot leave

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

204 · Access revoked; purchased seat quantity is unchanged

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/drives/{drive}/membership' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /public/configPublished plans, installer links and product availability

Authorization

No bearer security requirement is declared for this operation.

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Published plans, installer links and product availability

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PublicConfiguration"
    }
  }
}

503 · Configuration unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/public/config'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
PublicConfiguration
{
  "type": "object",
  "required": [
    "revision",
    "catalog",
    "settings"
  ],
  "properties": {
    "revision": {
      "type": "string"
    },
    "catalog": {
      "$ref": "#/components/schemas/PlanCatalog"
    },
    "settings": {
      "$ref": "#/components/schemas/PlatformSettings"
    }
  }
}
PlanCatalog
{
  "type": "object",
  "required": [
    "plans",
    "currency",
    "billing_interval",
    "checkout_mode"
  ],
  "properties": {
    "revision": {
      "type": "string"
    },
    "plans": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PlanOption"
      }
    },
    "currency": {
      "type": "string",
      "const": "USD"
    },
    "billing_interval": {
      "type": "string",
      "const": "month"
    },
    "checkout_mode": {
      "type": "string",
      "enum": [
        "disabled",
        "development"
      ]
    }
  }
}
PlanOption
{
  "type": "object",
  "required": [
    "id",
    "name",
    "storage_bytes",
    "seats",
    "monthly_total_minor",
    "extra_seat_monthly_minor",
    "storage_addon_bytes",
    "storage_addon_monthly_minor",
    "max_seats"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "availability": {
      "type": "string"
    },
    "version_id": {
      "type": "string"
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "seats": {
      "type": "integer",
      "minimum": 0
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0
    },
    "storage_addon_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "storage_addon_monthly_minor": {
      "type": "integer",
      "minimum": 0
    },
    "max_seats": {
      "type": "integer",
      "minimum": 0
    },
    "max_storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "display_order": {
      "type": "integer",
      "minimum": 0
    },
    "extra_seat_monthly_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "featured": {
      "type": "boolean"
    }
  }
}
PlatformSettings
{
  "type": "object",
  "required": [
    "signup_enabled",
    "checkout_enabled",
    "web_enabled",
    "linux_enabled",
    "macos_enabled",
    "windows_enabled",
    "announcement",
    "support_url",
    "support_email",
    "releases"
  ],
  "properties": {
    "signup_enabled": {
      "type": "boolean"
    },
    "checkout_enabled": {
      "type": "boolean"
    },
    "web_enabled": {
      "type": "boolean"
    },
    "linux_enabled": {
      "type": "boolean"
    },
    "macos_enabled": {
      "type": "boolean"
    },
    "windows_enabled": {
      "type": "boolean"
    },
    "announcement": {
      "type": "string"
    },
    "support_url": {
      "type": "string"
    },
    "support_email": {
      "type": "string"
    },
    "releases": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PlatformRelease"
      }
    },
    "announcement_starts_at": {
      "type": "string"
    },
    "announcement_ends_at": {
      "type": "string"
    }
  }
}
PlatformRelease
{
  "type": "object",
  "required": [
    "platform",
    "architecture",
    "format",
    "version",
    "url",
    "sha256",
    "notes",
    "published"
  ],
  "properties": {
    "platform": {
      "type": "string"
    },
    "architecture": {
      "type": "string"
    },
    "format": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "sha256": {
      "type": "string"
    },
    "sha512": {
      "type": "string",
      "description": "Base64 SHA-512 for desktop updater verification."
    },
    "minimum_supported_version": {
      "type": "string",
      "description": "Older matching desktop clients must update after pending saves finish."
    },
    "update_reason": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "published": {
      "type": "boolean"
    },
    "channel": {
      "type": "string",
      "enum": [
        "stable",
        "preview",
        "beta"
      ]
    },
    "file_size": {
      "type": "integer",
      "minimum": 0
    },
    "signing": {
      "type": "string",
      "enum": [
        "unsigned",
        "authenticode",
        "notarized",
        "not_applicable"
      ]
    },
    "verification": {
      "type": "string",
      "enum": [
        "not_checked",
        "passed",
        "failed"
      ]
    }
  }
}
GET /platform/configPlatform administrator draft and published configuration

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Platform administrator draft and published configuration

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PlatformConfiguration"
    }
  }
}

401 · Session required

403 · Platform administrator access required

503 · Configuration unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/platform/config' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
PlatformConfiguration
{
  "type": "object",
  "required": [
    "revision",
    "published",
    "draft"
  ],
  "properties": {
    "revision": {
      "type": "string"
    },
    "published": {
      "$ref": "#/components/schemas/PlatformDocument"
    },
    "draft": {
      "$ref": "#/components/schemas/PlatformDocument"
    }
  }
}
PlatformDocument
{
  "type": "object",
  "required": [
    "plans",
    "settings"
  ],
  "properties": {
    "plans": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PlanOption"
      }
    },
    "settings": {
      "$ref": "#/components/schemas/PlatformSettings"
    }
  }
}
PlanOption
{
  "type": "object",
  "required": [
    "id",
    "name",
    "storage_bytes",
    "seats",
    "monthly_total_minor",
    "extra_seat_monthly_minor",
    "storage_addon_bytes",
    "storage_addon_monthly_minor",
    "max_seats"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "availability": {
      "type": "string"
    },
    "version_id": {
      "type": "string"
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "seats": {
      "type": "integer",
      "minimum": 0
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0
    },
    "storage_addon_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "storage_addon_monthly_minor": {
      "type": "integer",
      "minimum": 0
    },
    "max_seats": {
      "type": "integer",
      "minimum": 0
    },
    "max_storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "display_order": {
      "type": "integer",
      "minimum": 0
    },
    "extra_seat_monthly_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "featured": {
      "type": "boolean"
    }
  }
}
PlatformSettings
{
  "type": "object",
  "required": [
    "signup_enabled",
    "checkout_enabled",
    "web_enabled",
    "linux_enabled",
    "macos_enabled",
    "windows_enabled",
    "announcement",
    "support_url",
    "support_email",
    "releases"
  ],
  "properties": {
    "signup_enabled": {
      "type": "boolean"
    },
    "checkout_enabled": {
      "type": "boolean"
    },
    "web_enabled": {
      "type": "boolean"
    },
    "linux_enabled": {
      "type": "boolean"
    },
    "macos_enabled": {
      "type": "boolean"
    },
    "windows_enabled": {
      "type": "boolean"
    },
    "announcement": {
      "type": "string"
    },
    "support_url": {
      "type": "string"
    },
    "support_email": {
      "type": "string"
    },
    "releases": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PlatformRelease"
      }
    },
    "announcement_starts_at": {
      "type": "string"
    },
    "announcement_ends_at": {
      "type": "string"
    }
  }
}
PlatformRelease
{
  "type": "object",
  "required": [
    "platform",
    "architecture",
    "format",
    "version",
    "url",
    "sha256",
    "notes",
    "published"
  ],
  "properties": {
    "platform": {
      "type": "string"
    },
    "architecture": {
      "type": "string"
    },
    "format": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "sha256": {
      "type": "string"
    },
    "sha512": {
      "type": "string",
      "description": "Base64 SHA-512 for desktop updater verification."
    },
    "minimum_supported_version": {
      "type": "string",
      "description": "Older matching desktop clients must update after pending saves finish."
    },
    "update_reason": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "published": {
      "type": "boolean"
    },
    "channel": {
      "type": "string",
      "enum": [
        "stable",
        "preview",
        "beta"
      ]
    },
    "file_size": {
      "type": "integer",
      "minimum": 0
    },
    "signing": {
      "type": "string",
      "enum": [
        "unsigned",
        "authenticode",
        "notarized",
        "not_applicable"
      ]
    },
    "verification": {
      "type": "string",
      "enum": [
        "not_checked",
        "passed",
        "failed"
      ]
    }
  }
}
PUT /platform/configSave a draft or publish product settings; platform administrator only

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
expected_revisionRequiredstring pattern: "^[1-9][0-9]*$"
documentRequiredPlatformDocument
publishRequiredboolean
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "expected_revision",
        "document",
        "publish"
      ],
      "properties": {
        "expected_revision": {
          "type": "string",
          "pattern": "^[1-9][0-9]*$"
        },
        "document": {
          "$ref": "#/components/schemas/PlatformDocument"
        },
        "publish": {
          "type": "boolean"
        }
      }
    }
  }
}

Documented responses

200 · Updated configuration

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/PlatformConfiguration"
    }
  }
}

400 · Invalid settings

401 · Session required

403 · Platform administrator access required

409 · Revision changed; reload before editing

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/platform/config' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"expected_revision":"REPLACE_WITH_VALID_VALUE","document":{"plans":[],"settings":{"signup_enabled":false,"checkout_enabled":false,"web_enabled":false,"linux_enabled":false,"macos_enabled":false,"windows_enabled":false,"announcement":"REPLACE_WITH_VALID_VALUE","support_url":"REPLACE_WITH_VALID_VALUE","support_email":"REPLACE_WITH_VALID_VALUE","releases":[]}},"publish":false}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
PlatformDocument
{
  "type": "object",
  "required": [
    "plans",
    "settings"
  ],
  "properties": {
    "plans": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PlanOption"
      }
    },
    "settings": {
      "$ref": "#/components/schemas/PlatformSettings"
    }
  }
}
PlanOption
{
  "type": "object",
  "required": [
    "id",
    "name",
    "storage_bytes",
    "seats",
    "monthly_total_minor",
    "extra_seat_monthly_minor",
    "storage_addon_bytes",
    "storage_addon_monthly_minor",
    "max_seats"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "availability": {
      "type": "string"
    },
    "version_id": {
      "type": "string"
    },
    "storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "seats": {
      "type": "integer",
      "minimum": 0
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0
    },
    "storage_addon_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "storage_addon_monthly_minor": {
      "type": "integer",
      "minimum": 0
    },
    "max_seats": {
      "type": "integer",
      "minimum": 0
    },
    "max_storage_bytes": {
      "type": "integer",
      "minimum": 0
    },
    "display_order": {
      "type": "integer",
      "minimum": 0
    },
    "extra_seat_monthly_minor": {
      "type": [
        "integer",
        "null"
      ],
      "minimum": 0
    },
    "featured": {
      "type": "boolean"
    }
  }
}
PlatformSettings
{
  "type": "object",
  "required": [
    "signup_enabled",
    "checkout_enabled",
    "web_enabled",
    "linux_enabled",
    "macos_enabled",
    "windows_enabled",
    "announcement",
    "support_url",
    "support_email",
    "releases"
  ],
  "properties": {
    "signup_enabled": {
      "type": "boolean"
    },
    "checkout_enabled": {
      "type": "boolean"
    },
    "web_enabled": {
      "type": "boolean"
    },
    "linux_enabled": {
      "type": "boolean"
    },
    "macos_enabled": {
      "type": "boolean"
    },
    "windows_enabled": {
      "type": "boolean"
    },
    "announcement": {
      "type": "string"
    },
    "support_url": {
      "type": "string"
    },
    "support_email": {
      "type": "string"
    },
    "releases": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/PlatformRelease"
      }
    },
    "announcement_starts_at": {
      "type": "string"
    },
    "announcement_ends_at": {
      "type": "string"
    }
  }
}
PlatformRelease
{
  "type": "object",
  "required": [
    "platform",
    "architecture",
    "format",
    "version",
    "url",
    "sha256",
    "notes",
    "published"
  ],
  "properties": {
    "platform": {
      "type": "string"
    },
    "architecture": {
      "type": "string"
    },
    "format": {
      "type": "string"
    },
    "version": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "sha256": {
      "type": "string"
    },
    "sha512": {
      "type": "string",
      "description": "Base64 SHA-512 for desktop updater verification."
    },
    "minimum_supported_version": {
      "type": "string",
      "description": "Older matching desktop clients must update after pending saves finish."
    },
    "update_reason": {
      "type": "string"
    },
    "notes": {
      "type": "string"
    },
    "published": {
      "type": "boolean"
    },
    "channel": {
      "type": "string",
      "enum": [
        "stable",
        "preview",
        "beta"
      ]
    },
    "file_size": {
      "type": "integer",
      "minimum": 0
    },
    "signing": {
      "type": "string",
      "enum": [
        "unsigned",
        "authenticode",
        "notarized",
        "not_applicable"
      ]
    },
    "verification": {
      "type": "string",
      "enum": [
        "not_checked",
        "passed",
        "failed"
      ]
    }
  }
}
PlatformConfiguration
{
  "type": "object",
  "required": [
    "revision",
    "published",
    "draft"
  ],
  "properties": {
    "revision": {
      "type": "string"
    },
    "published": {
      "$ref": "#/components/schemas/PlatformDocument"
    },
    "draft": {
      "$ref": "#/components/schemas/PlatformDocument"
    }
  }
}
GET /platform/auditLatest 100 product configuration changes; platform administrator only

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Audit records, newest first

Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "properties": {
        "items": {
          "type": "array",
          "items": {
            "$ref": "#/components/schemas/PlatformAuditEntry"
          }
        }
      }
    }
  }
}

401 · Session required

403 · Platform administrator access required

Request template

Code
curl --request GET \
  'https://api.example.test/v1/platform/audit' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
PlatformAuditEntry
{
  "type": "object",
  "required": [
    "id",
    "user_id",
    "action",
    "revision",
    "before",
    "after",
    "created_at"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "user_id": {
      "type": "string",
      "format": "uuid"
    },
    "action": {
      "type": "string"
    },
    "revision": {
      "type": "string"
    },
    "before": {},
    "after": {},
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "resource_type": {
      "type": "string"
    },
    "resource_id": {
      "type": "string"
    },
    "reason": {
      "type": "string"
    }
  }
}
GET /platform/resourcesRead independently versioned plans, releases and settings

Authorization

Use the authority permitted by this operation. bearer

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/platform/resources' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

PUT /platform/resources/{kind}/{id}Save only this resource; preserve unrelated edits and existing subscription terms

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
kind · pathstringRequired.
id · pathstringRequired.

Request body

Required · application/json

FieldTypeMeaning and constraints
expected_revisionRequiredstring
valueRequiredschema
activateOptionalboolean
removeOptionalboolean
reasonOptionalstring maxLength: 500
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "expected_revision",
        "value"
      ],
      "properties": {
        "expected_revision": {
          "type": "string"
        },
        "value": {},
        "activate": {
          "type": "boolean"
        },
        "remove": {
          "type": "boolean"
        },
        "reason": {
          "type": "string",
          "maxLength": 500
        }
      }
    }
  }
}

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/platform/resources/{kind}/{id}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"expected_revision":"REPLACE_WITH_VALID_VALUE","value":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /platform/overviewCustomer, storage and request totals

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
start · querystringOptional.
end · querystringOptional.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/platform/overview' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /platform/growthDaily registrations and observed activity

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
start · querystringOptional.
end · querystringOptional.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/platform/growth' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /platform/healthDependency health, database pool and recorded operator checks

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
start · querystringOptional.
end · querystringOptional.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/platform/health' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /platform/lists/{kind}Search and paginate safe administration records

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
kind · pathstringRequired.
q · querystringOptional.
status · querystringOptional.
id · querystringOptional.
page · querystringOptional.
page_size · querystringOptional.
start · querystringOptional.
end · querystringOptional.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/platform/lists/{kind}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

GET /platform/details/{kind}/{id}Read customer or drive details without credentials or file bytes

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
kind · pathstringRequired.
id · pathstringRequired.
start · querystringOptional.
end · querystringOptional.

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request GET \
  'https://api.example.test/v1/platform/details/{kind}/{id}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /platform/actions/{kind}/{id}Apply a role-authorized support action with a mandatory audit reason

Subscription changes require full or billing administrator access. No action records a payment or sends email.

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
kind · pathstringRequired.
id · pathstringRequired.

Request body

Required · application/json

FieldTypeMeaning and constraints
actionRequiredstring
reasonRequiredstring minLength: 1 · maxLength: 500
roleOptional"full" | "support" | "billing" | "analyst"
expected_revisionOptionalstringRequired for subscription actions; obtain from the subscription detail record.
valueOptionalAdminSubscriptionTerms
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "action",
        "reason"
      ],
      "properties": {
        "action": {
          "type": "string"
        },
        "reason": {
          "type": "string",
          "minLength": 1,
          "maxLength": 500
        },
        "role": {
          "type": "string",
          "enum": [
            "full",
            "support",
            "billing",
            "analyst"
          ]
        },
        "expected_revision": {
          "type": "string",
          "description": "Required for subscription actions; obtain from the subscription detail record."
        },
        "value": {
          "$ref": "#/components/schemas/AdminSubscriptionTerms"
        }
      }
    }
  }
}

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request POST \
  'https://api.example.test/v1/platform/actions/{kind}/{id}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"action":"REPLACE_WITH_VALID_VALUE","reason":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
AdminSubscriptionTerms
{
  "type": "object",
  "description": "Values for subscriptions administration. edit-allowances sets storage_bytes and seats while keeping price and plan. change-plan selects a published immutable plan_version_id (or plan_id with plan_revision). custom-subscription sets storage_bytes, seats and monthly_total_minor, including zero. These use timing now or next-cycle. adjust-validity uses access_until (an RFC 3339 future timestamp) to move validity earlier or later without changing billing terms. Automatic renewal is controlled separately by cancel-renewal and resume-renewal; changing validity does not enable renewal.",
  "properties": {
    "storage_bytes": {
      "type": "integer",
      "minimum": 1000000000,
      "maximum": 1000000000000000
    },
    "seats": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100000
    },
    "monthly_total_minor": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000000,
      "description": "Recurring monthly USD price in cents, independent of allowances."
    },
    "plan_version_id": {
      "type": "string"
    },
    "plan_id": {
      "type": "string"
    },
    "plan_revision": {
      "type": "string"
    },
    "timing": {
      "type": "string",
      "enum": [
        "now",
        "next-cycle"
      ]
    },
    "cycles": {
      "type": "integer",
      "minimum": 1,
      "maximum": 120
    }
  }
}
POST /platform/reports/{kind}Record an operator backup or recovery result

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
kind · pathstringRequired.

Request body

Required · application/json

FieldTypeMeaning and constraints
statusRequired"passed" | "failed"
reasonRequiredstring
detailsRequiredobject additionalProperties: false
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "status",
        "reason",
        "details"
      ],
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "passed",
            "failed"
          ]
        },
        "reason": {
          "type": "string"
        },
        "details": {
          "type": "object",
          "properties": {
            "summary": {
              "type": "string"
            },
            "reference": {
              "type": "string"
            }
          },
          "additionalProperties": false
        }
      }
    }
  }
}

Documented responses

200 · Administrator result

Code
{
  "application/json": {
    "schema": {
      "type": "object"
    }
  }
}

400 · Invalid fields or date range

401 · Session required

403 · Insufficient platform role

409 · Record changed; reload

503 · Administration temporarily unavailable

Request template

Code
curl --request POST \
  'https://api.example.test/v1/platform/reports/{kind}' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"status":"passed","reason":"REPLACE_WITH_VALID_VALUE","details":{}}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

POST /auth/otp/requestEmail a sign-in code

Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.

Authorization

No bearer security requirement is declared for this operation.

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
emailRequiredstring format: "email" · maxLength: 254
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "email"
      ],
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "maxLength": 254
        }
      }
    }
  }
}

Documented responses

202 · Challenge accepted

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/OTPChallenge"
    }
  }
}

400 · Invalid input

401 · Invalid, expired, consumed or exhausted code

429 · Rate limited; wait before trying again

503 · Email delivery unavailable

Request template

Code
curl --request POST \
  'https://api.example.test/v1/auth/otp/request' \
  -H 'Content-Type: application/json' \
  --data '{"email":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
OTPChallenge
{
  "type": "object",
  "required": [
    "challenge_id",
    "expires_at",
    "resend_after"
  ],
  "properties": {
    "challenge_id": {
      "type": "string",
      "format": "uuid"
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "resend_after": {
      "type": "integer",
      "minimum": 0
    },
    "code": {
      "type": "string",
      "description": "Only exposed by explicitly configured local integration fixtures. Never returned in production."
    }
  }
}
POST /auth/otp/verifySign in with an email code; create an account if needed

Codes expire after 10 minutes, are single use, and allow five attempts. Resending invalidates the previous code. Requests have a 60-second cooldown and a per-email and per-IP rate limit. Storage is activated separately.

Authorization

No bearer security requirement is declared for this operation.

Parameters

No parameter schema is declared here. Path identities shown in the URL must still be supplied.

Request body

Required · application/json

FieldTypeMeaning and constraints
challenge_idRequiredstring format: "uuid"
codeRequiredstring pattern: "^[0-9]{6}$"
Code
{
  "application/json": {
    "schema": {
      "type": "object",
      "required": [
        "challenge_id",
        "code"
      ],
      "properties": {
        "challenge_id": {
          "type": "string",
          "format": "uuid"
        },
        "code": {
          "type": "string",
          "pattern": "^[0-9]{6}$"
        }
      }
    }
  }
}

Documented responses

200 · Session created

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/AuthSession"
    }
  }
}

400 · Invalid input

401 · Invalid, expired, consumed or exhausted code

429 · Rate limited; wait before trying again

503 · Email delivery unavailable

Request template

Code
curl --request POST \
  'https://api.example.test/v1/auth/otp/verify' \
  -H 'Content-Type: application/json' \
  --data '{"challenge_id":"00000000-0000-0000-0000-000000000000","code":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
AuthSession
{
  "type": "object",
  "required": [
    "user",
    "access_token",
    "access_expires_at",
    "refresh_token",
    "refresh_expires_at"
  ],
  "properties": {
    "user": {
      "$ref": "#/components/schemas/User"
    },
    "access_token": {
      "type": "string",
      "minLength": 1
    },
    "access_expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "refresh_token": {
      "type": "string",
      "minLength": 1
    },
    "refresh_expires_at": {
      "type": "string",
      "format": "date-time"
    }
  }
}
User
{
  "type": "object",
  "required": [
    "id",
    "email"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "email": {
      "type": "string",
      "format": "email"
    }
  }
}
GET /drives/{drive}/historyRead history settings and storage breakdown

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Success

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/FileHistoryPolicy"
    }
  }
}

400 · Invalid input

403 · Drive owner authority is required

404 · Drive or history not found

409 · Revision changed or selected content is protected

Request template

Code
curl --request GET \
  'https://api.example.test/v1/drives/{drive}/history' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
FileHistoryPolicy
{
  "type": "object",
  "description": "Drive-wide history is off by default. Used storage counts current and retained historical contents with content deduplication.",
  "required": [
    "drive_id",
    "enabled",
    "revision",
    "current_bytes",
    "history_bytes",
    "used_bytes",
    "historical_versions"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "enabled": {
      "type": "boolean"
    },
    "revision": {
      "type": "string"
    },
    "current_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "history_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "historical_versions": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
PUT /drives/{drive}/historyEnable or disable history for future edits

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

Required · application/json

FieldTypeMeaning and constraints
enabledRequiredboolean
expected_revisionRequiredstring pattern: "^[1-9][0-9]*$"
Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/FileHistoryUpdate"
    }
  }
}

Documented responses

200 · Success

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/FileHistoryPolicy"
    }
  }
}

400 · Invalid input

403 · Drive owner authority is required

404 · Drive or history not found

409 · Revision changed or selected content is protected

Request template

Code
curl --request PUT \
  'https://api.example.test/v1/drives/{drive}/history' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL' \
  -H 'Content-Type: application/json' \
  --data '{"enabled":false,"expected_revision":"REPLACE_WITH_VALID_VALUE"}'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
FileHistoryPolicy
{
  "type": "object",
  "description": "Drive-wide history is off by default. Used storage counts current and retained historical contents with content deduplication.",
  "required": [
    "drive_id",
    "enabled",
    "revision",
    "current_bytes",
    "history_bytes",
    "used_bytes",
    "historical_versions"
  ],
  "properties": {
    "drive_id": {
      "type": "string",
      "format": "uuid"
    },
    "enabled": {
      "type": "boolean"
    },
    "revision": {
      "type": "string"
    },
    "current_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "history_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "historical_versions": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}
FileHistoryUpdate
{
  "type": "object",
  "description": "Owner-only setting. Disabling retains existing history; only future superseded revisions stop counting toward history.",
  "required": [
    "enabled",
    "expected_revision"
  ],
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "expected_revision": {
      "type": "string",
      "pattern": "^[1-9][0-9]*$"
    }
  }
}
DELETE /drives/{drive}/historyClear all earlier versions in this drive

Authorization

Use the authority permitted by this operation. bearer

Parameters

Name / locationTypeRequirement and constraints
drive · pathstringRequired. format: "uuid"

Request body

No request-body schema is declared in the contract for this operation. This does not imply an empty body is sufficient for every endpoint.

Documented responses

200 · Success

Code
{
  "application/json": {
    "schema": {
      "$ref": "#/components/schemas/HistoryCleanupResult"
    }
  }
}

400 · Invalid input

403 · Drive owner authority is required

404 · Drive or history not found

409 · Revision changed or selected content is protected

Request template

Code
curl --request DELETE \
  'https://api.example.test/v1/drives/{drive}/history' \
  -H 'Authorization: Bearer REPLACE_WITH_OPERATION_CREDENTIAL'

Add all required query/header parameters shown above. Binary bodies, authentication inputs and omitted schemas require the corresponding operation’s input; this template is not a ready-to-run credentialed request.

Request and response fields
HistoryCleanupResult
{
  "type": "object",
  "description": "Clears earlier versions, keeps current files, and releases allowance immediately. Protected snapshots, forks and live links are skipped. Physical reclamation is asynchronous and preserves replay and active-save pins.",
  "required": [
    "versions_cleared",
    "versions_skipped",
    "bytes_freed",
    "used_bytes"
  ],
  "properties": {
    "versions_cleared": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "versions_skipped": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "bytes_freed": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    },
    "used_bytes": {
      "type": "integer",
      "format": "int64",
      "minimum": 0
    }
  }
}