Contract reference

Models and schemas

Field types, required values and constraints from the OpenAPI contract. SDKs may wrap or unwrap endpoint envelopes; consult each method’s return type.

References link to named schemas below. Nullable values are distinct from omitted optional fields. Audit IDs preserve decimal-string precision. Binary byte results are not JSON model objects.

65 schemas

AdminSubscriptionTermsValues 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.

Field	Type	Meaning and constraints
`storage_bytes`Optional	integer	minimum: 1000000000 · maximum: 1000000000000000
`seats`Optional	integer	minimum: 1 · maximum: 100000
`monthly_total_minor`Optional	integer	Recurring monthly USD price in cents, independent of allowances. minimum: 0 · maximum: 1000000000000
`plan_version_id`Optional	string
`plan_id`Optional	string
`plan_revision`Optional	string
`timing`Optional	"now" \| "next-cycle"
`cycles`Optional	integer	minimum: 1 · maximum: 120

Full schema

Code

{
  "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
    }
  }
}

Field	Type	Meaning and constraints
`drive_id`Required	string
`billing_user_id`Required	string
`status`Required	string
`currency`Required	string
`revision`Required	string
`current_period_start`Required	string	Start of the current monthly cycle in UTC. format: "date-time"
`billing_anchor`Required	string	UTC day and time used to calculate calendar-month boundaries. Reset to the new date when an administrator adjusts validity. format: "date-time"
`cycle_number`Required	integer	minimum: 1
`access_until`Required	string	Authoritative validity date and next renewal boundary. Free subscriptions renew when automatic renewal is enabled. format: "date-time"
`pending_monthly_total_minor`Required	integer \| null	minimum: 0
`current_period_end`Required	string
`storage_bytes`Required	integer	minimum: 0
`seats`Required	integer	minimum: 0
`members`Required	integer	minimum: 0
`reserved_invitations`Required	integer	minimum: 0
`used_bytes`Required	integer	minimum: 0
`monthly_total_minor`Required	integer	minimum: 0
`cancel_at_period_end`Required	boolean
`pending_storage_bytes`Required	integer \| null	minimum: 1
`pending_seats`Required	integer \| null	minimum: 1
`plan_version_id`Optional	string \| null	format: "uuid"
`pending_plan_version_id`Optional	string \| null	format: "uuid"

Field	Type	Meaning and constraints
`name`Required	string	minLength: 1 · maxLength: 100
`storage_bytes`Required	integer	minimum: 1 · maximum: 1000000000000000
`seats`Required	integer	minimum: 1 · maximum: 100000
`plan_version_id`Optional	string	Version returned by GET /plans. Rejects stale terms with 409; omit when cancelling an existing subscription. format: "uuid"

Field	Type	Meaning and constraints
`kind`Required	"complete"
`events`Required	string	Count of events written by this successful export pattern: "^(0\|[1-9][0-9]*)$"

Field	Type	Meaning and constraints
`user_id`Required	string	format: "uuid"
`keep_days`Required	integer \| null	Null retains account audit history indefinitely minimum: 7 · maximum: 36500
`legal_hold`Required	boolean	Account legal hold blocks cleanup and cannot be changed by this endpoint
`revision`Required	string	pattern: "^[1-9][0-9]*$"

Field	Type	Meaning and constraints
`keep_days`Required	integer \| null	minimum: 7 · maximum: 36500
`expected_revision`Required	string	Displayed audit policy revision pattern: "^[1-9][0-9]*$"

Field	Type	Meaning and constraints
`id`Required	string	Decimal bigint identity preserved without numeric rounding pattern: "^[1-9][0-9]*$"
`actor_user_id`Required	string \| null	format: "uuid"
`actor_key_id`Required	string \| null	format: "uuid"
`action`Required	string
`target_type`Required	string
`target_id`Required	string \| null
`outcome`Required	"success" \| "denied" \| "failed"
`created_at`Required	string	format: "date-time"

Field	Type	Meaning and constraints
`events`Required	array<AuditEvent>	maxItems: 200
`next_cursor`Required	string \| null	maxLength: 256

Field	Type	Meaning and constraints
`invitation`Required	DriveInvitation
`token`Optional	string	One-time token exposed only by configured local development delivery minLength: 1

Field	Type	Meaning and constraints
`role`Required	"viewer" \| "editor" \| "admin"
`expected_role`Required	"viewer" \| "editor" \| "admin" \| "owner"

Field	Type	Meaning and constraints
`download_path`Required	string	pattern: "^/v1/files/[0-9a-f-]{36}/versions/[0-9a-f-]{36}/browser-download$"
`expires_at`Required	string	format: "date-time"

Field	Type	Meaning and constraints
`sha256`Required	string	Empty for a zero extent or immutable base reference pattern: "^([0-9a-f]{64})?$"
`size`Required	integer	format: "int64" · minimum: 1
`zero`Optional	boolean	True means this extent represents zero bytes without an object
`base_offset`Optional	integer	Reuse this range from base_version_id; excludes zero and a content hash format: "int64" · minimum: 0

Field	Type	Meaning and constraints
`logical_size`Required	integer	format: "int64" · minimum: 0
`chunks`Required	array<ChunkRef>	maxItems: 1000000
`base_version_id`Optional	string	Immutable current version selected at upload creation and pinned through completion format: "uuid"

Field	Type	Meaning and constraints
`user`Required	User
`access_token`Required	string	minLength: 1
`access_expires_at`Required	string	format: "date-time"
`refresh_token`Required	string	minLength: 1
`refresh_expires_at`Required	string	format: "date-time"

Field	Type	Meaning and constraints
`offset`Required	integer	format: "int64" · minimum: 0 · maximum: 9223372036854776000
`data`Required	string	minLength: 1

Field	Type	Meaning and constraints
`entry`Required	Entry
`version`Required	Version
`idempotent_replay`Optional	boolean

Field	Type	Meaning and constraints
`epoch`Required	string	format: "uuid"
`sequence`Required	integer	format: "int64" · minimum: 0

Field	Type	Meaning and constraints
`cursor`Required	integer	format: "int64" · minimum: 0
`epoch`Required	string	format: "uuid"
`changes`Required	array<object>

Field	Type	Meaning and constraints
`boundary`Required	CursorBoundary
`entries`Required	array<Entry>	maxItems: 500
`next_entry_id`Required	string \| null	format: "uuid"

Field	Type	Meaning and constraints
`status`Required	"added" \| "modified" \| "deleted"
`base_entry_id`Optional	string \| null	format: "uuid"
`branch_entry_id`Required	string	format: "uuid"
`name`Required	string
`path`Required	string	Current path in the branch
`base_path`Optional	string \| null	Path in the immutable base snapshot
`kind`Required	"file" \| "folder"
`base_version_id`Optional	string \| null	format: "uuid"
`version_id`Optional	string \| null	format: "uuid"
`logical_size`Required	integer	format: "int64"
`actor_id`Optional	string \| null	Latest authenticated actor for this branch entry when available format: "uuid"

Field	Type	Meaning and constraints
`file_name`Required	string
`version_id`Required	string	format: "uuid"
`logical_size`Required	integer	minimum: 0 · maximum: 9223372036854776000
`checksum_sha256`Required	string \| null	Whole-file checksum when available; null for extent versions without a computed whole-file digest. pattern: "^[0-9a-f]{64}$"
`expires_at`Required	string	format: "date-time"

Field	Type	Meaning and constraints
`parent_id`Optional	string \| null	format: "uuid"
`title`Required	string	minLength: 1 · maxLength: 100
`max_files`Required	integer	minimum: 1 · maximum: 100
`max_file_bytes`Required	integer	minimum: 1 · maximum: 104857600
`max_total_bytes`Required	integer	minimum: 1 · maximum: 1073741824
`allowed_extensions`Optional	array<string>	maxItems: 20
`expires_at`Required	string	format: "date-time"

Field	Type	Meaning and constraints
`receipt_id`Required	string	format: "uuid"
`file_name`Required	string
`size_bytes`Required	integer	minimum: 0 · maximum: 104857600
`sha256`Required	string	pattern: "^[0-9a-f]{64}$"
`idempotent_replay`Required	boolean

Field	Type	Meaning and constraints
`file_id`Required	string	format: "uuid"
`drive_id`Required	string	format: "uuid"
`version_id`Required	string \| null	format: "uuid"
`name`Required	string
`path`Required	string
`kind`Required	"file" \| "folder"
`logical_size`Required	integer	Byte length of the matched current version in the same search snapshot format: "int64" · minimum: 0
`excerpt`Required	string	Plain text prefix of indexed UTF-8 content
`content_state`Required	"pending" \| "processing" \| "indexed" \| "unsupported"

Field	Type	Meaning and constraints
`results`Required	array<SearchHit>	maxItems: 100
`next_cursor`Required	string \| null

Field	Type	Meaning and constraints
`platform`Required	string
`architecture`Required	string
`format`Required	string
`version`Required	string
`url`Required	string
`sha256`Required	string
`sha512`Optional	string	Base64 SHA-512 for desktop updater verification.
`minimum_supported_version`Optional	string	Older matching desktop clients must update after pending saves finish.
`update_reason`Optional	string
`notes`Required	string
`published`Required	boolean
`channel`Optional	"stable" \| "preview" \| "beta"
`file_size`Optional	integer	minimum: 0
`signing`Optional	"unsigned" \| "authenticode" \| "notarized" \| "not_applicable"
`verification`Optional	"not_checked" \| "passed" \| "failed"

Field	Type	Meaning and constraints
`revision`Optional	string
`plans`Required	array<PlanOption>
`currency`Required	string
`billing_interval`Required	string
`checkout_mode`Required	"disabled" \| "development"

Field	Type	Meaning and constraints
`signup_enabled`Required	boolean
`checkout_enabled`Required	boolean
`web_enabled`Required	boolean
`linux_enabled`Required	boolean
`macos_enabled`Required	boolean
`windows_enabled`Required	boolean
`announcement`Required	string
`support_url`Required	string
`support_email`Required	string
`releases`Required	array<PlatformRelease>
`announcement_starts_at`Optional	string
`announcement_ends_at`Optional	string

Field	Type	Meaning and constraints
`plans`Required	array<PlanOption>
`settings`Required	PlatformSettings

Field	Type	Meaning and constraints
`revision`Required	string
`catalog`Required	PlanCatalog
`settings`Required	PlatformSettings

Field	Type	Meaning and constraints
`challenge_id`Required	string	format: "uuid"
`expires_at`Required	string	format: "date-time"
`resend_after`Required	integer	minimum: 0
`code`Optional	string	Only exposed by explicitly configured local integration fixtures. Never returned in production.

Field	Type	Meaning and constraints
`enabled`Required	boolean
`expected_revision`Required	string	pattern: "^[1-9][0-9]*$"

Field	Type	Meaning and constraints
`versions_cleared`Required	integer	format: "int64" · minimum: 0
`versions_skipped`Required	integer	format: "int64" · minimum: 0
`bytes_freed`Required	integer	format: "int64" · minimum: 0
`used_bytes`Required	integer	format: "int64" · minimum: 0