Cozimo API

1. Overview

The Cozimo API lets you manipulate your Cozimo workgroups, folders and files.

It consists of a simple set of callable methods. To use the Cozimo API, you simply send requests to the https://www.cozimo.com/api/ endpoint and receive responses in the JSON format.

2. Character encoding

All data sent to the Cozimo API is expected to be encoded in the UTF-8 format.

For more information about Unicode and UTF-8, you may read the following:

3. Error handling

Responses to API requests should be checked against the 'status' key.

When a problem occurs while processing API requests, the response contains a 'status' key with a value different than 'OK'. It also contains a 'message' key describing the problem details.

If the response contains a 'status' key with a value of 'OK', or if it doesn't contain that key, you can assume that the request was handled without problems and you can proceed reading the response data.

4. Authentication

Every request to the Cozimo API needs to be authenticated. You authenticate your requests with HTTP Authentication using your regular Cozimo user — there is no special API user.

Important: always use the secure https://www.cozimo.com/api API endpoint so that your authentication credentials are encrypted.

5. Uploading media

To upload a file to a Cozimo folder, send a POST request to the following URL: https://www.cozimo.com/api/upload_file

with the following arguments:

folder_id: The ID of the collaboration folder you want to upload the file to.
title: The file's title.
description: The file's description.
data: The file's image data.

Remember that strings passed to the Cozimo API have to be encoded in the UTF-8 format.

When successful, the following JSON string is returned: {"status": "OK"}

When not successful, a JSON string is returned, similar to the following one: {"status": "failed", "message": "Disk quota exceeded."}

6. Listing collaboration folders

To obtain the list of your Cozimo collaboration folders, send a GET request to the following URL: https://www.cozimo.com/api/get_folders_info

with the following optional argument:

include_workgroup_info (optional): also include the workgroup information for each folder as part of the response.

When successful, a JSON string is returned, similar to the following: {
    "status": "OK",
    "folders": [
         {
             "id": "f.2008-02-09.12348765",
             "url": "http://www.cozimo.com/...",
             "title": "A nice title"
         }
     ]
}

7. Listing workgroups

To obtain the list of your Cozimo workgroups, send a GET request to the following URL: https://www.cozimo.com/api/get_workgroups_info

with the following optional argument:

include_member_info (optional): also include a list of the workgroup members as part of the response.

When successful, a JSON string is returned, similar to the following: {
    "status": "OK",
    "workgroups": [
         {
             "id": "w.2108-04-25.6212523562",
             "title": "Workgroup One",
             "description": "A nice workgroup"
         }
     ]
}

If members information is requested, each response's workgroup block also contains a structure similar to the following: {
    "members": [
         {
             "id": "juan",
             "fullname": "Juan Pablo",
             "email": "juan@example.com",
             "job_title": "Software Janitor",
             ...
         }
     ]
}

8. Listing files

To obtain the list of files in a collaboration folder, send a GET request to the following URL: https://www.cozimo.com/api/get_files_info

with the following argument:

folder_id: the id of the folder you are inspecting.

When successful, a JSON string is returned, similar to the following one: {
    "status": "OK",
    "files": [
         {
             "id": "m.2008-04-29.34526",
             "title": "Daylight shot - three",
             "url": "http://www.cozimo.com/Members/...",
             "description": "We are keeping this one",
             "size": "9654",
             "creator": "John Doe",
             "last_annotated": "1972/25/05 02:04:06 GMT",
             "state": "staff"
         },
         {
             "id": "m.2006-08-12.783567282",
             "title": "Promo video",
             "url": "http://www.cozimo.com/Members/...",
             "description": "Latest promo material.",
             "size": "14846",
             "creator": "Michael J.",
             "last_annotated": "2004/05/07 03:05:07 GMT",
             "state": "workgroup"
         }
     ]
}

9. Listing workgroup members

To obtain the list of members in a workgroup, send a GET request to the following URL: https://www.cozimo.com/api/get_members_info

with the following argument:

workgroup_id: the id of the workgroup you are inspecting.

When successful, a JSON string is returned, similar to the following one: {
    "status": "OK",
    "members": [
         {
             "id": "ronaldo",
             "fullname": "Cristiano Ronaldo",
             "e-mail": "ronaldo@example.com",
             "role": "staff",
             ...
         },
         {
             "id": "bastian",
             "fullname": "Bastian Schweinsteiger",
             "e-mail": "bastian@example.com",
             "role": "collaborator",
             ...
         },
     ]
}

10. Listing folder messages

To obtain the list of messages in a folder, send a GET request to the following URL: https://www.cozimo.com/api/get_messages_info

with the following argument:

folder_id: the id of the folder you want the messages for.
reference_id (optional): the id of the message you are interested in (must be in the specified folder).

When successful, a JSON string is returned, similar to the following one: {
    "status": "OK",
    "messages": [
         {
             "id": "21",
             "subject": "the subject",
             "body": "the body",
             "reference": "m.2009-02-26.9737607627",
             "creator": "Gijsbert de Haan",
             "creator_id": "myuserid",
             "date": "2009/02/27 15:17:03.844 US/Eastern",
             "access_id": "workgroup",
             "inreplyto_id": "42",
             ...
         },
         {
             "id": "42",
             ...
         },
     ]
}

11. Post message

To post a message for a folder item, send a POST request to the following URL: https://www.cozimo.com/api/post_message

with the following argument:

folder_id: the id of the folder you want to post the message to.
reference: item id the message refers to (must be in the same folder).
subject: message subject.
body: message body.
access: message access, can be workgroup or staff.
to: comma separated list of user ids you want the message mailed to.
inreplyto_id (optional): message id this message is a reply to.

When successful, a JSON string is returned, similar to the following one: {
"status": "OK",
"message_id": "21"
}