API: Projects

Jump to: List | Create | Read | Update | Delete | Archive | Activate

List projects

GET /api/projects

The projects resource returns projects accessible by the user. For all roles except freelancers this includes all projects in the account. Freelancers see all projects they currently have been given access to. This method returns active and archived projects.

JSON
XML
$ curl -v -H "X-FreckleToken:lx3gi6pxdjtjn57afp8c2bv1me7g89j" https://apitest.letsfreckle.com/api/projects.json
Response:
[
  {
    "project":{
      "name":"Nutsnbolts",
      "unbillable_minutes":0,
      "created_at":"2010-11-30T21:56:39Z",
      "billable":true,
      "budget_minutes":null,
      "minutes":0,
      "cached_tags":null,
      "remaining_minutes":null,
      "updated_at":"2011-10-19T15:59:56Z",
      "import_id":null,
      "account_id":5039,
      "group_name":null,
      "minutes":0,
      "project_group_id":null,
      "id":34580,
      "enabled":true,
      "billable_minutes":0,
      "user_id":null,
      "unbillable_minutes":0,
      "color_hex":"ff9898",
      "budget":null,
      "stepping":15,
      "invoice_recipient_details":null
    }
  }
  // ...more projects...
]
$ curl -v -H "X-FreckleToken:lx3gi6pxdjtjn57afp8c2bv1me7g89j" https://apitest.letsfreckle.com/api/projects.xml
Response:
<?xml version="1.0" encoding="UTF-8"?>
<projects type="array">
  <project>
    <account-id type="integer">5039</account-id>
    <billable type="boolean">true</billable>
    <billable-minutes type="integer">0</billable-minutes>
    <budget type="integer" nil="true"></budget>
    <cached-tags type="yaml" nil="true"></cached-tags>
    <color-hex>f1f353</color-hex>
    <created-at type="date time">2010-11-30T21:56:39Z</created-at>
    <enabled type="boolean">true</enabled>
    <id type="integer">34572</id>
    <import-id type="integer" nil="true"></import-id>
    <invoice-recipient-details nil="true"></invoice-recipient-details>
    <minutes type="integer">0</minutes>
    <name>Activity_1_doloressequiunde</name>
    <project-group-id type="integer" nil="true"></project-group-id>
    <stepping type="integer">15</stepping>
    <unbillable-minutes type="integer">0</unbillable-minutes>
    <updated-at type="date time">2011-10-19T15:59:56Z</updated-at>
    <user-id type="integer" nil="true"></user-id>
    <minutes type="integer">0</minutes>
    <budget-minutes nil="true"></budget-minutes>
    <remaining-minutes nil="true"></remaining-minutes>
    <unbillable-minutes type="integer">0</unbillable-minutes>
    <group-name nil="true"></group-name>
  </project>
  <!-- ...more projects... -->
</projects>

Response codes

If successful, the response code is 200 OK with the results of the call given in the response body.

Roles

All roles have access to this resource. For freelancers, only projects they have access to are returned.

Show project

GET /api/projects/<id>
JSON
XML
$ curl -v -H "X-FreckleToken:lx3gi6pxdjtjn57afp8c2bv1me7g89j" https://apitest.letsfreckle.com/api/projects/34572.json
Response:
{
   "project":{
      "name":"Activity_1_doloressequiunde",
      "unbillable_minutes":0,
      "created_at":"2010-11-30T21:56:39Z",
      "billable":true,
      "budget_minutes":null,
      "minutes":0,
      "cached_tags":null,
      "remaining_minutes":null,
      "updated_at":"2011-10-19T15:59:56Z",
      "import_id":null,
      "account_id":5039,
      "group_name":null,
      "minutes":0,
      "project_group_id":null,
      "id":34572,
      "enabled":true,
      "billable_minutes":0,
      "user_id":null,
      "unbillable_minutes":0,
      "color_hex":"f1f353",
      "budget":null,
      "stepping":15,
      "invoice_recipient_details":null
   }
}
$ curl -v -H "X-FreckleToken:lx3gi6pxdjtjn57afp8c2bv1me7g89j" https://apitest.letsfreckle.com/api/projects/34572.xml
Response:
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <account-id type="integer">5039</account-id>
  <billable type="boolean">true</billable>
  <billable-minutes type="integer">0</billable-minutes>
  <budget type="integer" nil="true"></budget>
  <cached-tags type="yaml" nil="true"></cached-tags>
  <color-hex>f1f353</color-hex>
  <created-at type="date time">2010-11-30T21:56:39Z</created-at>
  <enabled type="boolean">true</enabled>
  <id type="integer">34572</id>
  <import-id type="integer" nil="true"></import-id>
  <invoice-recipient-details nil="true"></invoice-recipient-details>
  <minutes type="integer">0</minutes>
  <name>Activity_1_doloressequiunde</name>
  <project-group-id type="integer" nil="true"></project-group-id>
  <stepping type="integer">15</stepping>
  <unbillable-minutes type="integer">0</unbillable-minutes>
  <updated-at type="date time">2011-10-19T15:59:56Z</updated-at>
  <user-id type="integer" nil="true"></user-id>
  <minutes type="integer">0</minutes>
  <budget-minutes nil="true"></budget-minutes>
  <remaining-minutes nil="true"></remaining-minutes>
  <unbillable-minutes type="integer">0</unbillable-minutes>
  <group-name nil="true"></group-name>
</project>

Response codes

If successful 200 OK with the project information in the response body is returned.

If the project is not known or the user doesn’t have access to the project, 404 Not found is returned.

Roles

All roles have access to this resource.

Activate project

GET /api/projects//active

(Re-)Activates an archived project.

JSON
$ curl -H "X-FreckleToken:lx3gi6pxdjtjn57afp8c2bv1me7g89j" https://apitest.letsfreckle.com/api/projects/2/active.json

Response codes

If successful or in case the project was already active, 200 OK with a Location is returned, pointing to the project.

Roles

Everyone except freelancers can activate projects.

Archive project

GET /api/projects/<id>/archive

Archive a project. Archived projects are “frozen” and time can’t be logged for them.

JSON
$ curl -H "X-FreckleToken:lx3gi6pxdjtjn57afp8c2bv1me7g89j" https://apitest.letsfreckle.com/api/projects/2/archive.json

Response codes

If successful or in case the project was already archived, 200 OK with a Location is returned, pointing to the project.

Roles

Everyone except freelancers can archive projects.

Create project

POST /api/projects
XML
$ curl -d @data/project.xml -H "Content-type: text/xml" -H "X-FreckleToken:lx3gi6pxdjtjn57afp8c2bv1me7g89j" https://apitest.letsfreckle.com/api/projects.xml
Post body:
<?xml version="1.0" encoding="UTF-8"?>
<project>
  <name>foobar</name>
</project>

Response codes

201 Created means that the project was successfully created in is now visible in Freckle. The Location header in the HTTP response contains the path to this new project in the API. This path contains the project ID which your application can store so it can use the project later in other API calls.

Here’s an example response:

HTTP/1.1 201 Created
Server: nginx/1.2.1
Date: Sun, 02 Dec 2012 20:56:54 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 1
Connection: keep-alive
Status: 201 Created
Location: /api/projects/3187878
X-Runtime: 33
Cache-Control: private, max-age=0, must-revalidate

422 Unprocessable Entity means the request data was not valid, for example a required field was omitted, a project with the same name already exists, or the 1 project limit of free Freckle accounts has been reached.

Roles

All roles except for the freelancer role can create projects.

Delete project

DELETE /api/projects/<id>

Only projects that do not have any entries, expenses or invoices can be deleted. We recommend to archive projects instead.

XML
$ curl -v -X DELETE -H "X-FreckleToken:lx3gi6pxdjtjn57afp8c2bv1me7g89j" https://apitest.letsfreckle.com/api/projects/2.xml

Response codes

If deletion is successful, 200 OK will be returned.

422 Unprocessable Entity means that one of the preconditions (no entries, expenses or invoices) was not met. A reason like Project has entries will be returned as plain text in the response body.

Roles

All roles except freelancers can delete projects.