Document

Document Object

Field	Type	Description
id	snowflake	the document’s unique identifier
organisation_id	snowflake	the id of the owning organisation
organisation	organisation object	the owning organisation (full object or partial with only id)
origin_id	snowflake?	the id of the document this one was forked from, if any
number	integer	sequential number of the document within its organisation
formatted_number	string	human‑readable formatted number (e.g. “PRJ‑001”)
title	string	title of the document (2‑200 characters)
type	document type object	the document’s type (full object or partial with only id)
content_type	string	MIME type of the stored content (e.g. application/pdf, text/markdown)
default_branch_id	snowflake?	id of the default branch (draft or release)
default_branch	document branch object	the default branch (full object or partial with only id)
current_release_tag_id	snowflake?	id of the tag that marks the current released version
current_release_tag	document tag object	the current release tag (full object or partial with only id)
bookmark_count	integer	number of users who have bookmarked this document
fork_count	integer	how many times the document has been forked
branch_count	integer	total number of branches that exist for this document
open_work_item_count	integer	count of open work items linked to the document
closed_work_item_count	integer	count of closed work items linked to the document
work_item_types_count	object<snowflake, work item type count>	dictionary mapping work‑item‑type ids to their open/closed counts
project_id	snowflake?	id of the project this document belongs to
project	project object	the owning project (full or partial)
package_id	snowflake?	id of the package this document is part of
package	package object	the package (full or partial)
discipline_id	snowflake?	id of the discipline associated with the document
discipline	discipline object	the discipline (full or partial)
asset_group_id	snowflake?	id of the permanent asset group linked to the document
asset_group	asset group object	the asset group (full or partial, may include extra fields)
asset_id	snowflake?	id of the specific asset linked to the document
asset	asset object	the asset (full or partial; if part of an asset‑group, includes group context)
fields	object<snowflake, { id:string, name:string?, type:integer, value:any, units:string? }>	custom field values keyed by field id; each entry contains the field’s metadata and stored value
created_at	ISO8601 timestamp	when the document was originally created
created_by	user object	user who created the document (full or partial)
updated_at	ISO8601 timestamp	last time the document was edited (e.g. a new revision)
updated_by	user object	user who performed the latest update
accessed_at	ISO8601 timestamp?	moment the document was last accessed via the API, if supplied
tracking	object	optional tracking information (structure defined by DocumentTrack)
bookmark	object	optional bookmark information for the requesting user
permissions	object<Permission], boolean>	permission flags returned for the caller (e.g. VIEW_DOCUMENTS, EDIT_DOCUMENTS)
protection_rules	object	document‑level protection rules (if any)
is_deleted	boolean	whether the document is in a soft‑deleted state
deleted_at	ISO8601 timestamp?	when the document was soft‑deleted
deleted_by	user object	user who performed the deletion (full or partial)

Document Item Field Object

Field	Type	Description
id	snowflake	the field’s identifier
organisation_id	snowflake	the identifier of the owning organisation
required	boolean	true if a value must be supplied for this field
name	string	the field’s name (2‑200 characters)
description	string	a human‑readable description of the field
type	ItemFieldType	the field type identifier (ItemFieldType enum)
units	string	measurement units associated with the field (e.g. “kg”, “m”)
multi_line	boolean	true if the field accepts multi‑line text input
max_length?	integer?	maximum allowed length of a string value; omitted when not limited
default_value	object	the default value for the field (type depends on type)
values	array<object>	list of enumeration values for fields of type enum (empty if none)
enabled	boolean	true when the field is active and can be used

Document Item Field Enum Value Object

Field	Type	Description
id	snowflake	the enum value's identifier
value	string	the textual representation of the enum value
updated_at	ISO8601 timestamp	when the enum value was last updated
document_field_id	snowflake	the id of the associated document field
updated_by	user object	the user who performed the last update (contains only id)

Document Branch Object

Field	Type	Description
id	snowflake	the document branch identifier
organisation_id	snowflake	the id of the organisation that owns the branch
revision_id	snowflake	the id of the document revision this branch points to
revision	object	the document revision (partial) referenced by revision_id
name	string	the branch name (2‑256 characters)
protected	boolean	whether the branch is protected from deletion or modification
commit_count	integer	number of commits made on this branch
created_at	ISO8601 timestamp	when the branch was created
document_id	snowflake	the id of the document to which this branch belongs
document	document object	the document itself or a partial object containing only its id
created_by	user object	the user who created the branch (partial – contains only id)
is_deleted	boolean	true if the branch has been soft‑deleted
deleted_at?	ISO8601 timestamp?	when the branch was soft‑deleted, or null if not deleted
deleted_by?	user object?	the user who performed the deletion (partial – contains only id), or null

Document Revision Object

Field	Type	Description
id	snowflake	the revision’s identifier (stringified snowflake)
hash	hash	SHA‑256 hash of the revision content
document_id	snowflake	the identifier of the parent document
totp_token	string?	optional one‑time password token supplied by the client
revision	string	the human‑readable revision label (e.g. “A”, “1.0”)
title	string	the title of the document at this revision
clause_prefix_format	string?	format string used to build clause prefixes
clause_prefix_id	snowflake?	identifier of the prefix entity, if any
clause_digits	integer?	number of digits used for clause numbering
template_name	string?	file name of the OOXML document template (if uploaded)
template_hash	hash?	SHA hash of the stored template file
template_name_xlsx	string?	file name of the OOXML spreadsheet template (if uploaded)
template_hash_xlsx	hash?	SHA hash of the stored OOXML template file
tree	document tree?	full document‑tree structure; omitted when a partial response is requested
parents	array<string>	list of parent revision identifiers (stringified snowflakes)
message	string?	short commit message for this revision
signed	boolean	true if the revision was cryptographically signed by its creator
created_by	user object	user that created the revision
created_at	ISO8601 timestamp	creation time of the revision

Document Type Object

Field	Type	Description
id	snowflake	the document type's id
organisation_id	snowflake	the id of the organisation
name	string	the type's name (2-20 characters)
description	string	a description of the type
last_number	integer	the largest number currently issued to a document
number_format	string	a string formatter
revision_format	integer	revision format

Document Revision Sheet Object

Implements Orderable

Field	Type	Description
revision_id	snowflake	the document revision's id
sheet_id	snowflake	the document sheet's id
name	string	the document sheet's name (2-20 characters)
order	integer	the order of the sheet within the document

Document Revision Column Object

Implements Orderable

Field	Type	Description
revision_id	snowflake	the document revision's id
column_id	snowflake	the document sheet's id
name	string	the document column's name (2-20 characters)
description	string	a description of the document column
type		the document column's data type
conditional_formatting	string	the conditional formatting condition

Document Revision Clause Object

Implements Orderable

Field	Type	Description
revision_id	snowflake	the document revision's id
clause_id	snowflake	the document clause's id
text	string	the clause text (maximum 16 MiB including base 64 encoded image data)
fields	list of document fields	the document field values

Document Data Types

Document Data Units

Document Data Formats

Value	Name	Description
0	String	String
1	Decimal	Decimal number format 0.0000
2	Scientific	Scientific notation 0.0000x10^0
3	Engineering	Scientific notation where the exponent is a multiple of 3 [..., -6, -3, 0, 3, 6, ...]
4	Time	Instead of second, expressed in dd:hh:mm:ss
5	Unixtime	Number of seconds or milliseconds since the unix epoch expressed in ISO date format

Document Revision Field Object

Field	Type	Description
revision_id	snowflake	the document revision's id
field_id	snowflake	the document field's id

Document Merge Request Object

Field	Type	Description
organisation_id	snowflake	the organisation the merge request belongs to
number	integer	a sequential number for the merge request
from_branch_id	snowflake	the branch to merge
to_branch_id	snowflake	the branch to be merged to
workflow_id	snowflake	the workflow that will trigger the merge
user	user object	the creator of the document merge request
created_at	ISO8601 timestamp	when the document merge request was created

Revision Format

Name	Value	Description
none	0	No numbering scheme, use this if you issue numbers from another system. This will allow the user to manually assign both the document number and the revision.
zero	1	This scheme uses the integer numbers starting at 0.
one	2	This scheme uses the integer numbers starting at 1.
major_minor	3	This scheme uses a version number of the scheme Major.Minor allowing either the Major or the Minor component to be incremented.
major_minor_revision	4	This scheme uses a version number of the scheme Major.Minor.Revision allowing either the Major or the Minor component to be incremented. The Revision component is always incremented.
alphabet	5	This is the default scheme and uses the letters A-Z skipping "I", "O", "Q", "S", "X", "Z". The initial revision is denoted by a dash "-".
alphabet_all	6	This scheme uses the letters A-Z with the initial revision denoted by a dash "-".

Clause Number Format

Name	Value	Description
number	0	Document number
number_revision	1	Document number plus revision

Document Presence Object

Field	Type	Description
session_id	snowflake	the presence record’s unique identifier
user_id	snowflake	the id of the user whose presence is being reported
user	user object?	the user object
status	string	current presence state – one of "offline", "online" or "idle"
view_id	snowflake?	id of the document view the user is looking at (optional)
sheet_id	snowflake?	id of the sheet within the view (optional)
clause_id	snowflake?	id of the clause being edited/viewed (optional)
column_id	snowflake?	id of the column within the clause (optional)
updated_at	ISO8601 timestamp	when the presence information was last updated

Document Share Object

Field	Type	Description
id	snowflake	the share record identifier
document	document?	the shared document (full object or { "id": "<snowflake>" } )
user	user?	the user who is being granted access
organisation	organisation?	the organisation that owns the share
type	string	the share type (e.g., "document" )
status	string	current status of the share (e.g., "active", "revoked" )
scope_view	boolean	true if the recipient may view the document
scope_edit	boolean	true if the recipient may edit the document
scope_branch	boolean	true if the recipient may create branches for the document
scope_fork	boolean	true if the recipient may fork the document
scope_revisions	boolean	true if the recipient may view document revisions
scope_export	boolean	true if the recipient may export the document
share_to_users_organisation	boolean	true if the share is automatically propagated to all users in the organisation
shared_by	user?	the user who created the share record

Create Document

POST /documents

Parameters

Field	Type	Description
title	string	the document's title (2 - 200 characters)

Fork Document

POST /documents/{document.id}

This operation will create a fork of the document. The new document will be returned.

Create Document Branch

POST /documents/{document.id}/branches

Parameters

Field	Type	Description
name	string	the document branch's name (2 - 50 characters)

Create Document Sheet

POST /documents/{document.id}/revisions/{revision.hash}/sheets

This operation will create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

{
    "id": 123456,
    "hash": abdf12,
    "branch": {
        "id": 5678,
        "name": "draft",
        "user": { },
        "created_at": "2019-07-01T00:00:00+00:00",
    }
}

Parameters

Field	Type	Description
name	string	the document sheet's name (2 - 20 characters)

List Document Columns

GET /documents/{document.id}/revisions/{revision.hash}/columns

Get a list of columns for this revision of the document. Returns an array of document revision column objects.

Create Document Column

POST /documents/{document.id}/revisions/{revision.hash}/columns

This operation will create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

{
    "id": 123456,
    "hash": abdf12,
    "branch": {
        "id": 5678,
        "name": "draft",
        "user": { },
        "created_at": "2019-07-01T00:00:00+00:00"
    }
}

Modify Document Column

PATCH /documents/{document.id}/revisions/{revision.hash}/columns/{column.id}

Parameters

Field	Type	Description
name	?string	the document column's name (2-20 characters)
description	?string	a description of the document column
type	?	the document column's data type
conditional_formatting	?string	the conditional formatting condition

Delete Document Column

DELETE /documents/{document.id}/revisions/{revision.hash}/columns/{column.id}

This operation will delete a column from a revision on the branch and create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

Create Document Clause

POST /documents/{document.id}/revisions/{revision.hash}/clauses

This operation will create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

Parameters

Field	Type	Description
after	?snowflake	the clause to insert the new clause after
before	?snowflake	the clause to insert the new clause before

Modify Document Clause

PATCH /documents/{document.id}/revisions/{revision.hash}/clauses/{clause.id}

Parameters

Field	Type	Description
after	?snowflake	the clause to move the clause after
below	?snowflake	the clause to move the clause below

Delete Document Clause

DELETE /documents/{document.id}/revisions/{revision.hash}/clauses/{clause.id}

This operation will delete a clause from a revision on the branch and create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

Update Document Field

PATCH /documents/{document.id}/revisions/{revision.hash}/fields

This operation will create a new revision on the branch. The new revision will be returned. If the change cannot be merged then an error code will return.

This operation will cause all calculations to re-calculate.

Parameters

Field	Type	Description
clause_id	snowflake	the clause the updated field belongs to
column_id	snowflake	the column the updated field belongs to
value	string	the new value of the field

{
    "id": 123450,
    "hash": abdf12,
    "user": {},
    "created_at": "2019-07-01T00:00:00+00:00",
       "fields": [
        {
            "column_id": 123453,
            "clause_id": 123454,
            "value": "field value",
            "background_colour": ""
        } 
    ]
}

Get Document Revision

GET /documents/{document.id}/revisions/{revision.hash}

GET /documents/{document.id}/branches/{branch.name}

A document revision can be retrieved either by specifying a specific branch by name to get the latest revison, or by a specific revision's hash.

{
    "id": 123450,
    "hash" abdf12,
    "user" { },
    "created_at": "2019-07-01T00:00:00+00:00"
}