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 Part 2.

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