Protocol Documentation

Table of Contents

apikeys.proto

Top

ApiKeyDetails

Chorus API key details

FieldTypeLabelDescription
context string

The context of the API key A context id is generally used to refer to a catalogue (e.g. Metadata Catalogue). It can identify the current user, a space, another user in the system or the site as a whole. * `me`—this represents the currently authenticated user's Private Space, * `group{numeric-identifier}`—this represents a Space. The `{numeric-identifier}` is an internal identifier. If you require an id for a given Space, then use the `context` from the Space's details, * `user{numeric-identifier}`—this represents another user in the system. The `{numeric-identifier}` is an internal identifier. If you require an id for a given user, then use the `context` from the User's details, * `dom0`—this represents the whole site.

createdDate DateTime

The date/time that this object was created

id string

Unique ID of this object.

label string

An arbitrary chosen identifier for the API key

modifiedDate DateTime

The date/time that this object was last changed

ApiKeyDetailsWithToken

Chorus API key details containing the token string, only returned

on create operations

FieldTypeLabelDescription
apiKey string

The key token

context string

The context of the API key A context id is generally used to refer to a catalogue (e.g. Metadata Catalogue). It can identify the current user, a space, another user in the system or the site as a whole. * `me`—this represents the currently authenticated user's Private Space, * `group{numeric-identifier}`—this represents a Space. The `{numeric-identifier}` is an internal identifier. If you require an id for a given Space, then use the `context` from the Space's details, * `user{numeric-identifier}`—this represents another user in the system. The `{numeric-identifier}` is an internal identifier. If you require an id for a given user, then use the `context` from the User's details, * `dom0`—this represents the whole site.

createdDate DateTime

The date/time that this object was created

id string

Unique ID of this object.

label string

An arbitrary chosen identifier for the API key

modifiedDate DateTime

The date/time that this object was last changed

ApiKeysRequests

ApiKeysRequests.CreateProfileKey

FieldTypeLabelDescription
details CreateApiKeyDetails

Settings to use when creating the new API key

ApiKeysRequests.CreateSiteKey

FieldTypeLabelDescription
details CreateApiKeyDetails

Settings to use when creating the new API key

ApiKeysRequests.CreateSpacesKey

FieldTypeLabelDescription
details CreateApiKeyDetails

Settings to use when creating the new API key

spaceId string

The space for which to create the API key

ApiKeysRequests.Delete

FieldTypeLabelDescription
apiKeyId string

The ID of the API key to delete

ApiKeysRequests.Get

FieldTypeLabelDescription
apiKeyId string

IDs of the API keys to fetch details for

ApiKeysRequests.GetMulti

FieldTypeLabelDescription
apiKeyId string repeated

IDs of the API keys to fetch details for

ApiKeysRequests.GetProfileKeys

ApiKeysRequests.GetSiteKeys

ApiKeysRequests.GetSpacesKeys

FieldTypeLabelDescription
spaceId string

The space for which to get the API keys

ApiKeysRequests.Set

FieldTypeLabelDescription
apiKeyId string

ID of the API key to update

details SettableApiKeyDetails

API key details to set

update_mask google.protobuf.FieldMask

ApiKeysResponses

ApiKeysResponses.Delete

ApiKeysResponses.GetMulti

FieldTypeLabelDescription
response ApiKeyDetails repeated

ApiKeysResponses.GetProfileKeys

FieldTypeLabelDescription
response string repeated

ApiKeysResponses.GetSiteKeys

FieldTypeLabelDescription
response string repeated

ApiKeysResponses.GetSpacesKeys

FieldTypeLabelDescription
response string repeated

CreateApiKeyDetails

Settings to use when creating a new API key

FieldTypeLabelDescription
label string

An arbitrary chosen identifier for the API key

SettableApiKeyDetails

Settings to use for updating an API key's details

FieldTypeLabelDescription
label google.protobuf.StringValue

An arbitrary chosen identifier for the API key

ApiKeys

Method NameRequest TypeResponse TypeDescription
CreateProfileKey ApiKeysRequests.CreateProfileKey ApiKeyDetailsWithToken

Create a new profile API key with the supplied label

CreateSiteKey ApiKeysRequests.CreateSiteKey ApiKeyDetailsWithToken

Create a new site API key with the supplied label

CreateSpacesKey ApiKeysRequests.CreateSpacesKey ApiKeyDetailsWithToken

Create a new space API key with the supplied label

Delete ApiKeysRequests.Delete ApiKeysResponses.Delete

This method removes a single API key from Chorus. The API session must have sufficient rights to remove the API key.

Get ApiKeysRequests.Get ApiKeyDetails

This method returns the creation date and text label for API keys. Additionally, the context for each key (dom0 for the site, a GUID for a space or dom0 for a user) is returned.

GetMulti ApiKeysRequests.GetMulti ApiKeysResponses.GetMulti

This method returns the creation date and text label for API keys. Additionally, the context for each key (dom0 for the site, a GUID for a space or dom0 for a user) is returned.

GetProfileKeys ApiKeysRequests.GetProfileKeys ApiKeysResponses.GetProfileKeys

This method retrieves the API keys that are owned by the current session user. Further details about keys returned can be retrieved using the other API endpoints, above.

GetSiteKeys ApiKeysRequests.GetSiteKeys ApiKeysResponses.GetSiteKeys

Retrieve a list of API key IDs configured for the site

GetSpacesKeys ApiKeysRequests.GetSpacesKeys ApiKeysResponses.GetSpacesKeys

Retrieve a list of the API keys configured for a specific Space. Note that API keys of this sort are equivalent to the Manager role of a user in the Space.

Set ApiKeysRequests.Set ApiKeyDetails

This method updates the text label of an API key in Chorus. The response will provide the update details of the key.

auth.proto

Top

AuthDetails

Details about the currently authenticated user.

FieldTypeLabelDescription
userId string

The id of the user. This will be null for non-authenticated users.

userType AuthDetails.Type

The type of the user.

AuthRequests

AuthRequests.GetAuthDetails

AuthRequests.ImpersonateByEmail

FieldTypeLabelDescription
email string

The e-mail address of the account to impersonate

AuthRequests.ImpersonateById

FieldTypeLabelDescription
userId string

The GUID or ID of the account to impersonate

AuthRequests.ImpersonateByUsername

FieldTypeLabelDescription
userName string

The user account's username

AuthRequests.Login

FieldTypeLabelDescription
password string

The user account's password

username string

The user account's username

AuthRequests.LoginWithKey

FieldTypeLabelDescription
apiKey string

An API key generated by Chorus.

AuthRequests.Logout

AuthResponses

AuthResponses.Logout

LoginDetails

Response of a login method for normal users. This contains details of the user that has logged in.

FieldTypeLabelDescription
sessionId string

The new/updated session ID for further use

userDetails UserDetails

User details for the logged in user

AuthDetails.Type

Represents the type of a normal user.

NameNumberDescription
NotLoggedIn 0

Represents a non-authenticated user.

User 1

Represents a normal Chorus user.

ExternalUser 2

Represents an external chorus user.

Auth

Method NameRequest TypeResponse TypeDescription
GetAuthDetails AuthRequests.GetAuthDetails AuthDetails

Returns details about the currently active user.

ImpersonateByEmail AuthRequests.ImpersonateByEmail LoginDetails

Changes the active user for the current session to that specified. NB: e-mail lookup is only possible where the address is unique. If there are multiple users with the supplied address, a NOT_UNIQUE error will be returned. This method is only available for sessions created by a Site API key

ImpersonateById AuthRequests.ImpersonateById LoginDetails

Changes the active user for the current session to that specified. This method is only available for sessions created by a Site API key

ImpersonateByUsername AuthRequests.ImpersonateByUsername LoginDetails

Changes the active user for the current session to that specified. This method is only available for sessions created by a Site API key

Login AuthRequests.Login LoginDetails

Login to Chorus using a supplied username and password. This method should only be used if you're allowing users to login using their Chorus username and password. **The usernames and passwords must not be persistently stored and should be requested for each login. Use API Keys, and `LoginWithKey` if you require persistent user access.**

LoginWithKey AuthRequests.LoginWithKey LoginDetails

Login to Chorus using an API Key. The key may be for the site, a Space or a user account.

Logout AuthRequests.Logout AuthResponses.Logout

End the Chorus API session. Please use this method when your script or other integration has finished and you do not require the session again.

bin.proto

Top

BinRequests

BinRequests.Empty

BinRequests.Get

BinResponses

BinResponses.Empty

Bin

Method NameRequest TypeResponse TypeDescription
Empty BinRequests.Empty BinResponses.Empty

Get details about the user's bin

Get BinRequests.Get FolderDetails

Get details about the user's bin

content.proto

Top

ContentItemDetails

One of multiple content specific details of an item in Chorus.

FieldTypeLabelDescription
derivative FileDetails

file FileDetails

fileLink FileLinkDetails

folder FolderDetails

folderLink FolderLinkDetails

ContentItemWithDetails

Representation of a type of an item of content in Chorus.

FieldTypeLabelDescription
details ContentItemDetails

Provides type content specific details for the item in question

id string

Unique ID of this object.

name string

type ContentItemType

ContentRequests

ContentRequests.CreateFolder

FieldTypeLabelDescription
details CreateFolderDetails

Settings to use when creating the new folder

folderId string

ID of the parent folder

ContentRequests.Delete

FieldTypeLabelDescription
itemId string

ID of the item to delete

ContentRequests.Get

FieldTypeLabelDescription
itemId string

The ID of an item

FieldTypeLabelDescription
folderId string

Specify the folder ID from which to fetch file links

ContentRequests.GetChildFiles

FieldTypeLabelDescription
folderId string

Specify the folder ID from which to fetch files

FieldTypeLabelDescription
folderId string

Specify the folder ID from which to fetch folder links

ContentRequests.GetChildFolders

FieldTypeLabelDescription
folderId string

Specify the folder ID from which to fetch folders

ContentRequests.GetChildRights

FieldTypeLabelDescription
folderId string

Specify the folder or folder link from which to fetch rights

ContentRequests.GetContents

FieldTypeLabelDescription
folderId string

Specify the folder ID to fetch

ContentRequests.GetMetadata

FieldTypeLabelDescription
itemId string

Specify the item for which to fetch metadata

ContentRequests.GetMulti

FieldTypeLabelDescription
itemIds string repeated

The IDs of the items

ContentRequests.GetRights

FieldTypeLabelDescription
itemId string

Specify the item for which to fetch rights

ContentRequests.SearchFolder

FieldTypeLabelDescription
folderId string

ID of the folder or folder link to search within

query string

Search text

ContentResponses

ContentResponses.Delete

FieldTypeLabelDescription
response string repeated

ContentResponses.GetChildFiles

FieldTypeLabelDescription
response string repeated

FieldTypeLabelDescription
response string repeated

ContentResponses.GetChildFolders

FieldTypeLabelDescription
response string repeated

ContentResponses.GetContents

FieldTypeLabelDescription
response string repeated

ContentResponses.GetMulti

FieldTypeLabelDescription
response ContentItemWithDetails repeated

ContentResponses.SearchFolder

FieldTypeLabelDescription
response string repeated

ContentRights

Rights the current session has on the given item.

FieldTypeLabelDescription
createDerivative bool

rights to create a derivative from the item

delete bool

delete rights for the item

download bool

download rights for the item

edit bool

edit rights for the item

publish bool

publish rights for the item

share bool

share rights for the item

upload bool

upload rights for the item

view bool

view rights for the item

viewAttachments bool

rights to view the item's attachments

ContentItemType

Representation of a type of content in Chorus.

NameNumberDescription
FILE 0

This is a file

FILE_LINK 1

This is a link to a file.

FOLDER 2

This is a folder.

FOLDER_LINK 3

This is a link to a folder.

DERIVATIVE 4

This is a file derivative.

Content

Method NameRequest TypeResponse TypeDescription
CreateFolder ContentRequests.CreateFolder FolderDetails

Create a new folder under a parent folder.

Delete ContentRequests.Delete ContentResponses.Delete

Delete an item

Get ContentRequests.Get ContentItemWithDetails

Get the details about items, which can include files, file links, folders, folder links (including collections and Smart Collections) or derivatives.

GetChildFileLinks ContentRequests.GetChildFileLinks ContentResponses.GetChildFileLinks

Get the child file links for a given parent folder / folder link

GetChildFiles ContentRequests.GetChildFiles ContentResponses.GetChildFiles

Get the child files for a given parent folder / folder link

GetChildFolderLinks ContentRequests.GetChildFolderLinks ContentResponses.GetChildFolderLinks

Get the child folder links for a given parent folder / folder link

GetChildFolders ContentRequests.GetChildFolders ContentResponses.GetChildFolders

Get the child folders for a given parent folder / folder link

GetChildRights ContentRequests.GetChildRights ContentRights

Get rights for a folder or folder link's contents, according to the API session's underlying user account. Rights refers to user abilities such as view, download, edit and upload.

GetContents ContentRequests.GetContents ContentResponses.GetContents

Get the contents for a given parent folder / folder link

GetMetadata ContentRequests.GetMetadata MetadataValueMap

Gets the metadata for an item.

GetMulti ContentRequests.GetMulti ContentResponses.GetMulti

Get the details about items, which can include files, file links, folders, folder links (including collections and Smart Collections) or derivatives.

GetRights ContentRequests.GetRights ContentRights

Get rights for an item, according to the API session's underlying user account. Rights refers to user abilities such as view, download, edit and upload.

SearchFolder ContentRequests.SearchFolder ContentResponses.SearchFolder

Perform a general search within a folder. The search behaviour is identical to entering a text string in the search bar in the Chorus UI: the scope of the search is limited to the files accessible by the API session, and the metadata fields searched are those included in 'General' search in the catalogs accessible by that user.

contexts.proto

Top

ContextDetails

Details about a "context". A context is the root of a section of the site.

FieldTypeLabelDescription
avatarUrl string

The URL for the avatar of the context.

backingFolderId google.protobuf.StringValue

ID of the folder that is the home of this context. This will be null if the current user cannot view the folders.

id string

The ID of the context. A context id is generally used to refer to a catalogue (e.g. Metadata Catalogue). It can identify the current user, a space, another user in the system or the site as a whole. * `me`—this represents the currently authenticated user's Private Space, * `group{numeric-identifier}`—this represents a Space. The `{numeric-identifier}` is an internal identifier. If you require an id for a given Space, then use the `context` from the Space's details, * `user{numeric-identifier}`—this represents another user in the system. The `{numeric-identifier}` is an internal identifier. If you require an id for a given user, then use the `context` from the User's details, * `dom0`—this represents the whole site.

name string

The name of the context.

ownerId google.protobuf.StringValue

ID of the Space or User that this is the context of. This will be null either if you cannot see the Space or User, or this is a context for the site.

parentId string

The ID of the parent context.

type ContextType

The type of the context.

ContextsRequests

ContextsRequests.Get

FieldTypeLabelDescription
contextId string

An array of contexts for which details should be returned. A context id is generally used to refer to a catalogue (e.g. Metadata Catalogue). It can identify the current user, a space, another user in the system or the site as a whole. * `me`—this represents the currently authenticated user's Private Space, * `group{numeric-identifier}`—this represents a Space. The `{numeric-identifier}` is an internal identifier. If you require an id for a given Space, then use the `context` from the Space's details, * `user{numeric-identifier}`—this represents another user in the system. The `{numeric-identifier}` is an internal identifier. If you require an id for a given user, then use the `context` from the User's details, * `dom0`—this represents the whole site.

ContextsRequests.GetChildren

FieldTypeLabelDescription
contextId string

The parent context for which to get children A context id is generally used to refer to a catalogue (e.g. Metadata Catalogue). It can identify the current user, a space, another user in the system or the site as a whole. * `me`—this represents the currently authenticated user's Private Space, * `group{numeric-identifier}`—this represents a Space. The `{numeric-identifier}` is an internal identifier. If you require an id for a given Space, then use the `context` from the Space's details, * `user{numeric-identifier}`—this represents another user in the system. The `{numeric-identifier}` is an internal identifier. If you require an id for a given user, then use the `context` from the User's details, * `dom0`—this represents the whole site.

ContextsRequests.GetMulti

FieldTypeLabelDescription
contextIds string repeated

An array of contexts for which details should be returned. A context id is generally used to refer to a catalogue (e.g. Metadata Catalogue). It can identify the current user, a space, another user in the system or the site as a whole. * `me`—this represents the currently authenticated user's Private Space, * `group{numeric-identifier}`—this represents a Space. The `{numeric-identifier}` is an internal identifier. If you require an id for a given Space, then use the `context` from the Space's details, * `user{numeric-identifier}`—this represents another user in the system. The `{numeric-identifier}` is an internal identifier. If you require an id for a given user, then use the `context` from the User's details, * `dom0`—this represents the whole site.

FieldTypeLabelDescription
contextId string

ID of the context for which to get shared links A context id is generally used to refer to a particular root of content. It can identify the current user, a Space or another user in the system. * `me`—this represents the currently authenticated user's Private Space, * `group{numeric-identifier}`—this represents a Space. The `{numeric-identifier}` is an internal identifier. If you require an id for a given Space, then use the `context` from the Space's details, * `user{numeric-identifier}`—this represents another user in the system. The `{numeric-identifier}` is an internal identifier. If you require an id for a given user, then use the `context` from the User's details.

ContextsResponses

ContextsResponses.GetChildren

FieldTypeLabelDescription
response string repeated

ContextsResponses.GetMulti

FieldTypeLabelDescription
response ContextDetails repeated

FieldTypeLabelDescription
response SharedLinkDetails repeated

ContextType

Type of the context.

NameNumberDescription
Unknown 0

This represents a context of an unknown type.

PrivateSpace 1

This represents the current user's Private Space

Space 2

This represents a Space

OtherUser 3

This represents a different user

Site 4

This represents site content

Contexts

Method NameRequest TypeResponse TypeDescription
Get ContextsRequests.Get ContextDetails

Retrieve details of contexts. When you have received context values from other API responses, you can use this method to retrieve the details of those contexts, which include an avatar image URL, names, parent IDs and so on. Contexts: - me—this represents the currently authenticated user's Private Space, - group{numeric-identifier}—this represents a Space. The {numeric-identifier} is an internal identifier. If you require an id for a given Space, then use the context from the Space's details, - user{numeric-identifier}—this represents another user in the system. The {numeric-identifier} is an internal identifier. If you require an id for a given user, then use the context from the User's details. @param

GetChildren ContextsRequests.GetChildren ContextsResponses.GetChildren

Get the logical areas of Chorus visible to the specified context. This will return the site (dom0) context, the user's own home directory ("me"), the home directories of any spaces to which the user belongs, and the public folders of any other users or spaces in the site. The context IDs returned are suitable for use with Folders.GetTopLevelFolders and other methods that use contexts. Contexts: - me—this represents the currently authenticated user's Private Space, - group{numeric-identifier}—this represents a Space. The {numeric-identifier} is an internal identifier. If you require an id for a given Space, then use the context from the Space's details, - user{numeric-identifier}—this represents another user in the system. The {numeric-identifier} is an internal identifier. If you require an id for a given user, then use the context from the User's details. @param

GetMulti ContextsRequests.GetMulti ContextsResponses.GetMulti

Retrieve details of contexts. When you have received context values from other API responses, you can use this method to retrieve the details of those contexts, which include an avatar image URL, names, parent IDs and so on. Contexts: - me—this represents the currently authenticated user's Private Space, - group{numeric-identifier}—this represents a Space. The {numeric-identifier} is an internal identifier. If you require an id for a given Space, then use the context from the Space's details, - user{numeric-identifier}—this represents another user in the system. The {numeric-identifier} is an internal identifier. If you require an id for a given user, then use the context from the User's details. @param

GetSharedLinks ContextsRequests.GetSharedLinks ContextsResponses.GetSharedLinks

Get details about the shared links for a context. This is only available for Users and Spaces.

core.proto

Top

CoreRequests

CoreRequests.GetEnvironment

DateTime

This is a representation of a date time.

FieldTypeLabelDescription
rfc3339 string

The date encoded as per RFC-3339 (a.k.a ATOM)

timestamp int64

this is the date/time represented as the number of seconds since the Unix Epoch (January 1 1970, 00:00:00 UTC)

EnvironmentDetails

Details of the Chorus server.

FieldTypeLabelDescription
browserTitle string

The version of the title to use as the browser title (this often is longer and more verbose). If no specific browser title has been configured, then this will be the same as the 'title'.

title string

The site's title. This is used for the shortcuts and other places referring to the site.

version string

The current version of Chorus.

Core

Method NameRequest TypeResponse TypeDescription
GetEnvironment CoreRequests.GetEnvironment EnvironmentDetails

Returns the environment settings for the current user; useful for initial configuration of a UI or API based application.

directurls.proto

Top

DirectUrlSettings

Allows specification of the file returned via a Direct URL.

FieldTypeLabelDescription
blur google.protobuf.Int64Value

Sigma value for Gaussian blur

crop DirectUrlSettings.CropSettings

Details of a crop to apply

download google.protobuf.BoolValue

If true, this changes the content-type to application/x-force-download and forces browsers to trigger a download.

dpi google.protobuf.Int64Value

DPI for output image

filename google.protobuf.StringValue

Specify a filename to append to the URL (defaults to original file name)

fit DirectUrlSettings.FitMode

the desired method of resolving aspect ratio differences between the requested input and output

format DirectUrlSettings.FileFormat

Format code for requested file format

height google.protobuf.Int64Value

Height of output file in pixels

page google.protobuf.Int64Value

the page number to download, should be zero-indexed (e.g. the first page is '0'). Except when downloading the original, this will default to '0'

quality google.protobuf.Int64Value

A quality parameter for lossy formats like JPEG - accepted range 60-99, default is 85. Smaller parameters yield smaller filesize but lower fidelity

rotate google.protobuf.Int64Value

Rotation angle in degrees

width google.protobuf.Int64Value

Width of output file in pixels

DirectUrlSettings.CropSettings

The settings to use for cropping a file.

FieldTypeLabelDescription
height int64

Height, in pixels, of the area to crop.

width int64

Width, in pixels, of the area to crop.

x int64

Pixel on the `x` axis in which to start the crop.

y int64

Pixel on the `y` axis in which to start the crop.

DirectUrlSettings.FileFormat

Representation of the possible file formats that can be requested for a Direct URL.

NameNumberDescription
ORIGINAL 0

The created link will have the same format as the original.

JPG 1

The created link will be for a 'JPG' version of the file.

GIF 2

The created link will be for a 'GIF' version of the file.

PNG 3

The created link will be for a 'PNG' version of the file.

TIF 4

The created link will be for a 'TIF' version of the file.

WEB 5

The created link will be one of 'JPG', 'GIF' or 'PNG'. Exactly which will be based on the type of the original file.

DirectUrlSettings.FitMode

Representation of the 'fit mode' for a requested crop. This is the strategy to use when the requested crop's dimensions

don't match the output dimensions or aspect ratio.

NameNumberDescription
SCALE 0

Scale the resultant image so that both dimensions are at least the size requested

STRETCH 1

Stretch the resultant image so that it is exactly the supplied size

CROP 2

Crop the resultant image such that it does not exceed the desired dimensions

PAD 3

Pad the image with whitespace so that it is exactly the supplied dimensions

files.proto

Top

AudioDetails

Audio specific details about a file in Chorus.

FieldTypeLabelDescription
durationSecs double

Audio duration in seconds

DocumentDetails

Document specific details about a file in Chorus.

FieldTypeLabelDescription
height int64

Document height

pageCount int64

Document page count

width int64

Document width

FileDetails

Details about a file in Chorus.

FieldTypeLabelDescription
canViewOriginal bool

If the file is a derivative, whether the current user can see the original file

createdDate DateTime

The date/time that this object was created

filename string

The name of the file

fileSizeBytes int64

fileType FileType

The type of the file

id string

Unique ID of this object.

isDerivative bool

Whether the file is a derivative or not.

media MediaDetails

modifiedDate DateTime

The date/time that this object was last changed

originalAssetId google.protobuf.StringValue

If the file is a derivative, the guid for the original file

ownerId google.protobuf.StringValue

Unique ID of the object's owning user or space

parentId string

The GUID of the folder containing this file

revisionNumber int64

the revision number of the file

thumbnails Thumbnails

populated keys depend on the get options (e.g. withExtraThumbs)

FileLinkDetails

Details about a file link in Chorus.

FieldTypeLabelDescription
createdDate DateTime

The date/time that this object was created

id string

Unique ID of this object.

linkName string

The name of the linked file.

modifiedDate DateTime

The date/time that this object was last changed

originalFileId string

The ID of the linked file.

originalFileType FileType

The type of the linked file.

FilesRequests

FilesRequests.Attach

FieldTypeLabelDescription
attachedFileIds string repeated

The IDs of the File(s) to attach

fileId string

The ID of the File to which the attachment should be added

FilesRequests.DeleteDirectUrl

FieldTypeLabelDescription
fileId string

The ID of the file for which to revoke the Direct URLs.

FilesRequests.Detach

FieldTypeLabelDescription
attachedFileId string

The ID of the File to remove as an attachment

fileId string

The ID of the File from which the attachment should be removed

FilesRequests.DetachAll

FieldTypeLabelDescription
fileId string

The file to update

FilesRequests.Get

FieldTypeLabelDescription
fileId string

The ID of the file

FilesRequests.GetAttachments

FieldTypeLabelDescription
fileId string

The ID of the File for which to list attachments

FilesRequests.GetDirectUrl

FieldTypeLabelDescription
fileId string

ID of the file for which to get the Direct URL.

settings DirectUrlSettings

Settings to control how the returned file looks. Supplying no settings will return a link to the original file.

FieldTypeLabelDescription
linkId string

The ID of the file link

FilesRequests.GetLinkMulti

FieldTypeLabelDescription
linkIds string repeated

The IDs of the file links

FilesRequests.GetMetadata

FieldTypeLabelDescription
fileId string

The files to get metadata for

FilesRequests.GetMulti

FieldTypeLabelDescription
fileIds string repeated

The IDs of the files

FilesRequests.GetTemporaryDirectUrl

FieldTypeLabelDescription
fileId string

ID of the file for which to get the Direct URL

settings DirectUrlSettings

Settings to control how the returned file looks. Supplying no settings will return a link to the original file.

FilesResponses

FilesResponses.Attach

FieldTypeLabelDescription
response FileDetails repeated

FilesResponses.DeleteDirectUrl

FilesResponses.Detach

FieldTypeLabelDescription
response FileDetails repeated

FilesResponses.DetachAll

FilesResponses.GetAttachments

FieldTypeLabelDescription
response FileDetails repeated

FilesResponses.GetDirectUrl

FieldTypeLabelDescription
response string

FilesResponses.GetLinkMulti

FieldTypeLabelDescription
response FileLinkDetails repeated

FilesResponses.GetMulti

FieldTypeLabelDescription
response FileDetails repeated

FilesResponses.GetTemporaryDirectUrl

FieldTypeLabelDescription
response string

GenericDetails

Generic details about a file in Chorus.

ImageDetails

Image specific details about a file in Chorus.

FieldTypeLabelDescription
height int64

Image height in pixels

width int64

Image width in pixels

MediaDetails

One of multiple media specific details of a file in Chorus.

FieldTypeLabelDescription
audio AudioDetails

Specific details about an audio file

document DocumentDetails

Specific details about a document

generic GenericDetails

A catch-all details type for generic files

image ImageDetails

Specific details about an image file

video VideoDetails

Specific details about a video file

ThumbDetails

Details about a thumbnail for a file.

FieldTypeLabelDescription
height int64

Height in pixels

url string

The URL to access the thumbnail

width int64

Width in pixels

Thumbnails

A collection of available thumbnail sizes/types for a file.

FieldTypeLabelDescription
large ThumbDetails

medium ThumbDetails

small ThumbDetails

VideoDetails

Video specific details about a file in Chorus.

FieldTypeLabelDescription
durationSecs double

Video duration in seconds

framerate double

Video framerate in frames per second

height int64

Video height in pixels

width int64

Video width in pixels

FileType

Represents the type of a file.

NameNumberDescription
PICTURE 0

Indicates that this is an image file.

MOVIE 1

Indicates that this is a video file.

DOCUMENT 2

Indicates that this is a document file.

EXECUTABLE 3

Indicates that this is an executable file.

MUSIC 4

Indicates that this is an audio file.

GENERIC 5

Indicates that this is a generic file.

Files

Method NameRequest TypeResponse TypeDescription
Attach FilesRequests.Attach FilesResponses.Attach

Attach one or more files to another file. Each file is specified by its GUID.

DeleteDirectUrl FilesRequests.DeleteDirectUrl FilesResponses.DeleteDirectUrl

Delete any existing Direct URL (temporary or permanent) for the given file. The file is specified by its GUID. Note: this method deletes all direct URLs associated with the file.

Detach FilesRequests.Detach FilesResponses.Detach

Removes an attachment (attachedFieldId) from a file (fileId). Each file is specified by its GUID.

DetachAll FilesRequests.DetachAll FilesResponses.DetachAll

Remove all attached files from a file specified by its GUID. The attachments are removed but no files are deleted from Chorus.

Get FilesRequests.Get FileDetails

Get the details of files, specified using the files' GUIDs. Details returned include technical data such as file sizes, change dates, owners and thumbnail images, but excludes metadata (see /rest/v1/files/{fileId}/metadata).

GetAttachments FilesRequests.GetAttachments FilesResponses.GetAttachments

Retrieves a list of attached files for the specified file GUID. Each attachment is returned in the same format as the /rest/v1/files/{fileId} method.

GetDirectUrl FilesRequests.GetDirectUrl FilesResponses.GetDirectUrl

Get a permanent Direct URL for the given file, with optional cropping, resizing and other technical processing applied. The returned URL is suitable for embedding in other web content, and is delivered via Third Light's Content Delivery Network (CDN). Note: direct URLs from this method are not protected by sessions or other authentication. Direct URLs are considered to publicly-cacheable content.

GetLink FilesRequests.GetLink FileLinkDetails

Retrieve details for file links.

GetLinkMulti FilesRequests.GetLinkMulti FilesResponses.GetLinkMulti

Retrieve details for file links.

GetMetadata FilesRequests.GetMetadata MetadataValueMap

Gets the metadata for a file.

GetMulti FilesRequests.GetMulti FilesResponses.GetMulti

Get the details of files, specified using the files' GUIDs. Details returned include technical data such as file sizes, change dates, owners and thumbnail images, but excludes metadata (see /rest/v1/files/{fileId}/metadata).

GetTemporaryDirectUrl FilesRequests.GetTemporaryDirectUrl FilesResponses.GetTemporaryDirectUrl

Get a temporary Direct URL for the given file, with optional cropping, resizing and other technical processing applied. This method is suitable for downloading a file but as the URL will expire after 7 days, it should not be used in other web content. When the URL needs to be permanent, use /rest/v1/files/{fileId}/directUrl instead. Note: direct URLs from this method are not protected by sessions or other authentication. Direct URLs are considered to publicly-cacheable content.

folders.proto

Top

CreateFolderDetails

Settings to use when creating a new folder.

FieldTypeLabelDescription
description string

The description of the newly created folder.

name string

The name of the newly created folder.

searchOptions FolderSearchOptions

Search options to use (only valid when creating a smart collection).

searchParams FolderSearchParams repeated

Search params to use (only valid when creating a smart collection).

type FolderType

The type of folder to create.

FolderDetails

Details about a Chorus folder.

FieldTypeLabelDescription
context string

The identifier for the containing context

createdDate DateTime

The date/time that this object was created

description string

The description of the folder.

id string

Unique ID of this object.

modifiedDate DateTime

The date/time that this object was last changed

name string

parentId google.protobuf.StringValue

The ID of the parent of the folder, or null if there is no parent

type FolderType

The type of the folder.

FolderLinkDetails

Details about a folder link in Chorus.

FieldTypeLabelDescription
createdDate DateTime

The date/time that this object was created

id string

Unique ID of this object.

linkName string

The name of the linked folder.

modifiedDate DateTime

The date/time that this object was last changed

originalFolderId string

The ID of the linked folder.

FolderSearchOptions

Options to use when creating a smart collection.

FieldTypeLabelDescription
includeFileCopies bool

Default true: include multiple links to the same files (e.g. when visible via both a collection and the folder) in the search results

includeFolderCopies bool

Default false: include multiple links to the same folders (e.g. via shares) in the search results

includeFolders bool

Default false: include folders in the search results

resultLimit int64

maximum number of results for the search

FolderSearchParams

Search parameters used by a smart collection.

FieldTypeLabelDescription
condition string

condition to check in the search logic

tagName string

name of the tag to perform the search on

type string

the type of search to perform

value string

value used in the search conditional

FoldersRequests

FoldersRequests.Get

FieldTypeLabelDescription
folderId string

The of the folder

FoldersRequests.GetChildFiles

FieldTypeLabelDescription
folderId string

The ID of the folder to list

FoldersRequests.GetChildFolders

FieldTypeLabelDescription
folderId string

The ID of the folder to list

FieldTypeLabelDescription
linkId string

The ID of the folder link

FoldersRequests.GetLinkMulti

FieldTypeLabelDescription
linkIds string repeated

The IDs of the folder links

FoldersRequests.GetMulti

FieldTypeLabelDescription
folderIds string repeated

The IDs of the folder

FoldersRequests.Set

FieldTypeLabelDescription
details SettableFolderDetails

The folder details to set.

folderId string

A folder ID for the folder of interest.

update_mask google.protobuf.FieldMask

FoldersResponses

FoldersResponses.GetChildFiles

FieldTypeLabelDescription
response FileDetails repeated

FoldersResponses.GetChildFolders

FieldTypeLabelDescription
response FolderDetails repeated

FoldersResponses.GetLinkMulti

FieldTypeLabelDescription
response FolderLinkDetails repeated

FoldersResponses.GetMulti

FieldTypeLabelDescription
response FolderDetails repeated

SettableFolderDetails

Settings to use for updating a folder's details.

FieldTypeLabelDescription
description google.protobuf.StringValue

The description of the folder.

name google.protobuf.StringValue

The name of the folder.

FolderType

Representation of the type of a folder in Chorus.

NameNumberDescription
Container 0

This is a generic container.

Folder 1

This is a normal folder.

SmartCollection 2

This is a Smart Collection.

Collection 3

This is a Collection.

RecycleBin 4

This is a Recycle Bin.

ContextFolder 5

This is the root folder of a Context (e.g. a Space)

SearchResults 6

This is a folder that contains the results of a search.

DeletedFolder 7

This is a folder that is in the recycle bin.

SearchRoot 8

This is the parent folder of a user's search results.

ShareCollection 9

This is a collection created to share some files with other users or Spaces.

SharedLinkCollection 10

This is a collection created to share some files or folders as a link.

SharesRoot 11

This is the root folder where a user or Space's Share Collections are created.

SharedLinksRoot 12

This is the root where a user or Space's Shared Link Collections are created.

IncomingAttachments 13

This is a collection that contains a file's incoming attachments.

OutgoingAttachments 14

This is a collection that contains a file's outgoing attachments.

WorkflowFolder 15

This is a folder associated with a workflow. Unlike a `WorkflowCollection`, it can contain original files and folders.

WorkflowCollection 16

This is a collection associated with a workflow. It can contain links to files elsewhere in Chorus.

WorkflowPrivateRoot 17

This is the root where a Space's WorkflowFolders and WorkflowCollections are created.

DerivativeCollection 18

This is a collection associated with a derivative. It can contain links to derivatives elsewhere in Chorus.

SyncFolder 19

This is a folder used by the Chorus Sync application.

PrivateCollection 20

This is a private collection (restricted to private space, confers no access rights)

WorkflowBatchCollection 21

This is a collection of accepted workflow collections from one workflow request to multiple workflows.

Folders

Method NameRequest TypeResponse TypeDescription
Get FoldersRequests.Get FolderDetails

Retrieves details of container GUIDs. The container can be a folder, collection or Smart Collection as well as other containers like the recycle bin or shares. For details of the container type returned, see [FolderDetails](/apidocs/grpc/#chorus.FolderDetails). The container's details, including its name, description, owner, dates and context will be returned. Contexts: - me—this represents the currently authenticated user's Private Space, - group{numeric-identifier}—this represents a Space. The {numeric-identifier} is an internal identifier. If you require an id for a given Space, then use the context from the Space's details, - user{numeric-identifier}—this represents another user in the system. The {numeric-identifier} is an internal identifier. If you require an id for a given user, then use the context from the User's details. @param

GetChildFiles FoldersRequests.GetChildFiles FoldersResponses.GetChildFiles

Retrieves a list of the files in the container, specified by its GUID. Note that this method does not return a recursive list of files stored in any sub-containers, so you will typically use it in conjunction with /rest/v1/folders/{folderId}/folders to get sub-containers.

GetChildFolders FoldersRequests.GetChildFolders FoldersResponses.GetChildFolders

Retrieves a list of the sub-containers in the container, specified by its GUID. Note that this method does not return any lower sub-containers, so you will typically use it recursively.

GetLink FoldersRequests.GetLink FolderLinkDetails

Retrieve details for folder links.

GetLinkMulti FoldersRequests.GetLinkMulti FoldersResponses.GetLinkMulti

Retrieve details for folder links.

GetMulti FoldersRequests.GetMulti FoldersResponses.GetMulti

Retrieves details of container GUIDs. The container can be a folder, collection or Smart Collection as well as other containers like the recycle bin or shares. For details of the container type returned, see [FolderDetails](/apidocs/grpc/#chorus.FolderDetails). The container's details, including its name, description, owner, dates and context will be returned. Contexts: - me—this represents the currently authenticated user's Private Space, - group{numeric-identifier}—this represents a Space. The {numeric-identifier} is an internal identifier. If you require an id for a given Space, then use the context from the Space's details, - user{numeric-identifier}—this represents another user in the system. The {numeric-identifier} is an internal identifier. If you require an id for a given user, then use the context from the User's details. @param

Set FoldersRequests.Set FolderDetails

Set details on a folder. Allows setting the search parameters for a Smart Folder.

internalApi.proto

Top

InternalApiRequest

FieldTypeLabelDescription
Method string

Payload string

InternalApiResponse

FieldTypeLabelDescription
Output string

InternalApi

Method NameRequest TypeResponse TypeDescription
Do InternalApiRequest InternalApiResponse

metadata.proto

Top

Field

Represents the details of a metadata field.

FieldTypeLabelDescription
dataType string

the data type of the metadata field

description string

A description of the field

displayType string

the display type of the field

readOnly bool

whether the field is read only

searchSettings FieldSearchSettings

the search settings for the metadata field

supportedFileTypes string repeated

types of file supported by this metadata field

tagName string

The tag name

FieldSearchSettings

Represents the search details of a metadata field.

FieldTypeLabelDescription
advancedSearch bool

whether the field is available in advanced search

generalSearch bool

whether the field is available in general search

MetadataRequests

MetadataRequests.DeleteMetadataValues

FieldTypeLabelDescription
details MetadataValue

the value details to delete

itemId string

The file or folder to delete the metadata for

tagName string

The name of the tag for which to delete the metadata

MetadataRequests.GetField

FieldTypeLabelDescription
tagName string

The id of the field of which to get the details

MetadataRequests.GetFieldMulti

FieldTypeLabelDescription
tagNames string repeated

The id of the field of which to get the details

MetadataRequests.GetMetadataFields

FieldTypeLabelDescription
itemId string

The item to get metadata fields for

MetadataRequests.GetMetadataPanels

FieldTypeLabelDescription
itemId string

The item to get metadata panel IDs for

MetadataRequests.GetMetadataValues

FieldTypeLabelDescription
itemId string

The file or folder to get metadata for

tagName string

The name of the tag for which to retrieve the values

MetadataRequests.GetPanel

FieldTypeLabelDescription
panelId string

The id of the panel for which to get the details

MetadataRequests.GetPanelMulti

FieldTypeLabelDescription
panelIds string repeated

The id of the panel for which to get the details

MetadataRequests.GetProfileVocab

FieldTypeLabelDescription
tagName string

The name of the tag for which to retrieve the vocab

MetadataRequests.GetSiteVocab

FieldTypeLabelDescription
tagName string

The name of the tag for which to retrieve the vocab

MetadataRequests.GetSpaceVocab

FieldTypeLabelDescription
spaceId string

The space for which to get the tag vocab

tagName string

The name of the tag for which to retrieve the vocab

MetadataRequests.ReplaceMetadataValues

FieldTypeLabelDescription
details MetadataValue

the value details to set

itemId string

The file or folder to replace the metadata for

tagName string

The name of the tag for which to update the metadata

MetadataRequests.ReplaceProfileVocab

FieldTypeLabelDescription
details Vocab

the vocab details to set

tagName string

The name of the tag for which to replace the vocab

MetadataRequests.ReplaceSiteVocab

FieldTypeLabelDescription
details Vocab

the vocab details to set

tagName string

The name of the tag for which to replace the vocab

MetadataRequests.ReplaceSpaceVocab

FieldTypeLabelDescription
details Vocab

the vocab details to set

spaceId string

The space for which to replace the tag vocab

tagName string

The name of the tag for which to replace the vocab

MetadataRequests.UpdateMetadataValues

FieldTypeLabelDescription
details MetadataValue

the value details to set

itemId string

The file or folder to update the metadata for

tagName string

The name of the tag for which to update the metadata

MetadataRequests.UpdateProfileVocab

FieldTypeLabelDescription
details Vocab

the vocab details to set

tagName string

The name of the tag for which to replace the vocab

MetadataRequests.UpdateSiteVocab

FieldTypeLabelDescription
details Vocab

the vocab details to set

tagName string

The name of the tag for which to replace the vocab

MetadataRequests.UpdateSpaceVocab

FieldTypeLabelDescription
details Vocab

the vocab details to set

spaceId string

The space for which to update the tag vocab

tagName string

The name of the tag for which to replace the vocab

MetadataResponses

MetadataResponses.GetFieldMulti

FieldTypeLabelDescription
response Field repeated

MetadataResponses.GetMetadataFields

FieldTypeLabelDescription
response string repeated

MetadataResponses.GetMetadataPanels

FieldTypeLabelDescription
response string repeated

MetadataResponses.GetPanelMulti

FieldTypeLabelDescription
response Panel repeated

MetadataValue

Represents the value of a metadata field.

FieldTypeLabelDescription
numeric MetadataValue.NumericType

Values of metadata if the type of the metadata if this is a numeric type of field.

text MetadataValue.TextType

Values of metadata if the type of the metadata if this is a string type of field.

MetadataValue.NumericType

FieldTypeLabelDescription
values int64 repeated

MetadataValue.TextType

FieldTypeLabelDescription
values string repeated

MetadataValueMap

A map matching a metadata value to its values.

FieldTypeLabelDescription
values MetadataValueMap.ValuesEntry repeated

MetadataValueMap.ValuesEntry

FieldTypeLabelDescription
key string

value MetadataValue

Panel

Represents the details of a metadata panel.

FieldTypeLabelDescription
description string

A description of the panel

panelId string

The id of the panel

tagNames string repeated

names of the tags in this metadata panel

Vocab

Represents the details of a metadata panel.

FieldTypeLabelDescription
mode Vocab.Mode

the mode of the vocab

tagName string

The name of the tag

values string repeated

names of the values in the vocab list

Vocab.Mode

Represents the vocab mode

NameNumberDescription
DISABLED 0

Indicates that vocab is disabled.

INHERIT 1

Indicates that vocab should be inherited.

REPLACE 3

Indicates that vocab should replace any inherited vocab.

Metadata

Method NameRequest TypeResponse TypeDescription
DeleteMetadataValues MetadataRequests.DeleteMetadataValues MetadataValue

Delete the metadata for the tag for the item.

GetField MetadataRequests.GetField Field

Get the details of metadata fields.

GetFieldMulti MetadataRequests.GetFieldMulti MetadataResponses.GetFieldMulti

Get the details of metadata fields.

GetMetadataFields MetadataRequests.GetMetadataFields MetadataResponses.GetMetadataFields

Get the tag names of the metadata fields available for the item

GetMetadataPanels MetadataRequests.GetMetadataPanels MetadataResponses.GetMetadataPanels

Get the IDs of the metadata panels available for the item

GetMetadataValues MetadataRequests.GetMetadataValues MetadataValue

Get the details of the metadata for the tag for the item. The item may be a file or a container.

GetPanel MetadataRequests.GetPanel Panel

Get the details of metadata panels from the provided panel ID.

GetPanelMulti MetadataRequests.GetPanelMulti MetadataResponses.GetPanelMulti

Get the details of metadata panels from the provided panel ID.

GetProfileVocab MetadataRequests.GetProfileVocab Vocab

Get the details of the vocab for the metadata tag for the current profile

GetSiteVocab MetadataRequests.GetSiteVocab Vocab

Get the details of the vocab for the metadata tag for the site

GetSpaceVocab MetadataRequests.GetSpaceVocab Vocab

Get the details of the vocab for the metadata tag for the space

ReplaceMetadataValues MetadataRequests.ReplaceMetadataValues MetadataValue

Replace the metadata for the metadata tag for the item

ReplaceProfileVocab MetadataRequests.ReplaceProfileVocab Vocab

Sets new values to the vocabulary of the tag, for the current user profile. Note: this method overwrites existing values.

ReplaceSiteVocab MetadataRequests.ReplaceSiteVocab Vocab

Sets new values to the vocabulary of the tag, for the site. Note: this method overwrites existing values.

ReplaceSpaceVocab MetadataRequests.ReplaceSpaceVocab Vocab

Sets new values to the vocabulary of the tag, for the space. Note: this method overwrites existing values.

UpdateMetadataValues MetadataRequests.UpdateMetadataValues MetadataValue

Update the details of the metadata for the tag for the item. If called on a single-value field, it will replace the metadata. On multi-valued metadata field types, it will append it to the existing metadata.

UpdateProfileVocab MetadataRequests.UpdateProfileVocab Vocab

Adds new values to the vocabulary of the tag, for the current user profile. This method does not delete existing values.

UpdateSiteVocab MetadataRequests.UpdateSiteVocab Vocab

Adds new values to the vocabulary of the tag for the site. This method does not delete existing values.

UpdateSpaceVocab MetadataRequests.UpdateSpaceVocab Vocab

Adds new values to the vocabulary of the tag for the space. This method does not delete existing values.

search.proto

Top

SearchRequests

SearchRequests.Search

FieldTypeLabelDescription
query string

Search text

SearchResponses

SearchResponses.Search

FieldTypeLabelDescription
response string repeated

Search

Method NameRequest TypeResponse TypeDescription
Search SearchRequests.Search SearchResponses.Search

Perform a general search. The search behaviour is identical to entering a text string in the search bar in the Chorus UI: the scope of the search is limited to the files accessible by the API session, and the metadata fields searched are those included in 'General' search in the catalogs accessible by that user.

sharedlinks.proto

Top

SharedLinkDetails

Details about a shared link.

FieldTypeLabelDescription
createdDate DateTime

The date/time that this object was created

description string

A description for this Shared Link, which will get passed on to the link.

folderId string

ID of the special collection that backs this shared link.

id string

Unique ID of this object.

modifiedDate DateTime

The date/time that this object was last changed

name string

A convenient name for this Shared Link.

urls string repeated

URLs for the shared link

SharedLinksRequests

SharedLinksRequests.Get

FieldTypeLabelDescription
sharedLinkId string

The id, or array thereof, of the Shared Links of which to get the details.

SharedLinksRequests.GetMulti

FieldTypeLabelDescription
sharedLinkIds string repeated

The id, or array thereof, of the Shared Links of which to get the details.

SharedLinksResponses

SharedLinksResponses.GetMulti

FieldTypeLabelDescription
response SharedLinkDetails repeated

Method NameRequest TypeResponse TypeDescription
Get SharedLinksRequests.Get SharedLinkDetails

Get the details for the requested shared links.

GetMulti SharedLinksRequests.GetMulti SharedLinksResponses.GetMulti

Get the details for the requested shared links.

spaces.proto

Top

SpaceDetails

Details about a Space in Chorus.

FieldTypeLabelDescription
avatarUrl string

a URL to the current avatar

createdDate DateTime

The date/time that this object was created

description string

Description of this Space.

id string

Unique ID of this object.

modifiedDate DateTime

The date/time that this object was last changed

name string

Name of this Space.

parentId google.protobuf.StringValue

ID of the parent Space, or null if this is a top-level Space.

SpacesRequests

SpacesRequests.Get

FieldTypeLabelDescription
spaceId string

ID of the requested Space

SpacesRequests.GetMulti

FieldTypeLabelDescription
spaceIds string repeated

ID of the requested Space

SpacesResponses

SpacesResponses.GetMulti

FieldTypeLabelDescription
response SpaceDetails repeated

Spaces

Method NameRequest TypeResponse TypeDescription
Get SpacesRequests.Get SpaceDetails

Get the details about a Space.

GetMulti SpacesRequests.GetMulti SpacesResponses.GetMulti

Get the details about a Space.

uploads.proto

Top

UploadDetails

Details of a created upload session.

FieldTypeLabelDescription
cancelledCount int64

Number of files that have been cancelled before processing.

createdDate DateTime

The date/time that this object was created

destinationFolderId string

ID of the destination folder for the upload.

failedCount int64

Number of files that have been failed to process.

id string

Unique ID of this object.

isAcceptingFiles bool

Indication of whether the upload is still accepting files. This will be `false` after 'finish' has been called, or the upload has been cleaned up by the system.

modifiedDate DateTime

The date/time that this object was last changed

postUrl string

The URL to which files can be uploaded to using HTTP POST requests. The whole file should be posted raw.

status UploadDetails.Status

The current status of this upload batch.

successCount int64

Number of files that have been successfully processed.

totalCount int64

Total number of files in the upload batch.

uploadedIds string repeated

IDs of files that have been successfully uploaded.

UploadsRequests

UploadsRequests.Create

FieldTypeLabelDescription
destinationFolderId string

The ID of the container in which to upload

UploadsRequests.Finish

FieldTypeLabelDescription
uploadId string

ID of the Upload to finish.

UploadsRequests.Get

FieldTypeLabelDescription
uploadId string

ID of the Upload for which to get the details.

UploadDetails.Status

Status of an upload.

NameNumberDescription
Ready 0

upload batch is ready to receive files

Started 1

has started receiving files

Queued 2

has been marked as closed, but no files in the upload have started to be processed

Processing 3

has been marked as closed, and some files in the upload have started to be processed

Finished 4

has been marked as closed, and all files in the upload have been processed

Uploads

Method NameRequest TypeResponse TypeDescription
Create UploadsRequests.Create UploadDetails

This method creates an upload session to allow uploading of files into Chorus. A value of "postUrl" is returned which is used for all transfers to the upload queue for this uploadId. Once all files have been transferred, then the upload should be finished using the finish method. The /rest/v1/uploads/{uploadId} method can be polled periodically to see the progress of the upload.

Finish UploadsRequests.Finish UploadDetails

Mark an upload as finished. This is done after the last file for the upload has been uploaded, and indicates to Chorus that the files received can be processed.

Get UploadsRequests.Get UploadDetails

Get details about an upload. This method is intended to be polled to get the status of files which have been transferred. For example, the total count and the number of successful file uploads and failed file uploads can be compared and used to give feedback to the user.

users.proto

Top

CreateUserDetails

Settings to use when creating a user

FieldTypeLabelDescription
description string

A description about the user, e.g. their job title or department.

email string

The email address of the user.

hideHomeSpaceShortcut bool

No longer supported. Field preserved for backwards compatibility.

name string

The user's name.

username string

The "username" of the user.

SettableUserDetails

Settings to use for updating a user's details

FieldTypeLabelDescription
description google.protobuf.StringValue

A description about the user, e.g. their job title or department.

email google.protobuf.StringValue

The email address of the user.

hideHomeSpaceShortcut google.protobuf.BoolValue

No longer supported. Field preserved for backwards compatibility.

name google.protobuf.StringValue

The user's name.

UserDetails

Represents the details of a normal Chorus User.

FieldTypeLabelDescription
avatarUrl string

a URL to the current avatar

backingFolderId google.protobuf.StringValue

ID of the folder that contains this user's contents. This will be null if requesting details for a different user to the one currently logged in.

createdDate DateTime

The date/time that this object was created

description string

A description about the user, e.g. their job title or department.

email google.protobuf.StringValue

The email address of the user. Will be null if the authenticated user cannot see this detail.

hideHomeSpaceShortcut google.protobuf.BoolValue

Flag used to decide whether to show the user's 'Home Space' in the UI. This should be used if presenting users with a similar layout to that seen in Chorus. Will be null if requesting the details of another user.

homeSpaceId google.protobuf.StringValue

ID of the user's Home Space. Null if the user does not have a Home Space, or if the current user cannot see the Home Space.

id string

Unique ID of this object.

modifiedDate DateTime

The date/time that this object was last changed

name string

The user's name.

username string

The "username" of the user.

UsersRequests

UsersRequests.CreateSiteUser

FieldTypeLabelDescription
details CreateUserDetails

Settings to use when creating the new user

UsersRequests.CreateSpacesUser

FieldTypeLabelDescription
details CreateUserDetails

Settings to use when creating the new user

spaceId string

The space in which to create the user

UsersRequests.Current

UsersRequests.Delete

FieldTypeLabelDescription
userId string

ID of the user to delete

UsersRequests.Get

FieldTypeLabelDescription
userId string

The ID of the user

UsersRequests.GetMulti

FieldTypeLabelDescription
userIds string repeated

The IDs of the users

UsersRequests.GetSiteUsers

UsersRequests.GetSpacesUsers

FieldTypeLabelDescription
spaceId string

The space for which to get the users

UsersRequests.LookupUsers

FieldTypeLabelDescription
query string

The query to match on.

type UserLookupType

The type of lookup the query is used for.

UsersRequests.Set

FieldTypeLabelDescription
details SettableUserDetails

User details to set

update_mask google.protobuf.FieldMask

userId string

ID of the user to update

UsersResponses

UsersResponses.Delete

UsersResponses.GetMulti

FieldTypeLabelDescription
response UserDetails repeated

UsersResponses.GetSiteUsers

FieldTypeLabelDescription
response string repeated

UsersResponses.GetSpacesUsers

FieldTypeLabelDescription
response string repeated

UsersResponses.LookupUsers

FieldTypeLabelDescription
response string repeated

UserLookupType

Lookup methods when searching for users.

NameNumberDescription
USERNAME 0

Lookup by username

NAME 1

Lookup by name

EMAIL 2

Lookup by email

DESCRIPTION 3

Lookup by description

ALL 4

Lookup by all filters

Users

Method NameRequest TypeResponse TypeDescription
CreateSiteUser UsersRequests.CreateSiteUser UserDetails

Create a new site user

CreateSpacesUser UsersRequests.CreateSpacesUser UserDetails

Creates a new user in the specified space. Note that users do not automatically become associated with any role in the space.

Current UsersRequests.Current UserDetails

Returns details of the current user. Note: this will return an error if the current user is not a Normal User.

Delete UsersRequests.Delete UsersResponses.Delete

Delete the specified user

Get UsersRequests.Get UserDetails

Get details about users.

GetMulti UsersRequests.GetMulti UsersResponses.GetMulti

Get details about users.

GetSiteUsers UsersRequests.GetSiteUsers UsersResponses.GetSiteUsers

Retrieve a list of all user IDs in the system

GetSpacesUsers UsersRequests.GetSpacesUsers UsersResponses.GetSpacesUsers

Retrieve a list of all user IDs in the provided space

LookupUsers UsersRequests.LookupUsers UsersResponses.LookupUsers

Find all users matching some query string.

Set UsersRequests.Set UserDetails

Update the details of an API key

Scalar Value Types

.proto TypeNotesC++JavaPythonGoC#PHPRuby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)