Introduction

Producteev exposes some of its functionality via an Application Programming Interface (API). This document is a reference for that functionality, and aims to serve as a reference for developers building tools that talk to Producteev.

Authentication

All Producteev API methods require authentication. All responses are relative to the context of the authenticating user. For example, an attempt to retrieve information on a protected user who is not friends with the requesting user will fail.

For the time being, HTTP Basic Authentication is the only supported authentication scheme. When authenticating via Basic Auth, use your registered username as the username component. Session cookies and parameter-based login are known to work but are not officially supported.

HTTPS / SSL

All Producteev API methods can be accessed using SSL connection, just use https:// instead of te http:// and you have your data secured.

RESTful Resources

The Producteev API conforms vaguely to the design principles of Representational State Transfer (REST). You'll find that you can simply change the file extension on most any request to get results in the format of your choice. This document notes which formats are available for each method. Producteev presently supports the following data formats: XML, JSON and RSS syndication format.

Parameters

Some API methods take optional or requisite parameters. Where applicable, we've documented those parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings.

HTTP Requests

Unless otherwise noted, methods exposed by the Producteev API require a GET request. Methods that post tasks or other data generation require a POST. Where noted, some API methods will return different results based on HTTP headers sent by the client. When requesting XML, the response is UTF-8 encoded. Symbols and characters outside of the standard ASCII range are translated to HTML entities.

HTTP Status Codes

The Producteev API attempts to return appropriate HTTP status codes for every request. Here's what's going on with our various status codes:

  • 200 OK: all cool.
  • 304 Not Modified: there was no new data to return.
  • 400 Bad Request: your request is invalid, and we'll return an error message that tells you why.
  • 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided aren't valid.
  • 403 Forbidden: we understand your request, but are refusing to fulfill it. An accompanying error message should explain why.
  • 404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (ex: no such user).
  • 500 Internal Server Error: we did something wrong. Please let us know so we can check it out.
  • 502 Bad Gateway: we are down for upgrade.
  • 503 Service Unavailable: overloaded at the time. Try again later.
When the Producteev API returns error messages, it attempts to do so in your requested format. For example, an error from an XML method might look like this:
<?xml version="1.0" encoding="UTF-8"?>
<system>
<error request="/users/show/132.xml" message="Requested user is no part of your colleagues" />
</system>


On RSS format when no data is found a HTTP 404 error is returned.

Encoding

The Producteev API supports UTF-8 encoding. Please note that angle brackets ("<" and ">") are entity-encoded to prevent Cross-Site Scripting attacks for web-embedded consumers of JSON API output.

The Easiest Way to Play Around with the Producteev API

If your system has curl (and it should!) or using a web browser, you've already got a great way to poke around the Producteev API. Here are some examples:

How do I report bugs and issues with the Producteev API?

You can see the list of existing issues right here. Please check to be sure your issue hasn't already been reported. Vote up an existing issue or add an example to it if it describes your bug, or report a new issue if need be.

users

show

Show user information, you can only see information of users who are considered your colleagues.

URL: http://api.producteev.com/users/show.format

Formats: xml, json, rss

Method(s): GET

Parameters:

  • id - Optional. The id or e-mail of the user for whon to request the user information, if ommited shows authenticated user information.

colleagues

Displays list of colleagues of the authenticated user

URL: http://api.producteev.com/users/colleagues.format

Formats: xml, json, rss

Method(s): GET

update_status

Update the status of the authenticated user

URL: http://api.producteev.com/users/update_status.format

Formats: xml, json, rss

Method(s): GET, POST

Parameters:

  • status - The new status message.

update_alert

Enable or disable alert for the authenticated user.

URL: http://api.producteev.com/users/update_alert.format

Formats: xml, json, rss

Method(s): GET, POST

Parameters:

  • alert - Alert type (example: followers).
  • status - Possible values: on or off.

update_report

Subscribe or unsubscribe to report for the authenticated user.

URL: http://api.producteev.com/users/update_report.format

Formats: xml, json, rss

Method(s): GET, POST

Parameters:

  • report - Report type (example: weekly).
  • status - Possible values: on or off.

tasks

show

Display specific task information

URL: http://api.producteev.com/tasks/show.format

Formats: xml, json, rss

Method(s): GET

Parameters:

  • id - The id of the task.

view

Display authenticated user tasks list

URL: http://api.producteev.com/tasks/view.format

Formats: xml, json, rss

Method(s): GET

Parameters:

  • category_id - Optional. The id of the category to show tasks.
  • colleague_id - Optional. The id of the colleague to show tasks.
  • order_by - Optional. The field to sort results.
  • order_type - Optional. The type of sorting ASC or DESC.

create

Create new task for the authenticated user

URL: http://api.producteev.com/tasks/create.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • title - The task title.
  • description - Optional. The task description.
  • category_id - Optional. The task category to assign the task.

update

Update task title

URL: http://api.producteev.com/tasks/update.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task.
  • title - The new task title.
  • description - Optional. The task description.
  • status - Optional. The new task status, valid values: clear, pending, active and done.
  • reminder - Optional. Date & time for the task reminder, any valid date format.
  • category_id - Optional. The task category to assign the task.

delete

Delete a specific task

URL: http://api.producteev.com/tasks/delete.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task.

update_status

Update task status

URL: http://api.producteev.com/tasks/update_status.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task.
  • status - The new task status, valid values: clear, pending, active and done.

update_category

Update task cateogry

URL: http://api.producteev.com/tasks/update_category.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task.
  • status - The new task category id.

set_reminder

Set a reminder for task

URL: http://api.producteev.com/tasks/set_reminder.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task.
  • reminder - Optional. Date & time for the task reminder, any valid date format, if empty will clear reminder.

assign

Assign task to colleague

URL: http://api.producteev.com/tasks/assign.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task.
  • colleague_id - The colleague id to assign the task.

add_comment

Add comment on a task

URL: http://api.producteev.com/tasks/add_comment.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task.
  • message - The comment.

delete_comment

Delete a task comment

URL: http://api.producteev.com/tasks/delete_comment.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task comment.

comment

View a task comment

URL: http://api.producteev.com/tasks/comment.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task comment.

comments

View a task comments

URL: http://api.producteev.com/tasks/comments.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task.

categories

show

Display specific task category information

URL: http://api.producteev.com/categories/show.format

Formats: xml, json, rss

Method(s): GET

Parameters:

  • id - The id of the task category.

view

Display authenticated user tasks categories list

URL: http://api.producteev.com/categories/view.format

Formats: xml, json, rss

Method(s): GET

Parameters:

  • colleague_id - Optional. The id of the colleague to show tasks.

create

Create new task category for the authenticated user

URL: http://api.producteev.com/categories/create.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • title - The task cateogry title.
  • privacy - Optional. The task cateogry privacy, public or private.
  • type - Optional. The task cateogry type.

update

Update a task category name

URL: http://api.producteev.com/categories/update.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The task cateogry id.
  • title - The task cateogry title.

delete

Delete a task category

URL: http://api.producteev.com/categories/delete.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The task cateogry id.

set_privacy

Update task category privacy

URL: http://api.producteev.com/categories/set_privacy.format

Formats: xml, json

Method(s): POST, GET

Parameters:

  • id - The id of the task category.
  • status - The new task category privacy, valid values: public and private

timeline

view

Show authenticted user live feed - events timeline

URL: http://api.producteev.com/timeline/view.format

Formats: xml, json, rss

Method(s): GET

Parameters:

  • colleague_id - Optional. The id of the user to show live feed.