Requests and Responses (LP Classic)

General RESTful API Resources and Methods

For background on RESTful APIs in general, see Wikipedia or another suitable reference.

HTTP Methods

If you want to	Then you should
fetch all instances of a resource	GET /api/v1/resource
fetch a single instance of the resource	GET /api/v1/resource/:id
create a new resource	POST /api/v1/resource
update an existing resource	PUT /api/v1/resource/:id
delete an existing resource	DELETE /api/v1/resource/:id

If your HTTP client does not implement the PUT and DELETE methods, then you can use a POST with an additional parameter named _method and a value of either PUT or DELETE.

For example, to delete a task using the POST method rather than the DELETE method, do:

% curl https://app.liquidplanner.com/api/workspaces/:id/tasks/:id?_method=DELETE -X POST

HTTP Status Codes

Check the HTTP status code of responses from the API to determine whether your request was processed successfully.

Success Codes

Status Code	Result
200 OK	successful read, update, or delete
201 Created	successful create

Error or Exception Codes

Status Code	Result
400 Bad Request	unrecognized or invalid request URL
401 Unauthorized	credentials not provided or are incorrect
422 Unprocessable Entity	unsuccessful create, update, or delete; syntactic or validation error
404 Not Found	record does not exist, or you do not have permission to access it
500 Internal Server Error	unexpected error; you've likely found a bug in LiquidPlanner
501 Not Implemented	you asked for an API version that is not implemented (either because it does not exist, or it has been deprecated)
503 Service Unavailable	API is disabled globally, or your account is throttled; check the error in the response body

Error Responses

Response Body

When returning an error, the response body contains details of the error represented as a JSON hash.

For example, requesting an invalid task id results in the following error response:

% curl https://app.liquidplanner.com/api/workspaces/12345/tasks/12345
{
  "type": "Error",
  "error": "NotFound",
  "message": "Record not found (or you don't have permission to access it)."
} 
 Status: 404 Not Found

Hash Keys of an Error Response

Key	Description
type	the literal string "Error"
error	specific kind of error, e.g. "NotFound" or "BadRequest"
message	descriptive or explanatory message

Writing via the API

Many, but not all, resources can be created or modified via the API. As a general rule, things that you can create or edit inside the “Projects” tab in the Web UI (tasks, projects, documents, comments, etc.) are also writable via the API.

On the other hand, administrative resources (members, workspace settings, activities, etc.) are in general not writable via the API.

When creating or modifying a resource, the payload should always be a JSON hash with a single root attribute: the lower-case name of the resource you are writing (except when dealing with the convenience methods, specified below). The value of that attribute should be a hash of all the attributes you’d like to write.

Create an item using POST, and update an item using PUT.

Resource Parameter

When creating or updating a resource, the API requires a request parameter with the same name as the resource (in the singular form), whose value is a hash of the resource’s attributes.

Putting together the HTTP methods, resource nesting, and the resource parameter, we have the following:

If you want to	Then you should	To	With a parameter
Create a Task	POST	/api/v1/workspaces/:workspace_id/tasks	task = ...hash
Create a Comment on a Task	POST	/api/v1/workspaces/:workspace_id/tasks/:task_id/comments	comment = ...hash
Update a Folder	PUT	/api/v1/workspaces/:workspace_id/folders/:folder_id	folder = ...hash

You can reference the available resources at: https://app.liquidplanner.com/api/v1/help/urls