Schemas

Access object

• roleRolerequired
  viewercommentereditormanager
• space_roleRolerequired
  viewercommentereditormanager
• governed_byFolderAccess | anyrequired

Account object

• user_idstringrequired
• planPlanrequired
  › 15 fields

  • storage_bytesinteger | null
    Bytes the owner's spaces may keep (each content counted once; spaces in their own bucket are not counted)
    required
  • ai_runs_monthinteger | null
    required
  • ai_media_minutes_monthinteger | null
    Minutes of audio and video that AI runs may read a month
    required
  • members_per_spaceinteger | null
    required
  • max_file_bytesinteger | null
    required
  • idstringrequired
  • namestringrequired
  • descriptionstring
  • price_centsintegerrequired
    Per month (per member when per_member)
  • price_yearly_centsinteger
    Per month when billed yearly (per member when per_member); 0: no yearly price
  • per_memberboolean
    The price, storage and AI allowances are per member; the account's limits are the plan's times its seats
  • currencystringrequired
  • publicbooleanrequired
  • sortinteger
  • updated_atTimestamp
• statusstringrequired
  default: no plan of its own, so the server's default plan
  defaultactivetrialingpast_duecanceled
• ends_atTimestamp
• seatsinteger
  On a per-member plan: the people in the spaces the account owns (not agents or guests), itself included
• overridesPlanLimits
  › 5 fields

  • storage_bytesinteger | null
    Bytes the owner's spaces may keep (each content counted once; spaces in their own bucket are not counted)
    required
  • ai_runs_monthinteger | null
    required
  • ai_media_minutes_monthinteger | null
    Minutes of audio and video that AI runs may read a month
    required
  • members_per_spaceinteger | null
    required
  • max_file_bytesinteger | null
    required
• limitsPlanLimitsrequired
  › 5 fields

  • storage_bytesinteger | null
    Bytes the owner's spaces may keep (each content counted once; spaces in their own bucket are not counted)
    required
  • ai_runs_monthinteger | null
    required
  • ai_media_minutes_monthinteger | null
    Minutes of audio and video that AI runs may read a month
    required
  • members_per_spaceinteger | null
    required
  • max_file_bytesinteger | null
    required
• usageobjectrequired
  › 6 fields

  • stored_bytesinteger
  • stored_measured_atTimestamp
  • ai_runsinteger
  • ai_media_minutesnumber
  • period_startTimestamp
  • period_endTimestamp
• overstring[]required
• providerstring

Action object

• namestringrequired
• versionstringrequired
  Changes when its output would; part of the cache key
• titlestringrequired
• descriptionstringrequired
• acceptsstring[]required
  MIME prefixes it takes, e.g. video/; empty = any file
• writesstring[]required
  Sidecar namespaces it writes, and "files" when it makes new files
• params_schemaobjectrequired
  JSON Schema of its params
• availablebooleanrequired
• needsstring
  When not available: the setting the server lacks

AddMemberRequest object

• emailstringrequired
• roleRolerequired
  viewercommentereditormanager

ApplyForkRequest object

• pathsstring[]
  Only changes at or under these paths (fork or original paths)
• forceboolean
  Also replace the original's newer versions
• dry_runboolean

AuditRecord object

• atTimestamprequired
• sourcestringrequired
  orgspace
• kindstringrequired
  org.created, member.added, team.member_added, space.team_set, folder.access_set, sso.signed_in… or a journal op (version.created, node.moved…)
• actor_idstringrequired
• actor_emailstringrequired
• actor_kindstring
  personagentplugin
• viastring
  token or action
• space_idstring
• space_namestring
• targetstring
• pathstring
  The file name as it was (space records)
• detailobject

ChunkRef object

• hashHashrequired
  ^[0-9a-f]{64}$
• offsetintegerrequired
• lenintegerrequired

Comment object

• idstringrequired
• space_idstringrequired
• node_idstringrequired
• version_idstring | nullrequired
  The version on screen when it was written
  required
• parent_idstring | nullrequired
  Set on replies
  required
• authorUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• guest_namestring
  The name a reviewer gave on a review link (author is then the link's guest user)
• bodystringrequired
  ≤ 5000 chars
• at_msinteger | nullrequired
  Where in the video or audio
  required
• until_msinteger | nullrequired
  required
• regionRegion | anyrequired
• resolvedbooleanrequired
• resolved_atTimestamp | any
• resolved_bystring | null
  required
• created_atTimestamprequired
• edited_atTimestamp | anyrequired
• repliesComment[]

CommentRequest object

• bodystringrequired
  ≤ 5000 chars
• at_msinteger
  ≥ 0
• until_msinteger
  Needs at_ms; not before it
• regionRegion
  › 4 fields

  • xnumberrequired
  • ynumberrequired
  • wnumberrequired
  • hnumberrequired
• parent_idstring
  Reply to this comment (a reply to a reply joins the same thread)
• version_idstring
  The version being looked at (default: the current one)

CommitVersionRequest object

• base_version_idstring | nullrequired
  required
• manifestManifestrequired
  › 3 fields

  • algostringrequired
    fastcdc-v1
  • sizeintegerrequired
  • chunksChunkRef[]required
    › 3 fields

    • hashHashrequired
      ^[0-9a-f]{64}$
    • offsetintegerrequired
    • lenintegerrequired
• mimestring
• client_mtimeTimestamp
• if_version_idstring
  Save only if the file is still at this version (same as If-Match); else 412 precondition_failed
• if_newboolean
  Save only if the file has no version yet (same as If-None-Match: *)

CommitVersionResponse object

• versionVersionInforequired
  › 15 fields

  • idstringrequired
  • node_idstringrequired
  • seqintegerrequired
    1-based per node
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • manifest_hashHashrequired
    ^[0-9a-f]{64}$
  • authorUserrequired
    › 4 fields

    • idstringrequired
    • emailstringrequired
      Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    • display_namestringrequired
    • kindstringrequired
      humanagent
  • device_idstring | nullrequired
    required
  • base_version_idstring | nullrequired
    required
  • superseded_version_idstring | nullrequired
    Head this save replaced although it was not its base
    required
  • client_mtimeTimestamp | anyrequired
  • created_atTimestamprequired
  • labelstring
    The name someone gave this version ("Client cut"), unique per file; absent if none
  • labeled_bystring
  • labeled_atTimestamp
• nodeNodeInforequired
  › 11 fields

  • idstringrequired
  • space_idstringrequired
  • parent_idstring | nullrequired
    null for the space root
    required
  • namestringrequired
  • kindNodeKindrequired
    filedir
  • head_version_idstring | nullrequired
    required
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • meta_revintegerrequired
    Bumped by rename
  • deletedbooleanrequired
  • mtimeTimestamprequired
• supersededSuperseded | anyrequired

CreateNodeRequest object

• parent_idstringrequired
• namestringrequired
• kindNodeKindrequired
  filedir
• if_existsstring
  When a live sibling has the same name (case-insensitive): rename creates "name (2).ext"; reuse returns the existing node of the same kind; fail (or If-None-Match: *) answers 412 precondition_failed with the existing node_id. Sync clients use reuse so concurrent creates of one path converge on one file (last save wins, both saves in its history).
  renamereusefail
  default "rename"

CreateShareRequest object

• node_idstringrequired
• modeShareModerequired
  viewuploadrequest
• passwordstring
• expires_atTimestamp
• can_commentboolean
  A review link: anyone with it can comment, under a name they give
• no_downloadboolean
  Watch-only: no downloads; videos play their streaming proxy, and originals the browser cannot show are not served
• titlestring
  Mode request (required there): what files you are asking for
  ≤ 200 chars
• messagestring
  Mode request: details for the senders
  ≤ 4000 chars

CreateShareResponse object

• shareSharerequired
  › 13 fields

  • idstringrequired
  • node_idstringrequired
  • modeShareModerequired
    viewuploadrequest
  • has_passwordbooleanrequired
  • expires_atTimestamp | anyrequired
  • created_bystringrequired
  • created_atTimestamprequired
  • revokedbooleanrequired
  • can_commentboolean
    A review link: people with it can comment on its files
  • no_downloadboolean
    Watch-only: the page previews and plays the streaming proxy but offers no download
  • titlestring | any
    What an upload request asks for
  • messagestring | any
    Details of an upload request
  • uploadsinteger
    Files people have sent through the link
• tokenstringrequired
• urlstringrequired

CreateSpaceRequest object

• namestringrequired
• storage_idstring
  One of my storage profiles to keep its files in

Device object

• idstringrequired
• namestringrequired
• platformstringrequired
• last_seen_atTimestamp | any
• revoked_atTimestamp | any
• currentbooleanrequired

DownloadTicket object

• ticketstringrequired
• manifestManifestrequired
  › 3 fields

  • algostringrequired
    fastcdc-v1
  • sizeintegerrequired
  • chunksChunkRef[]required
    › 3 fields

    • hashHashrequired
      ^[0-9a-f]{64}$
    • offsetintegerrequired
    • lenintegerrequired
• blockgw_urlstringrequired
• expires_atTimestamprequired

DownloadTicketRequest object

• version_idstringrequired
• renditionstring
  e.g. thumb, or proxy (the server-made 720p H.264 stream of a video)
• streamboolean
  A ticket for a player: lasts a viewing session (6 h) instead of minutes

EditOp object

• atinteger (int64)required
  Byte offset in the old version
  ≥ 0
• deleteinteger (int64)
  Bytes removed there
  default 0 · ≥ 0
• textstring
  Inserted there, as UTF-8
• base64string
  Inserted there, as bytes (instead of text)

EditRequest object

• if_version_idstring
  The version the offsets are in; must still be the head
• opsEditOp[]
  ≤ 10000 items
  › 4 fields

  • atinteger (int64)required
    Byte offset in the old version
    ≥ 0
  • deleteinteger (int64)
    Bytes removed there
    default 0 · ≥ 0
  • textstring
    Inserted there, as UTF-8
  • base64string
    Inserted there, as bytes (instead of text)
• truncateinteger (int64)
  Cut the result to this many bytes
  ≥ 0

EmailStartRequest object

• emailstring (email)required

EmailVerifyRequest object

• emailstringrequired
• codestringrequired
  ^[0-9]{6}$
• device_namestringrequired
• platformstringrequired
• display_namestring
  Used when the account is created

Error object

• errorobjectrequired
  › 4 fields

  • codestringrequired
    Stable; see the error reference (docs/reference/errors.md). New codes may be added, so treat an unknown one by its HTTP status.
    bad_requestunauthorizedforbiddennot_foundconflictmissing_chunksprecondition_failedquota_exceededrate_limitedexpiredsso_requiredsso_unavailabledomain_unprovenmail_failedunavailableinternal
  • messagestringrequired
    For people; may change. Match on code
  • detailsany
    Extra data for some codes, e.g. the current version for precondition_failed
  • request_idstring
    Same as the X-Request-Id header; quote it when reporting a problem

FolderAccess object

• node_idstringrequired
• pathstringrequired
• default_roleRole | anyrequired
  The most anyone not granted may do inside; null keeps their space role
• grantsFolderGrant[]required
  › 4 fields

  • kindstringrequired
    userteam
  • idstring
  • roleRolerequired
    viewercommentereditormanager
  • namestring
    An email or team name; on a request a user may be named by email instead of id
• updated_bystring
• updated_atTimestamp

FolderGrant object

• kindstringrequired
  userteam
• idstring
• roleRolerequired
  viewercommentereditormanager
• namestring
  An email or team name; on a request a user may be named by email instead of id

FolderSize object

• filesintegerrequired
• foldersintegerrequired
• bytesintegerrequired
  Bytes of the current versions of every file
• videosintegerrequired
• proxy_filesintegerrequired
  Videos that have a streaming proxy
• proxy_bytesintegerrequired
  What those proxies weigh
• largestintegerrequired
  The biggest single file

ForkApplied any

• kindstringrequired
  addedmodifiedmetadatamoveddeleted
• node_kindstringrequired
  filedir
• pathstringrequired
  In the fork ("" for a deleted node)
• node_idstringrequired
  In the fork
• origin_pathstring
  Where it is (or goes) in the original
• origin_node_idstring
• sidecarsstring[]
  Namespaces whose documents differ
• conflictboolean
  The original changed it too since the fork: apply needs force
• whystring
• resultstringrequired
  appliedskippedwould applyfailed
• errorstring

ForkChange object

• kindstringrequired
  addedmodifiedmetadatamoveddeleted
• node_kindstringrequired
  filedir
• pathstringrequired
  In the fork ("" for a deleted node)
• node_idstringrequired
  In the fork
• origin_pathstring
  Where it is (or goes) in the original
• origin_node_idstring
• sidecarsstring[]
  Namespaces whose documents differ
• conflictboolean
  The original changed it too since the fork: apply needs force
• whystring

ForkRequest object

• namestringrequired
• pathstring
  Only this folder of the space (default all of it)

Hash string

JournalEntry object

• seqintegerrequired
• opJournalOprequired
  node.creatednode.renamednode.movednode.deletednode.restoredversion.createdversion.labeledsidecar.updatedrendition.updatedincoming.startedincoming.stoppedcomment.createdcomment.updated
• node_idstringrequired
• version_idstring | nullrequired
  required
• actor_idstringrequired
  The user the change was made by or for
• actor_kindstringrequired
  A person, an agent, or a server plugin (e.g. the media worker) acting for actor_id
  humanagentplugin
• actor_viastring
  What the change came through: an access token (tok_…) or a plugin (media). Absent for the apps.
• device_idstring | nullrequired
  required
• tsTimestamprequired
• nodeNodeInforequired
  › 11 fields

  • idstringrequired
  • space_idstringrequired
  • parent_idstring | nullrequired
    null for the space root
    required
  • namestringrequired
  • kindNodeKindrequired
    filedir
  • head_version_idstring | nullrequired
    required
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • meta_revintegerrequired
    Bumped by rename
  • deletedbooleanrequired
  • mtimeTimestamprequired

JournalOp string

JournalPage object

• entriesJournalEntry[]required
  › 10 fields

  • seqintegerrequired
  • opJournalOprequired
    node.creatednode.renamednode.movednode.deletednode.restoredversion.createdversion.labeledsidecar.updatedrendition.updatedincoming.startedincoming.stoppedcomment.createdcomment.updated
  • node_idstringrequired
  • version_idstring | nullrequired
    required
  • actor_idstringrequired
    The user the change was made by or for
  • actor_kindstringrequired
    A person, an agent, or a server plugin (e.g. the media worker) acting for actor_id
    humanagentplugin
  • actor_viastring
    What the change came through: an access token (tok_…) or a plugin (media). Absent for the apps.
  • device_idstring | nullrequired
    required
  • tsTimestamprequired
  • nodeNodeInforequired
    › 11 fields

    • idstringrequired
    • space_idstringrequired
    • parent_idstring | nullrequired
      null for the space root
      required
    • namestringrequired
    • kindNodeKindrequired
      filedir
    • head_version_idstring | nullrequired
      required
    • sizeintegerrequired
    • mimestring | nullrequired
      required
    • meta_revintegerrequired
      Bumped by rename
    • deletedbooleanrequired
    • mtimeTimestamprequired
• last_seqintegerrequired
• has_morebooleanrequired

Manifest object

• algostringrequired
  fastcdc-v1
• sizeintegerrequired
• chunksChunkRef[]required
  › 3 fields

  • hashHashrequired
    ^[0-9a-f]{64}$
  • offsetintegerrequired
  • lenintegerrequired

Member object

• userUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• roleRolerequired
  viewercommentereditormanager
• direct_roleRole | any
  Their own grant; null when they are here only through teams
• teamsMemberTeam[]
  › 3 fields

  • idstringrequired
  • namestringrequired
  • roleRolerequired
    viewercommentereditormanager

MemberTeam object

• idstringrequired
• namestringrequired
• roleRolerequired
  viewercommentereditormanager

NamespaceOwner object

• namespacestringrequired
• ownerUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• created_atTimestamprequired

NodeInfo object

• idstringrequired
• space_idstringrequired
• parent_idstring | nullrequired
  null for the space root
  required
• namestringrequired
• kindNodeKindrequired
  filedir
• head_version_idstring | nullrequired
  required
• sizeintegerrequired
• mimestring | nullrequired
  required
• meta_revintegerrequired
  Bumped by rename
• deletedbooleanrequired
• mtimeTimestamprequired

NodeKind string

NodePage object

• itemsNodeInfo[]required
  › 11 fields

  • idstringrequired
  • space_idstringrequired
  • parent_idstring | nullrequired
    null for the space root
    required
  • namestringrequired
  • kindNodeKindrequired
    filedir
  • head_version_idstring | nullrequired
    required
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • meta_revintegerrequired
    Bumped by rename
  • deletedbooleanrequired
  • mtimeTimestamprequired
• next_cursorstring | nullrequired
  required

Notification object

• idstringrequired
• kindNotificationKindrequired
  version.supersededspace.invitedshare.uploadedspace.role_changedspace.removedcomment.created
• payloadobjectrequired
  version.superseded: {space_id, node_id, name, your_version_id, new_version_id, by: User} space.invited: {space_id, space_name, role, by: User} share.uploaded: {space_id, share_id, node_id, name, parent_id}
• read_atTimestamp | anyrequired
• created_atTimestamprequired

NotificationKind string

NotificationPage object

• itemsNotification[]required
  › 5 fields

  • idstringrequired
  • kindNotificationKindrequired
    version.supersededspace.invitedshare.uploadedspace.role_changedspace.removedcomment.created
  • payloadobjectrequired
    version.superseded: {space_id, node_id, name, your_version_id, new_version_id, by: User} space.invited: {space_id, space_name, role, by: User} share.uploaded: {space_id, share_id, node_id, name, parent_id}
  • read_atTimestamp | anyrequired
  • created_atTimestamprequired
• next_cursorstring | nullrequired
  required

OAuthApp object

• idstringrequired
  The OAuth client_id
• namestringrequired
• redirect_urisstring[]required
• client_uristring
• logo_uristring
• confidentialbooleanrequired
• registeredbooleanrequired
  The app registered itself (RFC 7591)
• created_atTimestamprequired

Org object

• idstringrequired
• namestringrequired
• roleOrgRolerequired
  owneradminmember
• membersintegerrequired
• teamsintegerrequired
• spacesintegerrequired
• created_atTimestamprequired

OrgMember object

• userUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• roleOrgRolerequired
  owneradminmember
• teamsstring[]required
• sinceTimestamprequired

OrgRole string

OrgSpace object

• idstringrequired
• namestringrequired
• owner_idstringrequired
• teamsMemberTeam[]required
  › 3 fields

  • idstringrequired
  • namestringrequired
  • roleRolerequired
    viewercommentereditormanager

PatchMemberRequest object

• roleRolerequired
  viewercommentereditormanager

PatchNodeRequest object

• namestring
• parent_idstring
• if_version_idstring
  Rename or move only if the file is still at this version

PatchSpaceRequest object

• namestring
• storage_idstring
  A storage profile of mine, or empty for the server's own storage. Only while the space has no files (409).

Pipeline object

• idstringrequired
• space_idstringrequired
• created_bystringrequired
  The manager it runs for; it stops if they stop being a manager
• namestringrequired
• actionstringrequired
• paramsobjectrequired
• path_globstringrequired
  e.g. /dailies/** or **/*.mov; empty = all
• mime_prefixstringrequired
  e.g. video/; empty = what the action accepts
• conditionsPipelineConditions
  › 7 fields

  • min_sizeinteger
    Bytes
    ≥ 0
  • max_sizeinteger
    ≥ 0
  • min_duration_snumber
    ≥ 0
  • max_duration_snumber
    ≥ 0
  • min_widthinteger
    ≥ 0
  • min_heightinteger
    ≥ 0
  • has_audioboolean
• afterstring | null
  The action it follows: it starts when a run of that action finishes on a matching file, instead of on save
  required
• activebooleanrequired
• disabled_reasonstring | null
  required
• cursor_seqintegerrequired
  Last journal seq looked at
• created_atTimestamprequired

PipelineConditions object

• min_sizeinteger
  Bytes
  ≥ 0
• max_sizeinteger
  ≥ 0
• min_duration_snumber
  ≥ 0
• max_duration_snumber
  ≥ 0
• min_widthinteger
  ≥ 0
• min_heightinteger
  ≥ 0
• has_audioboolean

PipelineRequest object

• namestring
• actionstring
• paramsobject
• path_globstring
• mime_prefixstring
• conditionsPipelineConditions
  › 7 fields

  • min_sizeinteger
    Bytes
    ≥ 0
  • max_sizeinteger
    ≥ 0
  • min_duration_snumber
    ≥ 0
  • max_duration_snumber
    ≥ 0
  • min_widthinteger
    ≥ 0
  • min_heightinteger
    ≥ 0
  • has_audioboolean
• afterstring
  An action name; "" clears it
• activeboolean

PipelineTemplate object

• idstringrequired
• titlestringrequired
• descriptionstringrequired
• pipelinesPipelineRequest[]required
  › 8 fields

  • namestring
  • actionstring
  • paramsobject
  • path_globstring
  • mime_prefixstring
  • conditionsPipelineConditions
    › 7 fields

    • min_sizeinteger
      Bytes
      ≥ 0
    • max_sizeinteger
      ≥ 0
    • min_duration_snumber
      ≥ 0
    • max_duration_snumber
      ≥ 0
    • min_widthinteger
      ≥ 0
    • min_heightinteger
      ≥ 0
    • has_audioboolean
  • afterstring
    An action name; "" clears it
  • activeboolean

Plan any

• storage_bytesinteger | null
  Bytes the owner's spaces may keep (each content counted once; spaces in their own bucket are not counted)
  required
• ai_runs_monthinteger | null
  required
• ai_media_minutes_monthinteger | null
  Minutes of audio and video that AI runs may read a month
  required
• members_per_spaceinteger | null
  required
• max_file_bytesinteger | null
  required
• idstringrequired
• namestringrequired
• descriptionstring
• price_centsintegerrequired
  Per month (per member when per_member)
• price_yearly_centsinteger
  Per month when billed yearly (per member when per_member); 0: no yearly price
• per_memberboolean
  The price, storage and AI allowances are per member; the account's limits are the plan's times its seats
• currencystringrequired
• publicbooleanrequired
• sortinteger
• updated_atTimestamp

PlanLimits object

• storage_bytesinteger | null
  Bytes the owner's spaces may keep (each content counted once; spaces in their own bucket are not counted)
  required
• ai_runs_monthinteger | null
  required
• ai_media_minutes_monthinteger | null
  Minutes of audio and video that AI runs may read a month
  required
• members_per_spaceinteger | null
  required
• max_file_bytesinteger | null
  required

Plugin object

• idstringrequired
• space_idstringrequired
• namestringrequired
• manifestPluginManifestrequired
  › 9 fields

  • namestringrequired
    Its actions are .
    ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
  • titlestring
  • descriptionstring
  • versionstringrequired
    Part of the result cache key: a new version runs files again
  • homepagestring
  • runtimestring
    https: jobs are POSTed to endpoint. runner: no endpoint; sidespace runner (or any program) claims jobs at POST /v1/plugin-runs/claim
    httpsrunner
    default "https"
  • endpointstring
    Receives the signed jobs (POST); https. Not set for runner plugins
  • timeout_secondsinteger
    How long a run answered with 202 may take before it is sent again
    default 3600 · ≥ 10 · ≤ 86400
  • actionsobject[]required
    ≤ 50 items
    › 6 fields

    • namestringrequired
      ^[a-z][a-z0-9_-]{0,40}$
    • titlestring
    • descriptionstring
    • acceptsstring[]
      MIME prefixes; empty = any file
    • writesstring[]required
      x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
    • params_schemaobject
      JSON Schema the params are checked against
• endpointstringrequired
• created_bystringrequired
• activebooleanrequired
• disabled_reasonstring | null
  required
• created_atTimestamprequired
• updated_atTimestamprequired

PluginJob object

• typestringrequired
  run
• run_idstringrequired
• actionstringrequired
  The plugin's own action name (check
• attemptintegerrequired
• space_idstringrequired
• node_idstringrequired
• version_idstringrequired
• pathstringrequired
• namestringrequired
• mimestring
• sizeintegerrequired
• paramsobjectrequired
• inputobjectrequired
  › 2 fields

  • urlstringrequired
    The version's bytes; Range works
  • expires_atTimestamprequired
• sidecarsobject
  The media sidecar, when the server probed the file
• callbackobjectrequired
  › 3 fields

  • urlstringrequired
    …/v1/plugin-runs/{run_id}; POST /progress, /upload, /complete
  • tokenstringrequired
    srt_…, as a bearer token
  • expires_atTimestamprequired

PluginManifest object

• namestringrequired
  Its actions are .
  ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
• titlestring
• descriptionstring
• versionstringrequired
  Part of the result cache key: a new version runs files again
• homepagestring
• runtimestring
  https: jobs are POSTed to endpoint. runner: no endpoint; sidespace runner (or any program) claims jobs at POST /v1/plugin-runs/claim
  httpsrunner
  default "https"
• endpointstring
  Receives the signed jobs (POST); https. Not set for runner plugins
• timeout_secondsinteger
  How long a run answered with 202 may take before it is sent again
  default 3600 · ≥ 10 · ≤ 86400
• actionsobject[]required
  ≤ 50 items
  › 6 fields

  • namestringrequired
    ^[a-z][a-z0-9_-]{0,40}$
  • titlestring
  • descriptionstring
  • acceptsstring[]
    MIME prefixes; empty = any file
  • writesstring[]required
    x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
  • params_schemaobject
    JSON Schema the params are checked against

PluginRequest object

• manifest_urlstring
• manifestPluginManifest
  › 9 fields

  • namestringrequired
    Its actions are .
    ^x-[a-z0-9][a-z0-9-]*(\.[a-z0-9][a-z0-9-]*)*$
  • titlestring
  • descriptionstring
  • versionstringrequired
    Part of the result cache key: a new version runs files again
  • homepagestring
  • runtimestring
    https: jobs are POSTed to endpoint. runner: no endpoint; sidespace runner (or any program) claims jobs at POST /v1/plugin-runs/claim
    httpsrunner
    default "https"
  • endpointstring
    Receives the signed jobs (POST); https. Not set for runner plugins
  • timeout_secondsinteger
    How long a run answered with 202 may take before it is sent again
    default 3600 · ≥ 10 · ≤ 86400
  • actionsobject[]required
    ≤ 50 items
    › 6 fields

    • namestringrequired
      ^[a-z][a-z0-9_-]{0,40}$
    • titlestring
    • descriptionstring
    • acceptsstring[]
      MIME prefixes; empty = any file
    • writesstring[]required
      x-… namespaces, transcript, ai.tags, ai.generation, user, and/or files
    • params_schemaobject
      JSON Schema the params are checked against
• activeboolean

PluginResult object

• sidecarsmap<string, any>
  namespace → document, only namespaces the action declares
• filesobject[]
  › 3 fields

  • pathstringrequired
  • mimestring
  • manifestManifestrequired
    › 3 fields

    • algostringrequired
      fastcdc-v1
    • sizeintegerrequired
    • chunksChunkRef[]required
      › 3 fields

      • hashHashrequired
        ^[0-9a-f]{64}$
      • offsetintegerrequired
      • lenintegerrequired
• errorstring
  On complete: the run failed
• retryboolean
  With error: try another attempt

Presence object

• space_idstringrequired
• node_idstringrequired
• user_idstringrequired
• user_namestringrequired
• device_idstringrequired
• statestringrequired
  viewingeditingnone
• expires_atTimestamprequired

PutRenditionRequest object

• manifestManifestrequired
  › 3 fields

  • algostringrequired
    fastcdc-v1
  • sizeintegerrequired
  • chunksChunkRef[]required
    › 3 fields

    • hashHashrequired
      ^[0-9a-f]{64}$
    • offsetintegerrequired
    • lenintegerrequired
• mimestringrequired

PutSidecarRequest object

• docobjectrequired
• schema_versioninteger
  default 1
• producerobject

RefreshRequest object

• refresh_tokenstringrequired

Region object

• xnumberrequired
• ynumberrequired
• wnumberrequired
• hnumberrequired

Release object

• platformstringrequired
  macoslinux
• versionstringrequired
• urlstring (uri)required
  Where to download it
• sha256string
  The download's SHA-256
• notesstring
• min_versionstring
  Older versions must update
• updatebooleanrequired
  current is older than version
• requiredbooleanrequired
  current is older than min_version

Rendition object

• kindstringrequired
• mimestringrequired
• manifest_hashHashrequired
  ^[0-9a-f]{64}$
• sizeintegerrequired

RewindChange object

• actionstringrequired
  restoreundeletemovetrashmissing
• node_idstringrequired
• kindNodeKindrequired
  filedir
• pathstringrequired
  Where it is after the rewind (trash; where it was)
• from_pathstring
  move: where it was before
• version_idstring
  restore: the version brought back
• notestring

RewindResult object

• as_of_seqintegerrequired
• as_of_timestring (date-time) | null
  required
• dry_runbooleanrequired
• changesRewindChange[]required
  › 7 fields

  • actionstringrequired
    restoreundeletemovetrashmissing
  • node_idstringrequired
  • kindNodeKindrequired
    filedir
  • pathstringrequired
    Where it is after the rewind (trash; where it was)
  • from_pathstring
    move: where it was before
  • version_idstring
    restore: the version brought back
  • notestring

Role string

Run object

• idstringrequired
• space_idstringrequired
• node_idstringrequired
• version_idstringrequired
  The version it works on; a newer save is a new run
• actionstringrequired
• action_versionstringrequired
• paramsobjectrequired
  The params with defaults filled in
• pipeline_idstring | null
  required
• requested_bystringrequired
• stateRunStaterequired
  queuedrunningdonefailedcanceled
• attemptsintegerrequired
  Tries so far; failures that may pass later retry up to 3 times
• progressnumber | null
  ≥ 0 · ≤ 1
  required
• errorstring | null
  required
• resultobject | null
  required
  › 2 fields

  • sidecarsmap<string, any>
    namespace → document written on the version
  • filesobject[]
    › 4 fields

    • pathstringrequired
    • mimestringrequired
    • node_idstring
    • version_idstring
• cachedbooleanrequired
  The result was reused from the same bytes done before
• created_atTimestamprequired
• started_atTimestamp | any
• finished_atTimestamp | any

RunRequest object

• actionstringrequired
• version_idstring
• node_idstring
• pathstring
• paramsobject
  Checked against the action's params_schema
• freshboolean
  Run again even if these bytes were done before

RunState string

SSOConfig object

• issuerstringrequired
• client_idstringrequired
• client_secretstring
• domainsstring[]required
• requiredboolean
  Email codes stop working for these domains
• redirect_uristring
  Register it with the provider
• domain_proofstring
  Value of the DNS TXT record _sidespace.
• updated_atTimestamp

SSOStart object

• urlstringrequired
• handlestringrequired
• expires_atTimestamprequired

SearchHit object

• nodeNodeInforequired
  › 11 fields

  • idstringrequired
  • space_idstringrequired
  • parent_idstring | nullrequired
    null for the space root
    required
  • namestringrequired
  • kindNodeKindrequired
    filedir
  • head_version_idstring | nullrequired
    required
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • meta_revintegerrequired
    Bumped by rename
  • deletedbooleanrequired
  • mtimeTimestamprequired
• space_namestringrequired
• folderstringrequired
  Path of the folder holding it, from the space root ("" at the root)
• matchedstring[]required
  "name", the sidecar namespaces, "comments", or "meaning" for a file found by what it is about
• snippetstring
  For a metadata or comment match, the matching value, shortened to about 120 characters
• momentsSearchMoment[]
  Where in a video or audio file it matched, in time order
  ≤ 5 items
  › 4 fields

  • at_msinteger (int64)required
    ≥ 0
  • until_msinteger (int64)
  • textstringrequired
    The transcript line, comment or piece of transcript that matched
  • sourcestringrequired
    transcriptcommentsmeaning
• scorenumber
  How close in meaning (cosine, 0–1), for files found by meaning

SearchMoment object

• at_msinteger (int64)required
  ≥ 0
• until_msinteger (int64)
• textstringrequired
  The transcript line, comment or piece of transcript that matched
• sourcestringrequired
  transcriptcommentsmeaning

SetFolderAccessRequest object

• default_roleRole | any
• grantsFolderGrant[]required
  › 4 fields

  • kindstringrequired
    userteam
  • idstring
  • roleRolerequired
    viewercommentereditormanager
  • namestring
    An email or team name; on a request a user may be named by email instead of id

Share object

• idstringrequired
• node_idstringrequired
• modeShareModerequired
  viewuploadrequest
• has_passwordbooleanrequired
• expires_atTimestamp | anyrequired
• created_bystringrequired
• created_atTimestamprequired
• revokedbooleanrequired
• can_commentboolean
  A review link: people with it can comment on its files
• no_downloadboolean
  Watch-only: the page previews and plays the streaming proxy but offers no download
• titlestring | any
  What an upload request asks for
• messagestring | any
  Details of an upload request
• uploadsinteger
  Files people have sent through the link

ShareMode string

ShelfItem object

• idstringrequired
• space_idstringrequired
• kindstringrequired
  textlinkfile
• textstring | nullrequired
  required
• node_idstring | nullrequired
  required
• namestring | nullrequired
  required
• sizeinteger | nullrequired
  required
• mimestring | nullrequired
  required
• is_folderbooleanrequired
• authorUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• created_atTimestamprequired
• expires_atTimestamprequired

ShelfRequest object

• textstring
  ≤ 10000 chars
• node_idstring

Sidecar object

• namespacestringrequired
• docobjectrequired
• schema_versionintegerrequired
• producerobject | nullrequired
  Who wrote it, e.g. {"name":"cliptap","version":"1.2","inherited_from":"ver_..."}
  required
• updated_atTimestamprequired

SnapshotPage object

• nodesNodeInfo[]required
  › 11 fields

  • idstringrequired
  • space_idstringrequired
  • parent_idstring | nullrequired
    null for the space root
    required
  • namestringrequired
  • kindNodeKindrequired
    filedir
  • head_version_idstring | nullrequired
    required
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • meta_revintegerrequired
    Bumped by rename
  • deletedbooleanrequired
  • mtimeTimestamprequired
• at_seqintegerrequired
• next_cursorstring | nullrequired
  required

Space object

• idstringrequired
• namestringrequired
• roleRolerequired
  viewercommentereditormanager
• owner_idstringrequired
• root_node_idstringrequired
• journal_seqintegerrequired
• created_atTimestamprequired
• storage_idstring
  The storage profile its files are in; absent for the server's own storage
• forkobject
  Set when the space is a fork
  › 3 fields

  • from_space_idstringrequired
  • pathstringrequired
    The folder of the original it copies ("/" for all of it)
  • at_seqintegerrequired
    The original's journal position when it was forked
• org_idstring
  The organization it belongs to

StorageProfile object

• idstringrequired
• namestringrequired
• kindstringrequired
  s3
• endpointstringrequired
  Empty for AWS S3
• bucketstringrequired
• regionstringrequired
• prefixstringrequired
  Keys go under it; empty or ends in /
• access_keystringrequired
• spacesintegerrequired
  How many spaces keep their files in it
• created_atTimestamprequired
• updated_atTimestamprequired

StorageRequest object

• namestring
• kindstring
  s3
  default "s3"
• endpointstring
  https URL of an S3-compatible service (R2, B2, OSS, MinIO…); empty for AWS S3
• bucketstring
• regionstring
  default "us-east-1"
• prefixstring
• access_keystring
• secret_keystring
  Stored sealed; never returned. Required with access_key: the gateway never lends its own credentials.

Superseded object

• version_idstringrequired
• authorUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent

Team object

• idstringrequired
• org_idstringrequired
• namestringrequired
• membersUser[]required
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• created_atTimestamprequired

Timestamp string (date-time)

TokenInfo object

• idstringrequired
• namestringrequired
• prefixstringrequired
  The first characters of the secret, to tell tokens apart
• userUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• scopesstring[]required
• space_idsstring[] | nullrequired
  null means every space
  required
• expires_atTimestamp | anyrequired
• last_used_atTimestamp | anyrequired
• created_atTimestamprequired
• revoked_atTimestamp | anyrequired
• s3_access_key_idstring
  Set when the token is also an S3 key
• app_idstring
  Set when an app got the token through OAuth: it lasts an hour and the app refreshes it
• parent_idstring
  Set when the token was derived from another token; it works only while that one (and every token above it) does

TokenPair object

• access_tokenstringrequired
  Ed25519 JWT, 15 minutes; claims sub, did, scope
• refresh_tokenstringrequired
  ., 30 days, rotates on every refresh
• expires_inintegerrequired
• userUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• device_idstringrequired

UploadSession object

• missingHash[]required
• ticketstringrequired
• blockgw_urlstringrequired
• expires_atTimestamprequired

UploadSessionRequest object

• hashesHash[]required
  ≤ 20000 items

User object

• idstringrequired
• emailstringrequired
  Agents have an address at agents.invalid: it finds them for invites, no mail goes there
• display_namestringrequired
• kindstringrequired
  humanagent

VersionCompare object

• aVersionInforequired
  › 15 fields

  • idstringrequired
  • node_idstringrequired
  • seqintegerrequired
    1-based per node
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • manifest_hashHashrequired
    ^[0-9a-f]{64}$
  • authorUserrequired
    › 4 fields

    • idstringrequired
    • emailstringrequired
      Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    • display_namestringrequired
    • kindstringrequired
      humanagent
  • device_idstring | nullrequired
    required
  • base_version_idstring | nullrequired
    required
  • superseded_version_idstring | nullrequired
    Head this save replaced although it was not its base
    required
  • client_mtimeTimestamp | anyrequired
  • created_atTimestamprequired
  • labelstring
    The name someone gave this version ("Client cut"), unique per file; absent if none
  • labeled_bystring
  • labeled_atTimestamp
• bVersionInforequired
  › 15 fields

  • idstringrequired
  • node_idstringrequired
  • seqintegerrequired
    1-based per node
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • manifest_hashHashrequired
    ^[0-9a-f]{64}$
  • authorUserrequired
    › 4 fields

    • idstringrequired
    • emailstringrequired
      Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    • display_namestringrequired
    • kindstringrequired
      humanagent
  • device_idstring | nullrequired
    required
  • base_version_idstring | nullrequired
    required
  • superseded_version_idstring | nullrequired
    Head this save replaced although it was not its base
    required
  • client_mtimeTimestamp | anyrequired
  • created_atTimestamprequired
  • labelstring
    The name someone gave this version ("Client cut"), unique per file; absent if none
  • labeled_bystring
  • labeled_atTimestamp
• same_contentbooleanrequired
  Byte for byte the same
• size_deltaintegerrequired
  B's size minus A's
• bytesobjectrequired
  The content compared chunk by chunk. A metadata-only re-save or a trim shares most of its bytes.
  › 4 fields

  • sharedintegerrequired
  • only_aintegerrequired
  • only_bintegerrequired
  • shared_rationumberrequired
    Shared over B's size (1 = nothing new in B)
• mediaobject[]required
  Media facts (duration_s, width, height, codecs…) that differ
  › 3 fields

  • fieldstringrequired
  • aanyrequired
  • banyrequired
• sidecarsobject[]required
  Sidecar namespaces added, removed or changed from A to B (core and media are left out)
  › 3 fields

  • namespacestringrequired
  • changestringrequired
    addedremovedchanged
  • fieldsstring[]
    Top-level keys that differ
• renditionsmap<string, string[]>required
  Rendition kinds by version id

VersionInfo object

• idstringrequired
• node_idstringrequired
• seqintegerrequired
  1-based per node
• sizeintegerrequired
• mimestring | nullrequired
  required
• manifest_hashHashrequired
  ^[0-9a-f]{64}$
• authorUserrequired
  › 4 fields

  • idstringrequired
  • emailstringrequired
    Agents have an address at agents.invalid: it finds them for invites, no mail goes there
  • display_namestringrequired
  • kindstringrequired
    humanagent
• device_idstring | nullrequired
  required
• base_version_idstring | nullrequired
  required
• superseded_version_idstring | nullrequired
  Head this save replaced although it was not its base
  required
• client_mtimeTimestamp | anyrequired
• created_atTimestamprequired
• labelstring
  The name someone gave this version ("Client cut"), unique per file; absent if none
• labeled_bystring
• labeled_atTimestamp

Webhook object

• idstringrequired
• space_idstringrequired
• created_bystringrequired
  The manager it speaks for; it stops if they stop being a manager
• urlstringrequired
  https (plain http and private addresses only on dev servers)
• eventsstring[]required
  Journal ops to send (node.created, version.created, sidecar.updated, …); empty = all
• path_globstringrequired
  Only paths matching, e.g. /dailies/** or **/*.mov; empty = all
• mime_prefixstringrequired
  Only files whose type starts with this, e.g. video/; empty = all
• descriptionstringrequired
• activebooleanrequired
• disabled_reasonstring | null
  required
• cursor_seqintegerrequired
  Last journal seq handled
• attemptsintegerrequired
  Failed tries of the next event
• failing_sinceTimestamp | any
• last_errorstring | null
  required
• created_atTimestamprequired

WebhookDelivery object

• idintegerrequired
• event_idstringrequired
• event_typestringrequired
• seqinteger | null
  required
• attemptintegerrequired
• statusinteger | null
  HTTP status; null when nothing answered
  required
• errorstring | null
  required
• duration_msintegerrequired
• created_atTimestamprequired

WebhookEvent object

• idstringrequired
  ".", the same on every retry and replay
• typestringrequired
  A journal op
• space_idstringrequired
• seqinteger
• timeTimestamprequired
• node_idstring
• version_idstring | null
  required
• pathstring
  The node's path when sent, e.g. /Ep01/Shots/a.mov
• nodeNodeInfo
  › 11 fields

  • idstringrequired
  • space_idstringrequired
  • parent_idstring | nullrequired
    null for the space root
    required
  • namestringrequired
  • kindNodeKindrequired
    filedir
  • head_version_idstring | nullrequired
    required
  • sizeintegerrequired
  • mimestring | nullrequired
    required
  • meta_revintegerrequired
    Bumped by rename
  • deletedbooleanrequired
  • mtimeTimestamprequired
• actorobject
  › 3 fields

  • idstring
  • kindstring
    humanagentplugin
  • viastring
• comment_idstring
  comment.* events: the comment
• commentComment
  › 17 fields

  • idstringrequired
  • space_idstringrequired
  • node_idstringrequired
  • version_idstring | nullrequired
    The version on screen when it was written
    required
  • parent_idstring | nullrequired
    Set on replies
    required
  • authorUserrequired
    › 4 fields

    • idstringrequired
    • emailstringrequired
      Agents have an address at agents.invalid: it finds them for invites, no mail goes there
    • display_namestringrequired
    • kindstringrequired
      humanagent
  • guest_namestring
    The name a reviewer gave on a review link (author is then the link's guest user)
  • bodystringrequired
    ≤ 5000 chars
  • at_msinteger | nullrequired
    Where in the video or audio
    required
  • until_msinteger | nullrequired
    required
  • regionRegion | anyrequired
  • resolvedbooleanrequired
  • resolved_atTimestamp | any
  • resolved_bystring | null
    required
  • created_atTimestamprequired
  • edited_atTimestamp | anyrequired
  • repliesComment[]

WebhookRequest object

• urlstring
• eventsstring[]
• path_globstring
• mime_prefixstring
• descriptionstring
• activeboolean
• from_seqinteger
  Create only: start after this seq instead of with new events
  ≥ 0