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

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

Method(s):

Parameters:

signup

Create a new account

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

Method(s): GET

Parameters:

  • email - Email address
  • password - Password
  • firstname - Firstname
  • lastname - Lastname
  • organization - Optional. User's compagny
  • position - Optional. User's position

update_status

Update the status of the authenticated user.

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

Method(s): GET POST

Parameters:

  • status - The new status message.

tasks

show

Display specific task information (including shared tasks)

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

Method(s): GET

Parameters:

  • id - The id of the task.

view

Display authenticated user tasks list

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

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

Method(s): GET POST

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

Method(s): GET POST

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, done and late
  • 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

Method(s): GET POST

Parameters:

  • id - The id of the task.

update_status

Update task status

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

Method(s): GET POST

Parameters:

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

update_category

Update task cateogry

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

Method(s): GET POST

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

Method(s): GET POST

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

Method(s): GET POST

Parameters:

  • id - The id of the task.
  • colleague_id - Can be either a colleague id or an array of ids (colleague_id[]).

update_context

Update task context

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

Method(s): GET

Parameters:

  • id - The id of the task.
  • context - The new task context, valid values: home, mobile and office.

update_progression

Update task progression

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

Method(s): GET

Parameters:

  • id - The id of the task.
  • progression - The new task progression, integer value between 0 and 100.

set_deadline

Update task deadline

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

Method(s): GET

Parameters:

  • id - The id of the task.
  • deadline - The new task deadline : valid timestamp.

attach_file

Attach file to a task

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

Method(s): GET

Parameters:

  • id - The id of the task.
  • file_id - Valid file id.

ping

Ping task to colleague(s)

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

Method(s): GET

Parameters:

  • id - The id of the task.
  • colleagues - Can be either a colleague id or an array of ids (colleagues[]).

send_email

Send task information to email address

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

Method(s): GET

Parameters:

  • id - The id of the task.
  • email - Any valid email address.

add_comment

Add comment on a task

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

Method(s): GET POST

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

Method(s): GET POST

Parameters:

  • id - The id of the task comment.

comment

View a comment

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

Method(s): GET POST

Parameters:

  • id - The id of the task comment.

comments

View task comments

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

Method(s): GET POST

Parameters:

  • id - The id of the task.

categories

show

Display specific task category information

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

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

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

Method(s): GET POST

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

Method(s): GET POST

Parameters:

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

delete

Delete a task category

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

Method(s): GET POST

Parameters:

  • id - The task cateogry id.

set_privacy

Update task category privacy

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

Method(s): GET POST

Parameters:

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

share

Share category between user(s)

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

Method(s): GET

Parameters:

  • id - The id of the task category.
  • colleagues - Can be either a colleague_id or an array of ids (colleagues[]).

timeline

view

Show authenticted user live feed - events timeline

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

Method(s): GET

Parameters:

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

files

add

Upload file

URL: http://api.producteev.com/files/add.format

Method(s): POST

Parameters:

  • title - File title
  • file - $_FILES['file']

delete

Delete some file

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

Method(s): GET

Parameters:

  • id - File id.

share

Share some file

URL: http://api.producteev.com/files/share.format

Method(s): GET

Parameters:

  • id - File id.
  • colleagues - Can be either a colleague_id or an array of ids (colleagues[]).

add_comment

Add comment on a file

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

Method(s): GET POST

Parameters:

  • id - File id
  • message - The comment.

delete_comment

Delete a file comment

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

Method(s): GET

Parameters:

  • id - The id of the comment.

main

summary

Dump user report (timeline, tasks, comments, ...)

URL: http://api.producteev.com/main/summary.format

Method(s):

Parameters: