Workspaces and Folders.

  1. Create a workspace
  2. Get details for a workspace
  3. Update workspace user list
  4. Update workspace settings
  5. List workspaces for a user
  6. List all workspaces
  7. Delete a workspace
  8. Create folder
  9. Rename folder
  10. Delete folder
  11. Move folder
  12. Move document to a folder
  13. List folders
  14. Set default tags for a folder
  15. Get default tags for a folder

Create a workspace

A workspace is a shared area with users, groups, roles and custom document types. To create a workspace, use the apiCreateWorkspace.php call, with the owner set to the annotate user (who must be a user on the system, e.g. created with the createAccount call). 

http://yoursite.com/annotate/php/apiCreateWorkspace.php?
api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

HTTP POST parameters:
    &name=my_workspace        # the name for the new workspace

    &about=description...     # (optional)the longer description
    &mirror=123456            # (optional) create as a content mirror of another workspace

The return value is OK 456789 (with the new workspace ID), or ERR + msg. The mirror argument is an advanced feature which lets you make a workspace which synchronises documents and notes from an existing, master workspace.

You can make a link to the workspace using a url like: 

documents.php?ws=456789

- see also the loginAs call which lets you create a link to log in as a given user and display the list of documents in a workspace.

Get details for a workspace

The apiGetWorkspaceDetails.php call returns detailed information about a workspace, including users, groups, roles, document status, document metadata, document tags, note tags, section tags, tag categories and settings. 

http://yoursite.com/annotate/php/apiGetWorkspaceDetails.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the admin user again
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

    &ws=123456                             # The workspace ID.

If there was a problem with the API call, it returns "ERR {msg}", otherwise a JSON object with the workspace settings. The arrays are json arrays with an id field which is unique within the workspace for the given array.

info (fields: id, title, about, created, owner, archived);

users (a list of all users, each with fields: id, email, firstname, lastname, roleid, sig);

groups (list of groups, each with fields: id, name, members (array of user ids);

roles (list of roles, each with fields: id, name, and a list of flags for permissions (e.g. upload, admin the workspace, view particular tabs of the gui etc);

status (list of document status; each with fields: id, name, about;

metadata (list of document metadata items, each with fields: id, name, desc, type, mandatory (boolean), values (array of possible values);

doctags (list of document tags; each with fields: id, tag, color and tagCategory);

doctag categories (list of document tag categories; each with fields: id, tag and color);

notetags (list of note tags; each with fields: id, tag, color and tagCategory);

notetag categories (list of note tag categories; each with fields: id, tag and color);

sectiontags (list of section tags; each with fields: id, tag, color and tagCategory);

sectiontag categories (list of section tag categories; each with fields: id, tag and color);

settings (list of workspace settings; noteStyle, thumbSize, toOptions etc);

Note: For workspaces of 50 members or less you will always get the complete list of users. For workspaces with more than 50 members you will need to set the optional parameter 'listall=1' if you want the full list.

Example output is given below; the user interface documents many of the workspace features in detail, so creating a test workspace and calling this API will return all the workspace settings. 

{
  "info" : { 
      "id" : "123456", 
      "title" : "Workspace XYZ", 
      "about" : "... the description",
      "created" : "2001-01-01",
      "owner" : "joe@example.com",
      "archived" : 0 },
  "users" : 
     [ { "id" : 1, "email" : "jane@example.com", 
         "firstname" : "Jane", "lastname" : "Bloggs",
         "roleid" : 0, "sig" : "jane" }, // ... 
     ], 
  "groups" : 
     [ { "id" : 1, "name" : "Group 1", "members" : [1,2,3] }, // ... 
     ],
  "roles" : 
     [ { "id" : 1, "name" : "Student", 
         "upload" : 1, "adminws" : 0, // more role permission flags... 
       }, // ... 
     ], 
  "status" :
     [ { "id" : 1, "name" : "Invoice", "about" : "an invoice ...", // ...
     ],
  "metadata" :
     [ { "id" : 1, "name" : "Department", "desc" : "", "type" : "string", "mandatory" : false, "values" : [] }, // ...
     ],
  "doctags" : 
     [ { "id" : 1, "tag" : "Urgent", "color" : "#f9625c", "tagCategory": 1 }, // ...
     ],
  "doctagcategories" :
     [ { "id" : 1, "tagCategory" : "Country" }, // ...
     ],
  "notetags" :
     [ { "id" : "_wt:1", "tag" : "Question", "color" : #ff625c", "tagCategory": 1 }, // ...
     ], 
  "notetagcategories" :
     [ { "id" : 1, "tagCategory" : "Country" }, // ...
     ],
  "sectiontags" :
     [ { "id" : "_st:1", "tag" : "Introduction", "color" : "#4ebdfa", "tagCategory": 1 }, // ...
     ],
  "sectiontagcategories" :
     [ { "id" : 1, "tagCategory" : "Country" }, // ...
     ],
  "settings" : 
     { "noteStyle" : "box", "thumbSize" : "m", // ... }
     
}

Update workspace user list

The apiUpdateWorkspaceUsers.php call updates the workspace user list: add/update/delete user and modify role/remove selection of users.

Add a user to the workspace 

http://yoursite.com/annotate/php/apiUpdateWorkspaceUsers.php?
    api-user=joe@example.com               # the admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the api-annotateuser has to match the apiuser
    &api-auth=xyz1234543983jeflgnwefgdgd   # the signed hash code.

HTTP POST parameters:
    &ws=123456                         # the workspace to be updated
    &action=add                            # the action to be performed
    &email=jack@example.com                # the user's email
    &roleid=1                              # workspace role id, see apiGetWorkspaceDetails.php 
    &firstname=Jack                    # (optional)
    &lastname=Black                        # (optional)
    &sig=Jack                              # (optional)
    &noemail=1                             # (optional) set to disable email notification

Return value is "OK + {workspace userid} + added {email} " or "ERR + {msg}".

Update workspace user

This updates the workspace user roleid, first name, last name and signature 

http://yoursite.com/annotate/php/apiUpdateWorkspaceUsers.php?
    api-user=joe@example.com               # the admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the api-annotateuser has to match the apiuser
    &api-auth=xyz1234543983jeflgnwefgdgd   # the signed hash code.

HTTP POST parameters:
    &ws=123456                         # the workspace to be updated
    &action=update                         # the action to be performed
    &email=jack@example.com                # the user's email, this cannot be changed
    &userid=3                          # workspace user id, see apiGetWorkspaceDetails.php 
    &roleid=1                              # workspace role id, see apiGetWorkspaceDetails.php
    &firstname=Jack                    # (optional)
    &lastname=Black                        # (optional)
    &sig=Jack                              # (optional)

Return value is "OK + {workspace userid} + {email} updated " or "ERR + {msg}".

Delete workspace user 

http://yoursite.com/annotate/php/apiUpdateWorkspaceUsers.php?
    api-user=joe@example.com               # the admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the api-annotateuser has to match the apiuser
    &api-auth=xyz1234543983jeflgnwefgdgd   # the signed hash code.

HTTP POST parameters:
    &ws=123456                         # the workspace to be updated
    &action=delete                         # the action to be performed
    &userid=3                              # workspace user id, see apiGetWorkspaceDetails.php

Return value is "OK + {workspace userid} + {email} removed" or "ERR + {msg}".

Set role for selected users 

http://yoursite.com/annotate/php/apiUpdateWorkspaceUsers.php?
    api-user=joe@example.com               # the admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the api-annotateuser has to match the apiuser
    &api-auth=xyz1234543983jeflgnwefgdgd   # the signed hash code.

HTTP POST parameters:
    &ws=123456                         # the workspace to be updated
    &action=setrole                        # the action to be performed
    &userids=1,2,3                         # comma-separated list of workspace user ids
    &roleid=1                              # workspace role id, see apiGetWorkspaceDetails.php

Return value is "OK set roles" or "ERR + {msg}".

Remove selected users 

http://yoursite.com/annotate/php/apiUpdateWorkspaceUsers.php?
    api-user=joe@example.com               # the admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the api-annotateuser has to match the apiuser
    &api-auth=xyz1234543983jeflgnwefgdgd   # the signed hash code.

HTTP POST parameters:
    &ws=123456                         # the workspace to be updated
    &action=removesel                      # the action to be performed
    &userids=1,2,3                         # comma-separated list of workspace user ids

Return value is "OK removed users" or "ERR + {msg}".

Update workspace settings

The apiUpdateWorkspaceSettings.php call updates the workspace settings, which includes: add/update/delete groups, roles, status, doctags, note tags and update info and settings.

Add group, role, status, metadata, document tag, note tag and section tag 

http://yoursite.com/annotate/php/apiUpdateWorkspaceSettings.php?
    api-user=joe@example.com               # the admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the api-annotateuser has to match the apiuser
    &api-auth=xyz1234543983jeflgnwefgdgd   # the signed hash code.

HTTP POST parameters:
    &ws=123456                         # the workspace to be updated
    &action=add                            # the action to be performed
    &setting=groups|roles|status|metadata|
         doctags|notetags|sectiontags  # choose the setting to be added
    &json=setting_info                     # json and url encoded array

Example JSON arrays are given below:

group {"name":"group 1","members":[1,2,3]}

role {"name":"Administrator","upload":1,"purge":1,"viewown":1,"viewall":1,"edittags":1,"editusers":1,"batchexport":1,"viewhome":1, "viewreviews":1,"viewnotesindex":1,"viewsearch":1,"viewdocsindex":1,"annotate":1,"moderate":1,"editfiles":1,"useradmin":1, "rolesadmin":1,"adminws":1,"createws":1,"moderatenotes":1,"resolve":1,"exportdocs":1,"downloaddocs":1,"accessws":1,"sharews":1}

status {"name":"No notes","about":"","addNotes":false,"toChoice":"free","defaultTo":"_viewers","newTags":false,"download":true,"override":true}

metadata {"name" : "Department", "desc" : "", "type" : "string", "mandatory" : false, "values" : []}

doctag {"tag":"Urgent","color":"#f9625c"}

note tag {"tag":"Question","color":"#ff625c"}

section tag {"tag":"Introduction","color":"#4ebdfa"}

Return value is "OK {id}" or "ERR + {msg}".

Update/delete group, role, status, metadata, document tag, note tag and section tag 

http://yoursite.com/annotate/php/apiUpdateWorkspaceSettings.php?
    api-user=joe@example.com               # the admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the api-annotateuser has to match the apiuser
    &api-auth=xyz1234543983jeflgnwefgdgd   # the signed hash code.

HTTP POST parameters:
    &ws=123456                          # the workspace to be updated
    &action=update|delete                   # the action to be performed
    &setting=groups|roles|status|metadata|
         doctags|notetags|sectiontags   # choose the setting to be added
    &json=setting_info                      # json and url encoded array

NOTE: the JSON array must include the ID of the element to be updated or deleted.

Return value is "OK" or "ERR + {msg}".

Update info or settings 

http://yoursite.com/annotate/php/apiUpdateWorkspaceSettings.php?
    api-user=joe@example.com               # the admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the api-annotateuser has to match the apiuser
    &api-auth=xyz1234543983jeflgnwefgdgd   # the signed hash code.

HTTP POST parameters:
    &ws=123456                       # the workspace to be updated
    &action=update                       # the action to be performed
    &setting=info|settings               # choose the setting to be added
    &json=setting_info                   # json and url encoded array

Example JSON arrays are given below:

info {"id":"123456","title":"Workspace XYZ","about":"","created":"2001-01-01","owner":"joe@example.com","archived":0}

settings {"noteStyle":"box","thumbSize":"m","toOptions":"svug"}

Return value is "OK" or "ERR + {msg}".

List workspaces for a user

The apiListWorkspaces.php call returns the IDs and names of all workspaces a given user has created or belongs to. 

http://yoursite.com/annotate/php/apiListWorkspaces.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

The return value is "ERR + msg" in case of error, or a JSON array containing an own list of the user's own workspaces; an others list of other users' workspaces they have joined; and a hasprivate flag if they have a private workspace (for annotate v3 compatibility). The own and others arrays contain fields id, title, about, created, archived. The workspace id can be passed in to the other API calls, e.g. to list the documents for a user in a given workspace. 

{
  "own" : [ 
      { "id" : "123456", 
        "title" : "Some sample workspace", 
        "about" : "Some desc...",
        "created" : "2012-01-01", 
        "owner" : "joe@example.com",
        "archived" : 0
      } //, { ... more workspaces ... } 
   ], 
  "others" : [ 
      { "id": "456789", "title" : ... entries as above } // , { ... }
   ],
  "hasprivate" : 1 
}

List all workspaces

The apiListAllWorkspaces.php call returns the IDs and names of all workspaces created on a server. It can only be called by a server admin users. 

http://yoursite.com/annotate/php/apiListAllWorkspaces.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=joe@example.com      # the admin user again
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

The return value is a json array of basic information about each workspace, or ERR + msg if there was some error with the api call. 

[
   { "id" : "123456", "title" : "Some ws", "about" : "info about the ws...", 
     "created" : "2001-01-01", "owner" : "jill@example.com" },
   { ... info about the next ws } 
]

Delete a workspace

The apiDeleteWorkspace.php call deletes a workspace and all its content. NB: Use with caution, as there is no UNDO. 

http://yoursite.com/annotate/php/apiDeleteWorkspace.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

POST parameters:
    &ws=123456                # the workspace to delete

Return value is "OK" or "ERR + msg".

Create folder

Documents can be added to folders within a workspace, arranged in a hierarchy. To create a folder, use the apiCreateFolder.php call: 

http://yoursite.com/annotate/php/apiCreateFolder.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

HTTP POST parameters:
    &n=Test%20Folder                       # The folder name
    &ws=123456                             # The workspace ID
    &p=                                    # The parent folder ID, e.g. 2008-01-01/abc123

The return value is either "OK {new folder id}" or "ERR {error message}".

Rename folder

The apiRenameFolder.php call lets you change the name of a folder. 

http://yoursite.com/annotate/php/apiRenameFolder.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

HTTP POST parameters:
    &f=2008-02-02/zxc789                   # The folder id
    &n=Newname                             # The new name

The return value is either "OK {new name}" , or "ERR {error message}".

Delete folder

The apiDeleteFolder.php call allows you to delete a folder and all its contents. 

http://yoursite.com/annotate/php/apiDeleteFolder.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

HTTP POST parameters:
    &f=2008-01-01/abc123                   # The folder ID

The return value is either "OK" or "ERR {error message}".

Move folder

The apiMoveFolder.php call allows you to move a folder to a given parent folder. 

http://yoursite.com/annotate/php/apiMoveFolder.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

HTTP POST parameters:
    &f=2008-02-02/zxc789                   # The folder to move
    &p=2008-01-01/abc123                   # New parent folder ID

The return value is either "OK", or "ERR {message}".

Move document to a folder

The apiMoveDocument.php call allows you to move a document to a given parent folder. The empty string "" is the folder ID of the top level Home folder. 

http://yoursite.com/annotate/php/apiMoveDocument.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

HTTP POST parameters:
    &d=2008-01-01                          # The document's date
    &c=xyz789                              # The document's code
    &p=2008-01-01/abc123                   # New parent folder ID

The return value is either "OK" or "ERR {error message}".

List folders

The listFolders.php call allows you to list all folders for a given user or workspace. When listing folders in a workspace, set the api-annotateuser to be one of the workspace members to see the folders visible to that user in the workspace.

http://yoursite.com/annotate/php/listFolders.php?    
     api-user=joe@example.com
     &api-requesttime=1234566
     &api-annotateuser=jill@example.com
     &api-auth=ABC123...
     
     &ws=123456 # workspace id (optional)

The return value will either be "ERR {some error message}" or a JSON encoded object:

{
  foldersbyid: {
    "2008-11-05/abc234" : {
       name: "sample folder",
       owner: "joe@example.com",
       id: "2008-11-05/abc234",
       parentid: "",   // "" for top level, otherwise the id of the parent folder
       childids: [],   // array of child folder ids
       meta: {
         // ... detailed metadata for folder, including sharing info
       }
    },
    "2008-12-01/xyz123" : { 
      // ... details for 2nd folder
    }
  },
  topids: [ // array of folder ids at top level
    "2008-11-05/abc234",
    "2008-12-01/xyz123"
  ]
}

The object returned contains the field foldersbyid, a map of folder ID to its info, and the array topids, a list of the folders at the top level. A folderid is a string like "2008-01-02/abc234" containing the date the folder was created and a random code.

Set default tags for a folder

The apiSetFolderTags.php call allows you to set the default set of note tags for documents added to the given folder. 

http://yoursite.com/annotate/php/apiSetFolderTags.php?
    api-user=joe@example.com               # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

HTTP POST parameters:
    &f=2008-02-02/zxc789                   # The folder id
    &t=tag1,tag2,tag456                    # The set of tags - comma or \n separated

The return value is either "OK" or "ERR {error message}".

Get default tags for a folder

The apiGetFolderTags.php call allows you to get the default set of note tags for the given folder. 

http://yoursite.com/annotate/php/apiGetFolderTags.php?
    api-user=joe@example.com                   # The admin user for the account
    &api-requesttime=123456                # the Unix timestamp (GMT)
    &api-annotateuser=jill@example.com     # The user's account
    &api-auth=xyz1234543983jeflgnwefgdgd   # The signed hash code.

HTTP POST or GET parameter:
    &f=2008-02-02/zxc789                   # The folder id

The return value is either "OK\n" + one tag per line, or "ERR {error message}".

Features

Departments

Industries

Resources

Contact us

© Annotate.com Sitemap Legal Terms