Projects¶

10 endpoints. Authentication, errors, paging and rate limits are described once, in the API overview.

Action	Method	Description
`addprojectmessage`	POST	Add a message/comment to a project
`addprojecttask`	POST	Add a task to a project
`createproject`	POST	Create a new project
`deleteprojecttask`	POST	Delete a task from a project
`endtasktimer`	POST	Stop a task timer
`getproject`	GET	Get a single project with tasks and messages
`getprojects`	GET	List all projects
`starttasktimer`	POST	Start a task timer
`updateproject`	POST	Update a project's details
`updateprojecttask`	POST	Update a project task

addprojectmessage¶

Add a message/comment to a project.

POST /api/v1/addprojectmessage

Permission: manage_projects

Parameters

Name	Type	Required	Description
`projectid`	integer	yes	The project. project_id is accepted too.
`message`	string	yes	The message.

Response

Field	Description
`result`	`success`
`messageid`	integer

Errors

Status	When
404	No such project.

Note

Signed with the user name of the staff member the credential belongs to.

Example

curl -X POST https://example.com/api/v1/addprojectmessage \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "projectid=1" \
  --data-urlencode "message=example"

addprojecttask¶

Add a task to a project.

POST /api/v1/addprojecttask

Permission: manage_projects

Parameters

Name	Type	Required	Description
`projectid`	integer	yes	The project. project_id is accepted too.
`task`	string	yes	The task, up to 255 characters. title is accepted too.
`notes`	string	no	Details. description is accepted too.
`due_date`	date	no	Due date.

Response

Field	Description
`result`	`success`
`taskid`	integer

Errors

Status	When
404	No such project.

Example

curl -X POST https://example.com/api/v1/addprojecttask \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "projectid=1" \
  --data-urlencode "task=example"

createproject¶

Create a new project.

POST /api/v1/createproject

Permission: manage_projects

Parameters

Name	Type	Required	Description
`title`	string	yes	Up to 255 characters.
`clientid`	integer	yes	The client.
`status`	string	no	pending (default), in_progress, completed or cancelled.
`due_date`	date	no	Due date.
`description`	string	no	Description.

Response

Field	Description
`result`	`success`
`projectid`	integer

Note

Owned by the staff member the credential belongs to.

Example

curl -X POST https://example.com/api/v1/createproject \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "title=example" \
  --data-urlencode "clientid=1"

deleteprojecttask¶

Delete a task from a project.

POST /api/v1/deleteprojecttask

Permission: manage_projects

Parameters

Name	Type	Required	Description
`taskid`	integer	yes	The task.

Response

Field	Description
`result`	`success`

Errors

Status	When
404	No such task.

Example

curl -X POST https://example.com/api/v1/deleteprojecttask \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "taskid=1"

endtasktimer¶

Stop a task timer.

POST /api/v1/endtasktimer

Permission: manage_projects

Parameters

Name	Type	Required	Description
`timerid`	integer	yes	The timer.

Response

Field	Description
`result`	`success`
`timerid`	integer
`seconds`	integer: how long this timer ran
`task_total_seconds`	integer: all timers on the task

Errors

Status	When
404	No such timer.

Note

Ending a timer that has already ended changes nothing and reports it again.

Example

curl -X POST https://example.com/api/v1/endtasktimer \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "timerid=1"

getproject¶

Get a single project with tasks and messages.

GET /api/v1/getproject

Permission: list_projects

Parameters

Name	Type	Required	Description
`projectid`	integer	yes	The project. id is accepted too.

Response

Field	Description
`result`	`success`
`project`	object: the project with its client, messages, and tasks with their timers

Errors

Status	When
404	No such project.

Example

curl -G https://example.com/api/v1/getproject \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "projectid=1"

getprojects¶

List all projects.

GET /api/v1/getprojects

Permission: list_projects

Parameters

Name	Type	Required	Description
`userid`	integer	no	Only this client's projects.
`limitstart`	integer	no	Where the page starts. Default 0.
`limitnum`	integer	no	Page size, 1 to 250. Default 25.

Response

Field	Description
`result`	`success`
`totalresults`	integer: rows matching the filters
`startnumber`	integer: where this page starts
`numreturned`	integer: rows on this page
`data`	array: the rows

Note

Each project carries its client, tasks and messages.

Example

curl -G https://example.com/api/v1/getprojects \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET"

starttasktimer¶

Start a task timer.

POST /api/v1/starttasktimer

Permission: manage_projects

Parameters

Name	Type	Required	Description
`taskid`	integer	yes	The task.
`projectid`	integer	no	When sent, the task must belong to this project.

Response

Field	Description
`result`	`success`
`timerid`	integer
`taskid`	integer
`started_at`	ISO 8601 time

Errors

Status	When
404	No such task (in that project).
409	A timer is already running for this task and staff member.

Note

The timer belongs to the staff member the credential belongs to.

Example

curl -X POST https://example.com/api/v1/starttasktimer \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "taskid=1"

updateproject¶

Update a project's details.

POST /api/v1/updateproject

Permission: manage_projects

Parameters

Name	Type	Required	Description
`projectid`	integer	yes	The project. id is accepted too.
`title`	string	no	Up to 255 characters.
`description`	string	no	Description.
`status`	string	no	pending, in_progress, completed or cancelled.
`due_date`	date	no	Due date.

Response

Field	Description
`result`	`success`
`projectid`	integer

Errors

Status	When
404	No such project.

Example

curl -X POST https://example.com/api/v1/updateproject \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "projectid=1"

updateprojecttask¶

Update a project task.

POST /api/v1/updateprojecttask

Permission: manage_projects

Parameters

Name	Type	Required	Description
`taskid`	integer	yes	The task.
`task`	string	no	Up to 255 characters. title is accepted too.
`notes`	string	no	Details. description is accepted too.
`completed`	boolean	no	Mark it done or not done.
`due_date`	date	no	Due date.

Response

Field	Description
`result`	`success`
`taskid`	integer

Errors

Status	When
404	No such task.

Example

curl -X POST https://example.com/api/v1/updateprojecttask \
  -H "X-API-Key: $PNLCS_IDENTIFIER" \
  -H "X-API-Secret: $PNLCS_SECRET" \
  --data-urlencode "taskid=1"