A.nnotate API reference - Part 3: Folders

This is Part 3 of the A.nnotate API reference guide which includes calls for dealing with folders. See also Part 1 which documents the listFolders.php call for listing a user's folders and the listDocuments.php call for listing documents in a given folder. Part 2 has information on adding user accounts, documents and notes.

1. Create a new folder

The apiCreateFolder.php call allows you to create a folder. The request must be signed by the api-user (see authentication). 

  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
    &p=                                    # The parent folder ID, e.g. 2008-01-01/abc123

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

2. Delete a 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}".

3. 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}".

4. Move a 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 {error message}".

5. 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}".

6. 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}".

7. Rename a 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}".

8. Sharing folders

The two calls below give access to the standard mechanisms for sharing folders - sending out invitations (which the recipient can accept or decline), and adding folders immediately to a given user's list.

8.1 Invite to share a folder

The apiInviteToShareFolder.php call lets you invite people to share a folder. They will see the invitation on their home page, where they can decide to accept (or not). 

  http://yoursite.com/annotate/php/apiInviteToShareFolder.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
    &e=user1@example.com,user2@example.com # Comma separated list of invitee emails
    &u=                                    # (optional) set to 1 to uninvite
    &m=Here+is+a+shared+folder             # (optional) message to include

The return value is either "OK" or "ERR" on the 1st line followed by one line per invitee starting OK or ERR if there was a problem.

8.2 Accepting a folder sharing invitation

The apiAcceptFolderInvite.php call lets you share particular folders with a given user, which will get added immediately to their list of documents. 

  http://yoursite.com/annotate/php/apiAcceptFolderInvite.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
    &s=user1@example.com                   # Sender of invitation

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